claude-dev-env 1.38.1 → 1.40.0

package/skills/skill-builder/SKILL.md

@@ -1,32 +1,44 @@
 ---
 name: skill-builder
 description: >-
-  Orchestrates the complete skill-building lifecycle using evaluation-driven
-  development. Routes through gap analysis, eval creation, skill writing (via
-  skill-writer), subagent testing (via skill-creator infrastructure), and
-  iterative refinement. Use when creating new skills, improving existing skills,
-  or optimizing skill descriptions. Triggers: 'build a skill', 'new skill
-  workflow', 'improve this skill', 'optimize skill description', 'skill
-  development lifecycle'.
+  Orchestrates the complete skill-building lifecycle using best-practice-driven
+  development. Routes through type classification, folder scaffolding, skill
+  writing (via skill-writer), self-audit against a 38-point checklist, and
+  iterative refinement from real usage observations. Use when creating new
+  skills, improving existing skills, or optimizing skill descriptions.
+  Triggers: 'build a skill', 'new skill workflow', 'improve this skill',
+  'optimize skill description', 'skill development lifecycle'.
 ---
 
-@${CLAUDE_SKILL_DIR}/references/eval-driven-flow.md
-
 # Skill Builder
 
-**Core principle:** Evaluation-driven development. Build evals BEFORE writing extensive documentation. This ensures skills solve real problems rather than documenting imagined ones.
+**Core principle:** Best-practice-driven craftsman. Knows every proven pattern, applies them intentionally, self-audits after building. The expert that enforces craft standards.
+
+Sources: [Anthropic best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), [Lessons from Building Claude Code](references/thariq-x-post-skills.json), model skills (bugteam, pr-converge).
+
+## Gotchas
 
-Source: [Anthropic Skill Best Practices - Evaluation and Iteration](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration)
+Highest-signal content. Append a bullet each time a skill build fails in a new way.
+
+> "The highest-signal content in any skill is the Gotchas section. These sections should be built up from common failure points that Claude runs into when using your skill."
 
 ## When this skill applies
 
-Trigger for requests to **build**, **improve**, or **polish** a skill through the full evaluation-driven lifecycle. This skill orchestrates the process -- it delegates writing to `/skill-writer` and evaluation infrastructure to the `skill-creator` plugin.
+Trigger for requests to **build**, **improve**, or **polish** a skill. This skill orchestrates the process — it classifies, scaffolds, gathers context, delegates writing to `/skill-writer`, and self-audits the result.
 
 For quick skill syntax questions or one-off SKILL.md edits, use `/skill-writer` directly instead.
 
-## Routing
+**Refusal cases — first match wins:**
+
+- **No clear task or domain.** Respond exactly: `What should this skill do? Give me a one-sentence description of the capability.`
 
-Assess the user's intent from conversation context and existing artifacts. Route directly:
+## The Process
+
+Each workflow file provides step-by-step instructions. After routing below, open the corresponding workflow file and follow it.
+
+### Routing
+
+Assess the user’s intent:
 
 **Creating a new skill?**
 Read `${CLAUDE_SKILL_DIR}/workflows/new-skill.md` and follow it.
@@ -34,74 +46,144 @@ Read `${CLAUDE_SKILL_DIR}/workflows/new-skill.md` and follow it.
 **Improving an existing skill?**
 Read `${CLAUDE_SKILL_DIR}/workflows/improve-skill.md` and follow it.
 
-**Final polish only (description optimization, trigger eval)?**
+**Final polish only (description optimization, trigger audit)?**
 Read `${CLAUDE_SKILL_DIR}/workflows/polish-skill.md` and follow it.
 
 **Ambiguous?** Ask: "Are you creating a new skill, improving an existing one, or doing a final polish pass?"
 
-## The Claude A / Claude B Pattern
+### The Claude A / Claude B pattern
+
+You and the user are **Claude A** — the expert who designs and refines the skill. Subagents running the built skill on real tasks are **Claude B** — the agent using the skill to perform actual work.
+
+> "Work with one instance of Claude (‘Claude A’) to create a Skill that is used by other instances (‘Claude B’). Claude A helps you design and refine instructions, while Claude B tests them in real tasks."
+
+The feedback loop: observe Claude B’s behavior, bring insights back, refine the skill, test again.
+
+## Skill type routing
+
+> "After cataloging all of our skills, we noticed they cluster into a few recurring categories."
+
+Classify the skill into one of 9 types. The type determines folder structure. See `${CLAUDE_SKILL_DIR}/references/skill-types.md` for full details.
+
+| # | Type | Key folders |
+|---|---|---|
+| 1 | Library & API Reference | reference/, examples/ |
+| 2 | Product Verification | scripts/, reference/ |
+| 3 | Data Fetching & Analysis | reference/, scripts/ |
+| 4 | Business Process & Team Automation | templates/, scripts/ |
+| 5 | Code Scaffolding & Templates | templates/, scripts/ |
+| 6 | Code Quality & Review | reference/, scripts/ |
+| 7 | CI/CD & Deployment | workflows/, scripts/ |
+| 8 | Runbooks | reference/, templates/ |
+| 9 | Infrastructure Operations | reference/, scripts/ |
+
+## Principles
+
+These are non-negotiable. Every skill must satisfy them. The self-audit checklist enforces them.
+
+### Concision and defaults
+
+> "Default assumption: Claude is already very smart. Only add context Claude doesn’t already have."
+
+> "Don’t State the Obvious — focus on information that pushes Claude out of its normal way of thinking."
+
+Challenge each sentence: "Does Claude really need this?"
+
+### Degree of freedom
+
+> "Match the level of specificity to the task’s fragility and variability."
+
+High freedom (text guidance) for open fields. Low freedom (exact scripts, no parameters) for narrow bridges with cliffs.
+
+> "Avoid Railroading Claude — give Claude the information it needs, but give it the flexibility to adapt."
+
+### Progressive disclosure
+
+> "Keep SKILL.md body under 500 lines."
+
+SKILL.md is a hub. Detail lives in reference/, scripts execute without being read into context. References one level deep. Files over 100 lines get a TOC. Forward slashes only.
+
+See `${CLAUDE_SKILL_DIR}/references/progressive-disclosure.md` for the full specification.
+
+### Description field
+
+> "Always write in third person. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills."
+
+Include what the skill does AND specific trigger phrases. Max 1024 chars.
+
+> "The description field is not a summary — it’s a description of when to trigger."
+
+### Gotchas
+
+> "Build a Gotchas Section — the highest-signal content in any skill."
+
+Mandatory section. Built from real failure observations. Updated over time as new failure modes surface.
+
+### Templates and examples
 
-You and the user are **Claude A** -- the expert who designs and refines the skill. Subagents running the built skill on eval tasks are **Claude B** -- the agent using the skill to perform real work.
+> "Provide templates for output format" and "Examples help Claude understand the desired style and level of detail more clearly than descriptions alone."
 
-> "Work with one instance of Claude ('Claude A') to create a Skill that is used by other instances ('Claude B'). Claude A helps you design and refine instructions, while Claude B tests them in real tasks."
+Use the template pattern for structured outputs. Use the examples pattern (input/output pairs) for style-dependent work.
 
-The feedback loop: observe Claude B's behavior, bring insights back, refine the skill, test again.
+### Workflows and checklists
 
-## Phase Overview
+> "For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses."
 
-| Phase | Purpose | Delegated To |
-|-------|---------|-------------|
-| 1. Identify gaps | Document what fails without the skill | This skill (guided conversation) |
-| 2. Build evals | Create 3+ scenarios testing the gaps | This skill (templates + user input) |
-| 3. Write skill | Minimal instructions addressing gaps | `/skill-writer` |
-| 4. Test | Subagent runs with/without skill, grade, benchmark | `skill-creator` eval infrastructure |
-| 5. Iterate | Review results, refine, re-test | This skill + `/skill-writer` + Phase 4 |
-| 6. Polish | Description optimization, trigger eval, final check | `skill-creator` description optimizer |
+Multi-step processes get `[ ]` checklists. Quality-critical operations get feedback loops (run validator → fix → repeat).
 
-## Ground-up skill package (required reference)
+### Scripts
 
-When building a **new** skill as a **full package** (architecture inventory, progressive disclosure files, `evals/`, **human checkpoint after each file**), treat the following as **mandatory** before implementation:
+> "Handle error conditions rather than punting to Claude." "Make clear whether Claude should execute the script or read it as reference."
 
-- **Read:** the installed `@jl-cmd/prompt-generator` template `prompt-generator/templates/skill-from-ground-up.md` (upstream repository path: `skills/prompt-generator/templates/skill-from-ground-up.md` in [jl-cmd/prompt-generator](https://github.com/jl-cmd/prompt-generator)).
-- **Do:** Run `/prompt-generator` using that installed template with the file’s token table filled so the downstream session follows architecture-first sequencing, per-file review gates, and eval rows tied only to user-pasted or explicitly approved evidence.
+> "One of the most powerful tools you can give Claude is code — letting Claude spend its turns on composition rather than reconstructing boilerplate."
 
-Use this **together with** gap-analysis and eval-scenario templates in this package; the ground-up template supplies the **orchestration contract** for the multi-file layout Anthropic recommends.
+### Setup and memory
 
-## Refinement skill package (required reference)
+> "Think through the Setup — some skills may need to be set up with context from the user. A good pattern is to store this in a config.json file."
 
-When **improving** an existing skill as a **multi-file** or **checkpointed** package (baseline directory plus planned deltas, observation-grounded evals), treat the following as **mandatory** before Phase 2–6 file work in `improve-skill.md` or package-aware steps in `polish-skill.md`:
+> "Data stored in the skill directory may be deleted when you upgrade the skill, so store persistent data in `${CLAUDE_PLUGIN_DATA}`."
 
-- **Read:** `prompt-generator/templates/skill-refinement-package.md` (repository path: `skills/prompt-generator/templates/skill-refinement-package.md` in [jl-cmd/prompt-generator](https://github.com/jl-cmd/prompt-generator)).
-- **Do:** Run `/prompt-generator` with that file’s token table filled (`[[BASELINE_SKILL_ROOT]]`, `[[WORKSPACE_ROOT]]`, observation gap path, evidence rule) so rollout stays architecture-first, delta-focused, and tied to real observation or approved excerpts.
+### Constraints and refusal cases
 
-Net-new packages without a baseline skill directory use `skill-from-ground-up.md` instead.
+> bugteam pattern — non-negotiables separated from guidance, with design rationale. Explicit "first match wins" refusal conditions.
 
-## Principles (apply across all phases)
+### Anti-patterns
 
-1. **Evals before documentation.** Never write extensive skill content without evaluation scenarios to validate it.
+> No Windows paths. Don’t offer too many options — provide a default with escape hatch. Avoid time-sensitive claims. Use consistent terminology. No deeply nested references.
 
-2. **Minimal instructions first.** Write just enough to pass evaluations. Resist the urge to over-document.
+## Self-audit
 
-3. **Generalize from feedback.** The skill will be used across many prompts. Do not overfit to test cases.
+After every build, improvement, or polish pass, run the mandatory checklist at `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`. Every item must pass before delivery. Fix failures, then re-audit.
 
-4. **Explain the why.** Theory of mind beats rigid rules. Help the model understand reasoning, not just constraints.
+## Delegation to skill-writer
 
-5. **Observe, do not assume.** Iterate based on what Claude B actually does, not what you think it should do.
+skill-builder orchestrates; skill-writer authors. The handoff packet from Step 4 must include:
 
-## Delegation Details
+- Skill type and folder structure
+- Gap analysis or observation findings
+- Degree of freedom assessment
+- Initial gotchas
+- Any constraints
 
-See `${CLAUDE_SKILL_DIR}/references/delegation-map.md` for exact invocation patterns and integration points between this orchestrator, `/skill-writer`, and `skill-creator`.
+See `${CLAUDE_SKILL_DIR}/references/delegation-map.md` for exact patterns.
 
-## File Index
+## File index
 
 | File | Purpose |
 |------|---------|
-| `workflows/new-skill.md` | Full lifecycle for new skills (6 phases) |
-| `workflows/improve-skill.md` | Observation-first flow for existing skills |
-| `workflows/polish-skill.md` | Description optimization and final validation |
-| `references/eval-driven-flow.md` | Official Anthropic methodology with citations |
-| `references/delegation-map.md` | Integration map for skill-writer and skill-creator |
-| `templates/gap-analysis.md` | Template for Phase 1 gap documentation |
-| `templates/eval-scenario.json` | Eval template matching skill-creator schema |
-| `../prompt-generator/templates/skill-from-ground-up.md` | Required orchestration template for **net-new** full skill packages (architecture-first, checkpoints, evidence-backed evals) |
-| `../prompt-generator/templates/skill-refinement-package.md` | Required orchestration template for **existing-skill** multi-file refinements and package-aware polish (baseline + delta, checkpoints, evidence-backed evals) |
+| `SKILL.md` | This hub — principles, process, routing, file index |
+| `references/skill-types.md` | 9-type taxonomy with folder structures per type |
+| `references/progressive-disclosure.md` | Folder conventions, hub pattern, hard rules |
+| `references/self-audit-checklist.md` | 38-point mandatory post-build audit |
+| `references/delegation-map.md` | Subagent handoff patterns and transcript guidance |
+| `workflows/new-skill.md` | Full lifecycle for new skills (6 steps) |
+| `workflows/improve-skill.md` | Observation-first flow for existing skills (6 steps) |
+| `workflows/polish-skill.md` | Description audit and final validation (5 steps) |
+| `templates/gap-analysis.md` | Template for documenting skill gaps |
+
+## Folder map
+
+- `SKILL.md` — hub.
+- `references/` — best-practice specifications and the audit checklist.
+- `workflows/` — step-by-step workflows for each lifecycle phase.
+- `templates/` — reusable templates for skill artifacts.

package/skills/skill-builder/references/delegation-map.md

@@ -1,153 +1,112 @@
 # Delegation Map
 
-How the skill-builder orchestrator integrates with external skills at each phase.
+How skill-builder delegates work to subagents and `/skill-writer`.
 
-## Phase 1: Identify Gaps -- This Orchestrator
+## Delegating to skill-writer (Step 4)
 
-No external delegation. The orchestrator guides a conversation with the user to document what fails without a skill.
+skill-builder orchestrates; skill-writer authors the SKILL.md and companion files. The handoff must be structured so skill-writer has everything it needs.
 
-**Output:** `[skill-name]-workspace/gap-analysis.md` using the template at `templates/gap-analysis.md`.
-
-## Phase 2: Build Evals -- This Orchestrator
-
-No external delegation. The orchestrator helps the user transform gaps into eval scenarios.
-
-**Output:** `[skill-name]-workspace/evals/evals.json` using the template at `templates/eval-scenario.json`.
-
-**Baseline runs:** Spawn subagents WITHOUT any skill for each eval scenario. These run as background Agent tasks.
-
-## Phase 3: Write Skill -- Delegate to `/skill-writer`
-
-**Full package path:** If the user approved a package plan from `prompt-generator/templates/skill-from-ground-up.md` (net-new) or `prompt-generator/templates/skill-refinement-package.md` (existing baseline), paste the approved architecture summary, baseline inventory, planned deltas, and checkpoint list into the skill-writer handoff so file order and scope stay aligned.
-
-Invoke `/skill-writer` with the following context in your prompt:
+### New skill handoff
 
 ```
-Create a skill based on this gap analysis and eval scenarios.
-
-Gap analysis: [paste or reference gap-analysis.md]
-Eval scenarios: [paste or reference evals.json expected_output fields]
-Baseline failures: [summarize what Claude got wrong without the skill]
-
-Constraint: Write the minimum instructions needed to address these specific gaps.
-Do not over-document. Every line must serve a documented gap.
+Create a skill with these parameters:
+
+**Skill type:** [one of 9 types from skill-types.md]
+**Folder structure:** [directories to create: reference/, scripts/, etc.]
+**What it does:** [one-sentence capability description]
+**Domain context:** [what Claude needs to know that it doesn't already]
+**Initial gotchas:** [failure patterns to document from the start]
+**Degree of freedom:** [high | medium | low — with reasoning]
+**Constraints:** [non-negotiables]
+
+Produce:
+1. SKILL.md with hub layout (principle, gotchas, when-applies, process, file index, folder map)
+2. Companion files as needed (reference docs, workflow steps, templates)
+3. Every file under 500 lines; TOC on files over 100 lines
+4. File index listing every file and its purpose
 ```
 
-skill-writer handles: type classification, degree of freedom, frontmatter, body structure, progressive disclosure, self-check.
-
-**Output:** The skill's SKILL.md (and optional REFERENCE.md, scripts, etc.)
-
-## Phase 4: Test -- Delegate to skill-creator Infrastructure
-
-The skill-creator plugin provides the eval infrastructure. Reference its components directly:
-
-### Spawning test runs
+### Refine skill handoff
 
-For each eval, spawn TWO subagents in the SAME turn (parallel):
-
-**With-skill subagent:**
-```
-Execute this task:
-- Read the skill at [path-to-skill]/SKILL.md and follow its instructions
-- Task: [eval prompt from evals.json]
-- Input files: [eval files if any]
-- Save all output files to: [workspace]/iteration-N/eval-[name]/with_skill/outputs/
-- Save a transcript of your complete work to: [workspace]/iteration-N/eval-[name]/with_skill/transcript.md
-- At the end, write a metrics.json with tool call counts and file list
 ```
+Refine this existing skill:
 
-**Without-skill subagent** (baseline):
-For iteration-1, reuse baseline results from Phase 2 (iteration-0). For later iterations, the original baseline persists.
-
-### Grading
-
-Read the grading agent instructions from the skill-creator plugin:
-`[skill-creator-plugin-path]/agents/grader.md`
-
-Spawn a grader subagent for each run with:
-- The expectations from evals.json
-- The transcript path
-- The outputs directory
-
-**Output:** `grading.json` in each run directory.
-
-### Benchmarking
+**Current SKILL.md:** [reference or paste]
+**What was observed:** [specific failures from Claude B usage]
+**What to change:** [specific instructions to add/remove/modify]
+**New gotchas to add:** [failure patterns discovered]
+**What to preserve:** [working content — do not touch]
 
-Run the aggregation script from the skill-creator plugin directory:
-```bash
-cd [skill-creator-plugin-path] && python -m scripts.aggregate_benchmark [workspace]/iteration-N --skill-name [name]
+Constraint: Only change what the observations demand. Do not reorganize working content.
 ```
 
-**Output:** `benchmark.json` and `benchmark.md` in the iteration directory.
+## Spawning a test subagent
 
-### Eval Viewer
+To observe how Claude B uses a skill on a real task:
 
-Launch the viewer from the skill-creator plugin:
-```bash
-python [skill-creator-plugin-path]/eval-viewer/generate_review.py \
-  [workspace]/iteration-N \
-  --skill-name "[name]" \
-  --benchmark [workspace]/iteration-N/benchmark.json
 ```
+Agent(
+  subagent_type="general-purpose",
+  description="Test skill on real task",
+  prompt="Read the skill at [skill-path]/SKILL.md and follow its instructions.
 
-For iteration 2+, add: `--previous-workspace [workspace]/iteration-[N-1]`
+Task: [realistic user prompt]
 
-If no browser/display available, add: `--static [workspace]/iteration-N/review.html`
+Save a complete transcript of your work to: [workspace]/transcript.md"
+)
+```
 
-**Output:** Browser-based reviewer where the user inspects outputs and leaves feedback.
+Spawn with `run_in_background=true` for longer tasks. Read the transcript when the agent completes.
 
-### Finding the skill-creator plugin path
+## Reading a transcript for observations
 
-The skill-creator plugin is installed at a path like:
-`~/.claude/plugins/marketplaces/claude-plugins-official/plugins/skill-creator/skills/skill-creator/`
+> "Watch for unexpected exploration paths, missed connections, overreliance on certain sections, and ignored content."
 
-To find it dynamically, search for the skill-creator SKILL.md:
-```bash
-find ~/.claude/plugins -name "SKILL.md" -path "*/skill-creator/*" 2>/dev/null | head -1
-```
+Scan the transcript for:
 
-Then derive the plugin root from that path.
+1. **File access order** — Did Claude read files in the expected order? Unexpected ordering means the structure is not intuitive.
+2. **Missed files** — Were any reference files never accessed? They might be unnecessary or poorly signaled.
+3. **Re-read files** — Did Claude re-read the same file multiple times? That content should be in SKILL.md.
+4. **Gotcha moments** — Where did Claude make a wrong choice? That's a gotcha candidate.
+5. **Script usage** — Did Claude execute scripts as expected, or did it try to read them instead?
+6. **Tool call errors** — Any "tool not found" or path errors? Fix references.
 
-## Phase 5: Iterate -- This Orchestrator + `/skill-writer`
+## Delegating self-audit
 
-The orchestrator reads feedback.json and transcripts, synthesizes observations, then delegates refinement to `/skill-writer`:
+After building, spawn a subagent to run the checklist independently:
 
 ```
-Refine this existing skill based on these observations from testing.
+Agent(
+  subagent_type="general-purpose",
+  description="Self-audit skill against checklist",
+  prompt="Read the skill at [skill-path]/SKILL.md and all companion files.
 
-Current SKILL.md: [paste or reference]
-User feedback: [from feedback.json]
-Behavioral observations: [from transcript analysis]
+Then read the self-audit checklist at [skill-builder-path]/references/self-audit-checklist.md.
 
-Specific issues to address:
-1. [Issue from feedback]
-2. [Issue from observation]
+Check every item. For each: PASS, FAIL with specific file:line evidence and what to fix, or N/A with reason.
 
-Constraint: Only change what the feedback demands. Do not reorganize working content.
+Report as:
+## Audit Results
+[ ] Item 1: PASS
+[ ] Item 2: FAIL — [file:line] — [what's wrong and how to fix]
+..."
+)
 ```
 
-Then return to Phase 4 with the refined skill.
-
-## Phase 6: Polish -- Delegate to skill-creator Description Optimizer
+This gives an independent verification. Fix failures, then re-deliver to user.
 
-The skill-creator plugin includes a description optimization loop:
+## Testing across models
 
-### Trigger eval generation
+> "Test your Skill with all the models you plan to use it with."
 
-Generate 20 realistic eval queries (10 should-trigger, 10 should-not-trigger). Use the HTML review template from:
-`[skill-creator-plugin-path]/assets/eval_review.html`
+If the skill will be used with Haiku, spawn a haiku test subagent:
 
-### Optimization loop
-
-```bash
-cd [skill-creator-plugin-path] && python -m scripts.run_loop \
-  --eval-set [path-to-trigger-eval.json] \
-  --skill-path [path-to-skill] \
-  --model [current-model-id] \
-  --max-iterations 5 \
-  --verbose
+```
+Agent(
+  subagent_type="general-purpose",
+  model="haiku",
+  ...
+)
 ```
 
-### Final validation
-
-Run the skill-writer self-check rubric (from skill-writer's Step 9) against the finished skill. All items must pass.
+Haiku needs more explicit guidance than Opus. Observe whether the skill provides enough.

package/skills/skill-builder/references/progressive-disclosure.md

@@ -0,0 +1,122 @@
+# Progressive Disclosure
+
+Source A: [Anthropic — Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+Source B: [Lessons from Building Claude Code](thariq-x-post-skills.json)
+
+## Core concept
+
+> Source A: "SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide."
+
+> Source A: "At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed."
+
+> Source B: "You should think of the entire file system as a form of context engineering and progressive disclosure."
+
+## Standard folder conventions
+
+Every skill is a folder. These are the standard subdirectories, each with a specific role:
+
+| Directory | Purpose | When to use |
+|---|---|---|
+| `SKILL.md` | Hub — overview, gotchas, process, file index | Always |
+| `reference/` | Deep-dive reference material loaded on demand | Domain knowledge, API surfaces, schemas |
+| `scripts/` | Executable scripts (executed, not read into context) | Deterministic operations, validators, helpers |
+| `workflows/` | Multi-step sub-workflows for different scenarios | Complex branching processes |
+| `templates/` | Output templates or file scaffolds to copy and fill | Structured output formats |
+| `assets/` | Static data files, images, config templates | Reference data, configuration |
+| `examples/` | Copy-pasteable examples and usage patterns | Library/API reference skills |
+
+> Source A: "As your Skill grows, you can bundle additional content that Claude loads only when needed."
+
+> Source B: "The simplest form of progressive disclosure is to point to other markdown files for Claude to use."
+
+## The hub pattern
+
+SKILL.md is an index, not a textbook. It tells Claude what exists and when to read it.
+
+Observed in model skills (bugteam, pr-converge), the proven layout:
+
+1. Core principle (one sentence)
+2. Gotchas (highest-signal content)
+3. When this skill applies (trigger + refusal)
+4. The Process (checklist)
+5. Skill type routing (if applicable)
+6. Principles / constraints
+7. File index (what every file does)
+8. Folder map (end of file)
+
+> Source B: "Tell Claude what files are in your skill, and it will read them at appropriate times."
+
+## Three progressive disclosure patterns
+
+### Pattern 1: High-level guide with references
+
+> Source A: "Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed."
+
+```markdown
+## Quick start
+[essential content inline]
+
+## Advanced features
+**Form filling**: See [FORMS.md](FORMS.md)
+**API reference**: See [REFERENCE.md](REFERENCE.md)
+**Examples**: See [EXAMPLES.md](EXAMPLES.md)
+```
+
+### Pattern 2: Domain-specific organization
+
+> Source A: "When a user asks about sales metrics, Claude only needs to read sales-related schemas, not finance or marketing data."
+
+```markdown
+**Finance**: Revenue, ARR → See [reference/finance.md](reference/finance.md)
+**Sales**: Pipeline, accounts → See [reference/sales.md](reference/sales.md)
+**Product**: API usage, features → See [reference/product.md](reference/product.md)
+```
+
+### Pattern 3: Conditional details
+
+> Source A: "Show basic content, link to advanced content."
+
+```markdown
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+## Hard rules
+
+### 500-line cap on SKILL.md body
+
+> Source A: "Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files."
+
+### One level deep
+
+> Source A: "Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md."
+
+> Source A: "Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information."
+
+**Bad:** `SKILL.md → advanced.md → details.md`
+**Good:** `SKILL.md → advanced.md`, `SKILL.md → details.md`
+
+### TOC for files over 100 lines
+
+> Source A: "For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads."
+
+### Forward slashes only
+
+> Source A: "Always use forward slashes in file paths, even on Windows. Unix-style paths work across all platforms."
+
+## File naming conventions
+
+> Source A: "Name files descriptively: Use names that indicate content: `form_validation_rules.md`, not `doc2.md`."
+
+> Source A: "Organize for discovery: Structure directories by domain or feature. Good: `reference/finance.md`, `reference/sales.md`. Bad: `docs/file1.md`, `docs/file2.md`."
+
+## Scripts: execute vs read
+
+> Source A: "Make clear in your instructions whether Claude should execute the script or read it as reference."
+
+- **Execute:** "Run `analyze_form.py` to extract fields"
+- **Read as reference:** "See `analyze_form.py` for the extraction algorithm"
+
+> Source A: "For most utility scripts, execution is preferred because it's more reliable and efficient."