codebase-diagnostic

skills-registry-site

A two-tier field guide to a set of Claude skills:

• Public field guide (this build) — a calm, plain-language static site that teaches the generalized method of each skill. Built from portable Markdown, deployed to GitHub Pages. Only content explicitly tagged public is ever rendered (default-deny).
• Private workshop (a later milestone) — work-sensitive examples, work-specific reference, and team votes. Not in this repo yet; the public build is structured so a later step can publish only the public output to a separate repo without rework.

Source of truth is plain Markdown + per-skill metadata. Edit metadata, push, the site rebuilds. Host lock-in is near zero — swapping hosts is a DNS change plus a redeploy (see docs/HOSTING.md).

The visual language, design tokens, the value the site trades for the reader's time, and the constraints a design/frontend contributor must respect are documented in docs/DESIGN.md.

The two public views

View 1 — skill entry (/skills/<name>/, one page per published skill): header (name · one-line situation · health badge) → trust strip (used N× · helpful % · reviewed date) → Use it when → What you type (a literal, copyable prompt) → What you get back → See it work (a synthetic, sanitized before→after, plus a locked "team only" real-examples stub) → Where it trips → footer (team-only action stubs + a collapsed Technical reference disclosure whose work-specific portion is a locked stub).

View 2 — adaptive list (/, the home/index): a role-aware list of the published skills. Pick a role (URL ?role=test-eng, or a remembered choice) to get a "For your role · N" band; "Everything · N" lists them all. Sort toggle: For you / Top / New. With no role the default sort is Top (by helpful% then used). Role/sort behaviour is client-side; the page renders the Top list with no JS.

The legacy audit views (picker, map, health, registry, audit) still exist as an internal tool — see Internal audit tool below.

The data contract

Each skill is a directory under skills/<name>/:

File	Role	Visibility
SKILL.md	stub; frontmatter name + description (real body lives in Claude.ai)	—
.meta.yaml	audit metadata + the opt-in public: block	everything outside public: is private
guide.md	field-guide prose, split into visibility-tagged sections	per-section {visibility=public|private}
data/trust-stats.json	stub trust numbers, keyed by skill name	public

.meta.yaml → the public: block

A skill is published only if it has public.visibility: public. Everything else in .meta.yaml (status, frustration, reasoning-note, …) stays private and is never emitted.

# ...existing private audit fields stay exactly as-is...
public:
  visibility: public            # REQUIRED to publish. Omit the block ⇒ private.
  situation: "Plain-language, one line."   # REQUIRED
  health: healthy               # healthy | new  → green | amber dot. REQUIRED.
  roles: [test-eng, analyst]    # REQUIRED (may be []). Drives View 2's role band.
  domain_tag: device            # optional; defaults to the top-level `domain`.
  what_you_type: |              # REQUIRED — the literal, copyable prompt.
    analyze this data: <paste your TSV/CSV>
  what_you_get: "One short paragraph describing the output shape."  # REQUIRED

Valid roles: test-eng, analyst, researcher, dev, pm. Health: healthy | new.

guide.md → visibility-tagged sections

H2 headings carry a visibility annotation. Missing annotation ⇒ private (default-deny). Required public sections (the build fails loudly without them): Use it when, See it work, Where it trips, Technical reference — method.

## Use it when {visibility=public}
- plain-language triggers

## See it work {visibility=public}
before → after (synthetic, sanitized)

## Real examples {visibility=private}
STUB — drives a locked "team only" placeholder; body never leaves the source.

## Where it trips {visibility=public}
failure modes, as method

## Technical reference — method {visibility=public}
generalized triggers / precedence / related

## Technical reference — work-specific {visibility=private}
STUB — drives the locked work-specific disclosure.

data/trust-stats.json (stub seam)

{ "research-brief": { "used": 58, "helpful_pct": 93, "reviewed": "2026-05-27",
                      "total_votes": 15, "real_examples": 4, "worked_for_me": 12 } }

used + reviewed are required per entry; helpful_pct: null renders as "new". A published skill with no entry fails the build. This file is the only thing a later milestone swaps to plug in real aggregated votes — the lookup (src/lib/trust-stats.ts, getTrustStats(name)) and shape stay the same.

Privacy: default-deny + the leak test