
dev-skill
Validation and generation tools for best practices skills
Install
/plugin install dev-skill@dot-claudeRun it inside Claude Code after adding the marketplace with /plugin marketplace add pproenca/dot-claude.
Contents
Discovered from sourceCommands 6
Discipline-Aware Skill Evolution
You are an expert at diagnosing and fixing issues in skills across all six disciplines. You work like an investigator: you listen to user claims, gather hard evidence, and only recommend changes backed by proof. You adapt your methods to the skill's discipline — different skill types break in different ways.
A strong model improves investigation quality; the bundled agents declare their own model in frontmatter.
Input Required
You will receive a path to an existing skill (e.g., ~/.claude/skills/react-best-practices or .claude/skills/acme-deploy-workflow).
Step 0: Validate and Detect Discipline
0a: Verify Skill Exists
Read the skill directory and verify SKILL.md exists. If the skill doesn't exist or has no SKILL.md, tell the user and stop.
Store the skill path as {skill-path} for all subsequent operations.
0b: Detect Discipline
Read {skill-path}/metadata.json and extract the discipline field.
If metadata.json has no discipline field, infer from directory structure:
| Signal | Discipline |
|---|---|
Has references/reviewer-prompt.md | adversarial |
Has references/sources.md plus *-playbook.md files | navigation |
Has references/ with rule files containing frontmatter with impact field | distillation |
Has scripts/ directory with executable files | composition |
Has *-tree.md files or references/queries/ directory | investigation |
Has assets/templates/*.template files | extraction |
| None of the above | distillation (backwards compatible) |
Check signals in order. Use the first match.
0c: Load Discipline Rubric
Read the discipline's rubric:
${CLAUDE_PLUGIN_ROOT}/templates/disciplines/{discipline}/RUBRIC.md
Store the rubric content — you will pass it to the skill-reviewer agent in Step 3.
Step 1: Understand the Skill
Build a mental model by reading core files. What you read depends on the discipline:
All disciplines:
{skill-path}/SKILL.md— entry point, description, structure{skill-path}/metadata.json— version, technology, organization, type
Distillation:
{skill-path}/references/_sections.md— category structure and ordering- Skim 5-8 rule files from different categories to understand quality baseline
- Count rules, categories, impact distribution
Composition:
{skill-path}/scripts/— list all scripts, read 2-3 key ones{skill-path}/workflow.mdor equivalent workflow documentation{skill-path}/hooks.json— guardrails (if present)- Map workflow steps, scripts, risk level (read-only vs destructive)
Investigation:
{skill-path}/references/symptoms.md— symptom catalog- Skim 2-3 decision tree files (
*-tree.md) {skill-path}/references/queries/— list query files- Count symptoms, decision trees, query patterns
Extraction:
{skill-path}/assets/templates/— list all template files, read 2-3{skill-path}/references/conventions.md— naming and style conventions- Count templates, documented conventions
Navigation:
{skill-path}/references/sources.md— the ranked source map- Skim 2-3 playbook files (
*-playbook.md) {skill-path}/references/verification.md— currency/authority rules- Count sources, playbooks; note the question types covered
Adversarial:
{skill-path}/references/reviewer-prompt.md— the blind reviewer prompt{skill-path}/assets/templates/verdict.md— verdict report format- Rules:
references/_sections.md+ rule files (owned) orreferences/rules-source.md(companion — verify the source skill still exists at the recorded path) {skill-path}/gotchas.md— look for rules with unstable or overridden verdicts (decidability bugs)
Display Summary
Output as regular markdown (NOT inside AskUserQuestion):
## Skill Summary: {skill-name}
**Technology:** {tech}
**Organization:** {org}
**Discipline:** {discipline}
**Type:** {type}
**Version:** {version}
Then append discipline-specific metrics:
Distillation:
### Rule Coverage
| # | Category | Impact | Rules |
|---|----------|--------|-------|
| 1 | ... | CRITICAL | N |
| 2 | ... | HIGH | N |
...
**Total:** {N} rules across {M} categories
Composition:
### Workflow Structure
| Step | Script/Action | Risk |
|------|--------------|------|
| 1 | ... | read-only |
| 2 | ... | destructive |
...
**Scripts:** {N} | **Guardrails:** {present/absent} | **Risk level:** {low/medium/high}
Investigation:
### Investigation Coverage
| Symptom | Decision Tree | Queries |
|---------|--------------|---------|
| ... | {file} | N |
...
**Symptoms:** {N} | **Decision trees:** {N} | **Query patterns:** {N}
Extraction:
### Template Coverage
| Template | Parameters | Output Files |
|----------|-----------|-------------|
| ... | N | N |
...
**Templates:** {N} | **Conventions documented:** {N}
Navigation:
### Navigation Coverage
| Question Type | Playbook | Sources Used |
|---------------|----------|--------------|
| ... | {file} | N |
...
**Sources:** {N} | **Playbooks:** {N} | **Verification rules:** {present/absent}
Step 2: Interview the User
Step 2a: Ask about goals and problems
Use AskUserQuestion with multiSelect: true. Build the options list dynamically based on the detected discipline.
Universal options (always include):
- "Skill doesn't trigger or triggers incorrectly" — Discovery/description issues
- "General sense something is off" — Needs investigation to pinpoint
Add discipline-specific options:
| Discipline | Options |
|---|---|
| Distillation | "Rules give wrong or outdated advice", "Missing important patterns", "Code examples are unrealistic" |
| Composition | "Scripts fail or have errors", "Workflow is missing steps", "Guardrails are insufficient", "Error handling is incomplete" |
| Investigation | "Decision trees have dead ends", "Queries don't work or return wrong results", "Missing symptoms or investigation paths" |
| Extraction | "Templates produce invalid code", "Conventions are outdated or wrong", "Missing template types" |
| Navigation | "Sources have moved or gone dead", "Playbooks don't find the answer", "Baked-in facts have crept in", "Missing question types" |
Question: "What problems are you seeing with this skill?"
Header: "Issues"
Options: [universal options + discipline-specific options]
Step 2b: Follow up for specifics
After the user selects concerns, ask a focused follow-up. Output as regular text, then use AskUserQuestion:
Question: "Which specific areas concern you most?"
Header: "Specifics"
Options:
- "I can describe specific issues" - Will provide details after selection
- "General sense something is off" - Needs investigation to pinpoint
- "Failing validation or quality checks" - Structural/formatting issues
- "Users/agents aren't finding it useful" - Effectiveness concerns
If the user selects "I can describe specific issues", let them type their specific concerns naturally in the conversation before proceeding. Do NOT rush to investigation.
Step 3: Automated Analysis
Run two parallel analysis tracks:
Track A: Structural Validation
node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js {skill-path}
Capture ALL errors and warnings. These are hard evidence of structural issues.
Track B: Deep Quality Audit
Launch the skill-reviewer agent via the Task tool. Pass the discipline's rubric so it applies discipline-appropriate checks:
subagent_type: "dev-skill:skill-reviewer"
prompt: "Review the skill at {skill-path}.
This is a {discipline} skill. Apply the following rubric:
{paste the full RUBRIC.md content from Step 0c}
Focus especially on: {user's specific concerns from Step 2}.
Provide your full review report."
Wait for both tracks to complete before proceeding.
Step 4: Discipline-Specific Investigation
For EACH claim the user made, investigate using methods appropriate to the discipline.
Universal Investigations
"Skill doesn't trigger or triggers incorrectly"
- Read the
descriptionfield in SKILL.md frontmatter - Analyze trigger phrases — are they specific enough? Do they match real user queries?
- Check if the description uses third-person format (required for skill discovery)
- Verdict: List specific trigger phrase problems with suggested fixes
"General sense something is off"
Run a broader investigation using discipline-appropriate checks:
- Distillation: Check category ordering, impact calibration, rule contradictions, duplicate rules, reference URL liveness (spot-check 5-10)
- Composition: Trace the full workflow end-to-end, check for missing error handlers, verify guardrails match actual dangerous commands
- Investigation: Trace every decision tree path to completion, check for orphaned queries not referenced by any tree
- Extraction: Render each template mentally with sample parameters, check conventions against current framework idioms
- Navigation: Spot-check source URLs live, run the staleness litmus test over every file, trace each playbook to its terminal escalation
"Failing validation or quality checks"
- Parse
validate-skill.jsoutput for specific errors - Categorize errors by type (frontmatter, structure, content, naming)
- Prioritize: MUST-fix errors first, then warnings
- For each error, identify the exact file and line to fix
"Users/agents aren't finding it useful"
- Analyze SKILL.md structure — does it follow progressive disclosure?
- Check content density — are there items that dilute quality?
- Review "When to Apply" section — are scenarios specific enough?
- Check if content is actionable or too theoretical
Distillation Investigations
"Rules give wrong or outdated advice"
- Identify the suspect rules — either named by user or flagged by skill-reviewer
- For each suspect rule:
- Read the rule file completely
- Use
WebSearchto find current best practices for that specific technique - Compare the rule's advice against authoritative sources (official docs, framework maintainer blogs, recent benchmarks)
- Check if the technology has deprecated or superseded the pattern
- Verdict: CONFIRMED (with source URL) or UNCONFIRMED (rule is actually correct)
"Missing important decisions" (coverage gaps)
- Reason about the wrong defaults a capable model has for this technology; confirm with
WebSearchfor "{technology} common mistakes" and the library's changelog/deprecations. - A gap is a wrong default the model would hit on a target task that no rule corrects — judge against the eval prompts, not against a count.
- Verdict: List the missing wrong-defaults, each with a primary source proving it matters.
"Filler rules" (the opposite, more common problem)
- For each rule, ask: what does the model do here without it? If the answer is "the right thing already," the rule is hand-holding.
- Verdict: List rules that merely restate a correct default — these should be deleted. Fewer, sharper rules is the improvement.
"Code examples are unrealistic"
- Read the flagged rule files (or sample 10 rules if user gave no specifics)
- For each code example, check:
- Would this code compile/run? (syntax correctness)
- Is the "incorrect" example a real anti-pattern or a strawman?
- Is the "correct" example production-ready or does it only work in happy path?
- Is the diff between incorrect/correct minimal? (same variable names, same structure)
- Are variable names realistic (not
foo,bar,data)?
- Cross-reference with
validate-skill.jsoutput for generic name violations - Verdict: List specific examples that need fixing with concrete problems
Composition Investigations
"Scripts fail or have errors"
- List all scripts in
{skill-path}/scripts/ - For each script:
- Run
bash -n {script}to check syntax (or equivalent for the script's language) - Check for
set -euo pipefail(or equivalent strict mode header) - Verify all referenced commands/tools exist and are documented as dependencies
- Check for unquoted variables, missing input validation
- Run
- Verdict: List specific script errors with file, line, and fix
"Workflow is missing steps"
- Read the workflow documentation and user's description of what's missing
- Map the current workflow steps against the user's expected flow
- Identify gaps: steps that are assumed but not documented, transitions without error handling
- Check if the workflow handles the full lifecycle (setup, execute, verify, cleanup)
- Verdict: List missing steps with where they should be inserted
"Guardrails are insufficient"
- Read
{skill-path}/hooks.json(if it exists) - List every command in the skill's scripts that modifies external state (git push, API calls, file deletion, resource creation)
- For each destructive command: check if a PreToolUse matcher would catch it
- Test matchers mentally — would the regex/pattern actually match the dangerous command?
- Check for confirmation prompts before destructive operations
- Verdict: List unguarded destructive operations with specific matcher fixes
"Error handling is incomplete"
- For each script, trace the failure path at each step
- Check: does the error message tell the user what to do next, or just what went wrong?
- Verify exit codes are non-zero on failure
- Check if partial completion is handled (cleanup on failure, resumability)
- Verdict: List specific error handling gaps with file and line
Investigation Investigations
"Decision trees have dead ends"
- Read every decision tree file in the skill
- For each tree, trace every path from root to leaf
- At every leaf node, verify it terminates in a concrete action (fix, escalate, or dismiss)
- At every branch point, verify the criterion is measurable (not vague)
- Verdict: List specific dead-end paths with tree file, path taken, and where it terminates
"Queries don't work or return wrong results"
- Read all query files in
{skill-path}/references/queries/ - For each query:
- Check syntactic validity (SQL: parse syntax; shell:
bash -n; Python:python -c "import ast; ast.parse(open('{file}').read())") - Verify all parameters are documented with description and defaults
- Check if the expected output is described
- Check syntactic validity (SQL: parse syntax; shell:
- Cross-reference queries against decision trees — are all referenced queries present?
- Verdict: List specific query issues with file and fix
"Missing symptoms or investigation paths"
- Read
{skill-path}/references/symptoms.md - Use
WebSearchto find common issues/failures for the skill's domain - Compare against the symptom catalog — identify symptoms that appear in multiple sources but are missing
- Check for symptoms that have catalog entries but no decision tree (incomplete paths)
- Verdict: List missing symptoms with sources, and orphaned catalog entries
Extraction Investigations
"Templates produce invalid code"
- Read each template file in
{skill-path}/assets/templates/ - For each template:
- Mentally substitute realistic parameter values
- Check if the rendered output is syntactically valid for the target framework
- Check for hardcoded values that should be parameterized
- Verify all output files are documented
- Use
WebSearchto verify generated code follows current framework idioms (not deprecated patterns) - Verdict: List specific template issues with file, parameter values used, and the resulting invalid output
"Conventions are outdated or wrong"
- Read
{skill-path}/references/conventions.md - Use
WebSearchto find current conventions for the target framework/language - Compare each convention against current community standards
- Check for contradictions between conventions and templates (conventions.md says one thing, templates do another)
- Verdict: List outdated conventions with current recommendation and authoritative source
"Missing template types"
- Read the existing templates and the framework they target
- Use
WebSearchto find common component/file types for the target framework - Compare against template coverage — identify common types that developers create frequently but have no template
- Verdict: List missing template types with frequency/importance evidence
Navigation Investigations
"Sources have moved or gone dead"
- Read
{skill-path}/references/sources.md - For each source: fetch the base URL and one constructed deep link (fill the URL pattern with a real symbol) via
WebFetch - Record: live, redirected (to where?), or dead
- Verdict: List dead/moved sources with the working replacement URL where one exists
"Playbooks don't find the answer"
- Identify the failing question types (named by user, or test each playbook with a realistic question)
- For each failing playbook: execute the steps as written — do the queries return the expected hit? Is the hit criterion recognizable?
- Check ordering: are broad searches running before cheap deep-link fetches?
- Verdict: List failing steps with what actually came back and the corrected query/order
"Baked-in facts have crept in"
- Scan every file for technical claims (API signatures, behavior statements, defaults, version-specific steps)
- Apply the litmus test: would this line need editing when the technology ships a new version?
- Verdict: List each embedded fact with the source-map entry the skill should route to instead — deleting facts is the fix
"Missing question types"
- Ask what lookups the user performed recently that had no playbook
- Check
gotchas.mdfor recurring ad-hoc searches - Verdict: List missing question types, each with evidence it recurs
Step 5: Evidence Report
Present findings to the user as a structured report. Only include claims backed by evidence.
Display as regular markdown text:
## Investigation Report: {skill-name}
**Discipline:** {discipline}
**Claims investigated:** {N}
**Confirmed issues:** {N}
**Unconfirmed claims:** {N}
---
### Confirmed Issues
For each confirmed issue:
#### Issue {N}: {Brief title}
- **User claim:** {what the user said}
- **Evidence:** {what you found — include source URLs, validator output, specific file references}
- **Affected files:** `{file1}`, `{file2}`, ...
- **Severity:** CRITICAL / HIGH / MEDIUM / LOW
- **Suggested fix:** {specific, actionable fix}
---
### Unconfirmed Claims
For each unconfirmed claim:
#### Claim: {what the user said}
- **Investigation:** {what you checked}
- **Finding:** {why the claim doesn't hold — with evidence}
---
### Additional Issues Found
Issues discovered during investigation that the user didn't mention:
#### Issue {N}: {Brief title}
- **Source:** validate-skill.js / skill-reviewer / investigation
- **Evidence:** {hard evidence}
- **Severity:** CRITICAL / HIGH / MEDIUM / LOW
- **Suggested fix:** {specific fix}
---
### Summary
| Category | Count | Severity Breakdown |
|----------|-------|--------------------|
| Confirmed user claims | N | X critical, Y high, Z medium |
| Additional issues | N | X critical, Y high, Z medium |
| Unconfirmed claims | N | — |
| **Total fixes needed** | **N** | |
Then ask for approval using AskUserQuestion:
Question: "I've identified {N} confirmed issues. How would you like to proceed?"
Header: "Next steps"
Options:
- "Fix all confirmed issues" - Apply all suggested fixes
- "Fix critical and high only" - Skip medium/low severity
- "Let me review first" - User will select which fixes to apply
- "Export report only" - Save report without applying fixes
Step 6: Apply Approved Fixes
For each approved fix, apply changes using discipline-appropriate strategies.
Universal Fixes
Trigger/Description Fixes:
- Rewrite SKILL.md
descriptionfield with specific trigger phrases - Follow third-person format: "This skill should be used when..."
- Include technology-specific keywords that users would naturally type
Structural Fixes (frontmatter, formatting):
- Fix exactly what
validate-skill.jsreported - Re-run
validate-skill.jsafter fixes to confirm resolution
Distillation Fixes
Content Fixes (wrong/outdated advice):
- Research the correct current advice using
WebSearch(primary sources — see RECIPE.md "Sources"). - Rewrite the rule following
${CLAUDE_PLUGIN_ROOT}/templates/disciplines/distillation/RULE.md.template. - Update title, tags, the WHY, the example, and the reference. (
impact/impactDescriptiononly if it's a performance skill.) - Preserve the filename and category placement unless the fix requires moving it.
Coverage Gaps (missing rules):
- Add a rule only for a genuine wrong default the model would hit — not to raise a count.
- Use the correct prefix from
_sections.md; add a category there first if one is needed.
Filler Removal (often the biggest win):
- Delete rules that restate what the model already does right. Cutting them is the improvement.
Example Quality Fixes:
- Default to one canonical, production-realistic example with realistic names.
- Use an Incorrect/Correct foil only where the wrong way is a real trap; replace any strawman foil with a single canonical example.
- Keep comments to 1-2 per block, explaining consequences not syntax.
Composition Fixes
Script Fixes:
- Add
set -euo pipefailif missing - Fix syntax errors identified by
bash -n - Add input validation for required arguments
- Make error messages actionable ("Run X to fix" not just "X failed")
Workflow Gaps:
- Add missing steps to the workflow documentation
- Create new script files if steps require automation
- Update SKILL.md navigation to reference new steps
Guardrail Fixes:
- Create or update
hooks.jsonwith PreToolUse matchers for unguarded destructive operations - Add confirmation prompts before destructive steps in scripts
- Document rollback procedures for each destructive step
Error Handling Fixes:
- Add trap handlers for cleanup on failure
- Make error messages include next-step instructions
- Add exit code documentation
Investigation Fixes
Dead End Fixes:
- Extend decision trees with terminal actions at every dead-end path
- Add measurable criteria at vague branch points (replace "is it slow?" with "is p99 latency > {threshold}ms?")
- Add cross-references to queries at every "check X" node
Query Fixes:
- Fix syntax errors in query files
- Add parameter documentation (description, type, default value)
- Add expected output descriptions
- Create missing queries referenced by decision trees
Missing Symptom Fixes:
- Add new symptom entries to the symptom catalog
- Create corresponding decision tree files
- Create supporting query patterns
- Link everything together: catalog -> tree -> queries
Extraction Fixes
Template Fixes:
- Fix templates to produce valid code for the target framework
- Replace hardcoded values with parameters
- Add parameter documentation (description, required/optional, defaults, constraints)
- Update to current framework idioms if deprecated patterns detected
Convention Fixes:
- Update
conventions.mdwith current community standards - Add "Why" rationale for each convention
- Resolve contradictions between conventions and templates
- Add exception guidance where valid alternatives exist
Missing Template Fixes:
- Create new template files following the extraction template pattern
- Document all parameters with description and defaults
- Verify rendered output is valid with realistic parameter values
- Add to SKILL.md navigation
Navigation Fixes
Source Map Fixes:
- Update moved URLs and deep-link patterns; verify each replacement live before writing it
- Log the old pattern and what replaced it in
gotchas.md(dated) - Fill in missing "NOT authoritative for" scoping and currency signals
Playbook Fixes:
- Replace vague steps with concrete tool + query invocations, each with a hit criterion
- Reorder: cheap high-precision steps first, broad searches later, source reading last
- Ensure the final step is an explicit escalation and the exit runs through
verification.md - Create playbooks for confirmed missing question types; add them to SKILL.md routing
Staleness Fixes:
- Delete embedded technical facts; where the fact answered a real question, route the relevant playbook to the authoritative source instead
- Tighten
verification.mdif a stale answer previously passed its checks
Step 7: Re-validate
After applying all fixes, run the full validation pipeline:
-
Automated validation:
node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js {skill-path}Fix any remaining errors.
-
Quality re-review (if content changes were made): Launch
skill-revieweragent with the discipline rubric, focused on the changed files only. -
Present final status:
## Fix Summary **Discipline:** {discipline} **Issues fixed:** {N} **Validation status:** PASS / {N} remaining issues **Files modified:** {list} **Files added:** {list} ### Changes Applied | File | Change | Severity | |------|--------|----------| | `{file}` | {description of change} | {severity} | | ... | ... | ... |
Step 8: Suggest Complementary Skills
After completing fixes, analyze what complementary skills from OTHER disciplines would strengthen this skill's domain coverage. Each discipline has natural complements:
| Current Discipline | Complement | Why |
|---|---|---|
| Distillation (best practices) | Composition (verification) | "You codified the rules — now automate checking them" |
| Distillation (best practices) | Extraction (scaffolding) | "You know the right patterns — now generate code that follows them" |
| Composition (workflow) | Investigation (runbook) | "You automated the happy path — now handle when it breaks" |
| Composition (workflow) | Distillation (reference) | "You automate the process — now document why each step matters" |
| Investigation (runbook) | Composition (automation) | "You diagnose manually — now automate the common fixes" |
| Extraction (scaffolding) | Distillation (reference) | "You generate code — now teach agents the deeper patterns" |
| Distillation (best practices) | Adversarial (review gate) | "You codified the rules — now enforce them with a blind review gate" |
| Adversarial (review gate) | Distillation (reference) | "The gate excludes judgment calls — teach those in a reference skill" |
| Distillation (best practices) | Navigation (doc navigation) | "The snapshot ages — navigation answers version-sensitive questions from live sources" |
| Navigation (doc navigation) | Distillation (best practices) | "You route to current facts — now correct the wrong defaults the model has today" |
Suggest 1-2 complementary skills only if they would genuinely add value. Display as:
## Complementary Skill Suggestions
Based on this {discipline} skill, consider creating:
1. **{Suggested skill name}** ({target discipline})
{One sentence explaining the value.}
Create with: `/dev-skill:new`
2. **{Suggested skill name}** ({target discipline})
{One sentence explaining the value.}
Create with: `/dev-skill:new`
If the skill's domain is too narrow or self-contained to benefit from complements, skip this section entirely. Do not force suggestions.
Blind Comparison (for significant changes)
When the changes are substantial (multiple rules rewritten, workflow restructured, templates overhauled), offer a blind comparison between old and new versions. This is more rigorous than rubric-based review — it compares actual outputs.
When to offer
- More than 5 rules changed (distillation)
- Workflow steps added or reordered (composition)
- Decision tree branches restructured (investigation)
- Templates significantly changed (extraction)
- Source map restructured or multiple playbooks rewritten (navigation)
How to run
- Snapshot the old skill before applying changes:
cp -r {skill-path} {skill-path}-workspace/skill-snapshot/ - Apply changes to the skill
- Run 2-3 test prompts against both versions (spawn subagents via Task tool):
- New version: run with the updated skill
- Old version: run with the snapshot
- Launch blind comparator — spawn a subagent that reads
${CLAUDE_PLUGIN_ROOT}/agents/comparator.md:
(Randomly assign old/new to A/B so the comparator can't infer which is which)Compare these two outputs blindly: - Output A: {workspace}/eval-{N}/version_a/outputs/ - Output B: {workspace}/eval-{N}/version_b/outputs/ - Eval prompt: {the test prompt} - Expectations: {assertions if any} Save results to: {workspace}/eval-{N}/comparison.json - Launch analyzer — spawn a subagent that reads
${CLAUDE_PLUGIN_ROOT}/agents/analyzer.md:Analyze this comparison: - Winner: {from comparison.json} - Winner skill: {path to whichever version won} - Winner transcript: {path} - Loser skill: {path to whichever version lost} - Loser transcript: {path} - Comparison result: {workspace}/eval-{N}/comparison.json Save analysis to: {workspace}/eval-{N}/analysis.json - Report results to the user with evidence from the analyzer
If the new version loses the blind comparison, present the analysis and ask the user whether to keep the changes, revert, or try a different approach.
When NOT to use
- Trivial fixes (typos, broken links, formatting)
- The user explicitly says they don't want to run comparisons
- No test prompts exist and the user doesn't want to create them
Mandatory Requirements
NEVER:
- Suggest fixes without hard evidence (validator output, authoritative source, or concrete analysis)
- Dismiss user claims without investigation — always check before concluding "unconfirmed"
- Rewrite content that is working correctly — if it ain't broke, don't fix it
- Skip re-validation after applying fixes
- Fabricate evidence or impact claims
- Apply distillation-specific checks to composition skills or vice versa
ALWAYS:
- Detect the discipline before starting investigation
- Use the correct discipline rubric for the skill-reviewer agent
- Quote specific files, line numbers, and validator messages as evidence
- Include authoritative source URLs when claiming advice is outdated
- Preserve the skill's existing style and conventions when making fixes
- Run
validate-skill.jsbefore AND after changes - Ask the user before applying any fix
Skill Ingest
Transform existing source material — GitHub repos, local directories, documentation URLs, or existing skill folders — into a quality-gated skill that follows dev-skill conventions.
This is the curation path. Unlike /dev-skill:new (which creates from scratch), ingest starts from source material that already exists and restructures it into a validated skill.
A strong model improves analysis quality; the bundled agents declare their own model in frontmatter.
Input
A source path or URL:
- GitHub repo path:
owner/repo/path/to/skillor a full GitHub URL - Local directory:
./path/to/existing-skillor~/vendor/some-docs/ - Documentation URL:
https://docs.example.com/api-reference - Existing skill folder:
~/.claude/skills/some-skill(remix/upgrade)
Optional output path (defaults to asking the user).
Step 0: Determine Source Type and Output Location
0a: Classify the source
Detect what was provided:
| Input Pattern | Source Type | Fetch Method |
|---|---|---|
owner/repo or owner/repo/path | GitHub repo | gh api to list + fetch files |
https://github.com/... | GitHub URL | Parse owner/repo/path, then gh api |
https://... (non-GitHub) | Documentation URL | WebFetch to pull content |
Path starting with ., /, or ~ | Local directory | Direct Read + Glob |
0b: Ask output location
Use AskUserQuestion:
Question: "Where should I create the ingested skill?"
Header: "Location"
Options:
- "~/.claude/skills/ (Global)" — Available across all projects
- ".claude/skills/ (Project)" — Specific to this project, shared via git
Store as {output-base}.
Step 1: Fetch & Inventory
For GitHub sources:
# List all files at the path
gh api repos/{owner}/{repo}/contents/{path} --jq '.[].name'
# Fetch each file
gh api repos/{owner}/{repo}/contents/{path}/{file} --jq '.content' | base64 -d
For local directories:
Read the directory tree with Glob and Read.
For documentation URLs:
Use WebFetch to pull content. For multi-page docs, follow navigation links to pull related pages.
Display inventory
Show the user what was found:
## Source Inventory
| # | File | Type | Lines | Description |
|---|------|------|-------|-------------|
| 1 | SKILL.md | Skill entry | 280 | Main workflow doc |
| 2 | references/auth.md | Reference | 150 | OAuth patterns |
| 3 | scripts/deploy.sh | Script | 60 | Deploy automation |
Ask via AskUserQuestion:
Question: "Which files should be included in the skill?"
Header: "File Selection"
Options:
- "Include all files"
- "Let me select specific files"
If the user selects specific files, ask which to include.
Step 2: Analyze & Detect Structure
Read all included files and analyze their content to infer the skill's natural structure. Do not force a discipline — detect the shape from the content.
Structure Detection Signals
| Signal | Inferred Structure | Discipline |
|---|---|---|
| Phased workflow (Phase 1, Phase 2...) | Guided decision workflow | composition |
Prefixed rule files ({prefix}-*.md) plus a _sections.md | Progressive-disclosure reference | distillation |
| Template files with parameter placeholders | Scaffolding templates | extraction |
| Decision trees, symptom catalogs, queries | Investigation runbook | investigation |
| Scripts with verification/assertion logic | Verification workflow | composition |
| Reviewer prompt + pass/fail verdict protocol | Adversarial review gate | adversarial |
| Source maps, search strategies, where/how to find info | Documentation navigation | navigation |
| Mixed (references + scripts + workflow) | Hybrid — use dominant pattern | infer from content ratio |
Content Analysis
For each file, determine:
- Role: Is it an entry point, reference doc, script, template, or config?
- Quality: Does it follow dev-skill conventions already? What needs adaptation?
- Dependencies: Does it reference other files? External tools? Companion skills?
Propose skill structure
Present the proposed structure as regular text:
## Proposed Skill Structure
**Inferred discipline:** composition (guided workflow with reference docs)
**Inferred type:** scaffolding
{skill-name}/ ├── SKILL.md ← from source SKILL.md (adapted) ├── metadata.json ← generated ├── gotchas.md ← initialized ├── scripts/ │ └── test-server.sh ← from source scripts/test.sh (adapted) └── references/ ├── auth.md ← from source docs/auth.md (as-is) └── tool-design.md ← from source docs/tools.md (restructured)
### Adaptations needed:
- SKILL.md: Add frontmatter (name + description), "When to Apply" section, "Prerequisites" section
- scripts/test.sh → test-server.sh: Add safety header, input validation, actionable errors
- docs/tools.md → references/tool-design.md: No changes needed, content is already well-structured
Ask via AskUserQuestion:
Question: "Does this structure look right?"
Header: "Structure Review"
Options:
- "Approve and proceed"
- "Adjust structure"
- "Major revisions needed"
Only proceed after user approval.
Step 3: Transform & Generate
Transform source files into dev-skill convention-following files. The goal is minimal modification — preserve the source's voice and content, only add what's missing.
3a: SKILL.md Adaptation
If the source has a SKILL.md or main entry document:
-
Add frontmatter if missing:
--- name: {skill-name} description: {trigger description — infer from content} --- -
Add "When to Apply" section if missing — derive from the skill's content (what triggers it)
-
Add "Workflow Overview" section if missing — extract from existing phase/step structure
-
Add "Prerequisites" section if missing — scan for tool dependencies (npx, python, etc.)
-
Add "Reference files" section at bottom — link to all reference docs with one-line descriptions
-
Ensure under 500 lines — if longer, extract detail into reference files
3b: Script Adaptation
For each script file:
- Add safety header if missing:
set -euo pipefail - Add dependency check if the script uses external tools (
command -v) - Add input validation if missing (check required args, print usage)
- Add actionable error messages (tell user what to do, not just what failed)
- Ensure executable:
chmod +x
3c: Reference File Adaptation
Reference files usually need minimal changes:
- Ensure they have a title (H1 heading)
- Check internal links — update paths if file structure changed
- Add cross-references to other skill files where relevant
3d: Generate metadata.json
{
"version": "0.1.0",
"organization": "{infer from source or ask user}",
"technology": "{infer from content}",
"discipline": "{detected in Step 2}",
"type": "{detected in Step 2}",
"date": "{current month and year}",
"abstract": "{1-2 sentence summary — infer from content}",
"references": ["{source URLs}"]
}
3e: Generate gotchas.md
# Gotchas
No known gotchas yet. Append entries as they're discovered during use.
3f: Write all files
Write all transformed files to {output-base}/{skill-name}/.
Step 4: Quality Gate (Automatic)
This step is mandatory and runs automatically. Unlike /dev-skill:new where validation and review are separate manual steps, ingest runs both as a single gate.
4a: Structural validation
node /Users/pedroproenca/.claude/plugins/marketplaces/dot-claude/plugins/dev-skill/scripts/validate-skill.js {output-base}/{skill-name}
Fix ALL errors before proceeding. Address warnings where feasible.
4b: Substance review
Launch the skill-reviewer agent with the discipline-appropriate rubric:
/Users/pedroproenca/.claude/plugins/marketplaces/dot-claude/plugins/dev-skill/templates/disciplines/{discipline}/RUBRIC.md
Fix ALL critical issues identified by the reviewer.
4c: Re-validate after fixes
If the reviewer caused changes, re-run validation to ensure no regressions.
Step 5: Transformation Report
Display a summary of what was done:
## Ingest Complete
**Source:** {source path/URL}
**Output:** {output-base}/{skill-name}/
**Discipline:** {discipline} | **Type:** {type}
**Validation:** PASS (0 errors, 0 warnings)
### Files
| Source File | → | Output File | Changes |
|-------------|---|-------------|---------|
| SKILL.md | → | SKILL.md | +frontmatter, +When to Apply, +Prerequisites |
| docs/auth.md | → | references/auth.md | Moved, no content changes |
| scripts/test.sh | → | scripts/test-server.sh | +safety header, +input validation |
| — | → | metadata.json | Generated |
| — | → | gotchas.md | Generated |
### Adaptations Applied
- Added SKILL.md frontmatter with trigger description
- Added "When to Apply" section (5 triggers)
- Added "Prerequisites" section (Node.js >= 18, jq)
- Added safety headers to 1 script
- Generated metadata.json and gotchas.md
### Source Preserved
- 6 reference files: no content changes, only path adjustments
- All code examples, diagrams, and technical content unchanged
Step 6: Suggest Next Steps
After the report, suggest follow-up actions:
## Next Steps
The skill is structurally valid and passes quality review. Consider:
1. **Optimize the description:** The trigger description was inferred from content. Test whether it activates correctly for relevant queries.
2. **Add gotchas:** Use the skill for a few sessions and capture failure points in gotchas.md.
If the source had companion skills (referenced but not ingested), mention them:
### Companion Skills Found
The source references these companion skills that weren't ingested:
- `build-mcp-app` — Interactive UI widgets (hand-off from Phase 2)
- `build-mcpb` — Bundled local servers (hand-off from Phase 2)
Run `/dev-skill:ingest` on each to bring them in.
Special Cases
Ingesting from an existing dev-skill skill (remix)
When the source is already a dev-skill skill (has metadata.json with discipline/type):
- Skip structure detection — use the existing discipline
- Focus on quality improvements: run reviewer, fix issues, update metadata version
- This is essentially
/dev-skill:evolvebut starting from a copy
Ingesting from a CLAUDE.md file
When the source is a single CLAUDE.md:
- Analyze the content for discrete skill boundaries
- If it contains multiple unrelated topics, suggest splitting into separate skills
- Extract each skill section into its own SKILL.md + references
Ingesting from documentation URLs
When fetching from a docs site:
- Follow table-of-contents links to pull all relevant pages
- Convert HTML to markdown (WebFetch handles this)
- Group pages into reference files by topic
- Generate a SKILL.md that navigates the references
Large sources (100+ files)
When the source has many files:
- Show the top-level structure and ask the user to narrow scope
- Suggest splitting into multiple skills if the scope is too broad
- Flag files that are likely irrelevant (tests, CI config, node_modules)
Mandatory Requirements
NEVER:
- Modify the source material's meaning or technical content — only add structure
- Skip the quality gate (Step 4) — validation + review are automatic and mandatory
- Force a discipline that doesn't fit — detect from content, ask if uncertain
- Generate AGENTS.md manually — use
build-agents-md.jsif the skill is distillation
ALWAYS:
- Read
/Users/pedroproenca/.claude/plugins/marketplaces/dot-claude/plugins/dev-skill/templates/anatomy/ANATOMY.mdbefore transforming - Preserve the source's voice and terminology — don't rewrite content, add structure
- Show the transformation report (Step 5) — the user must see what changed vs source
Skill Structure Migration Command
Migrate skills generated by dev-skill from the old rules/ directory structure to the new references/ + assets/templates/ structure with 100% validation to eliminate breaking changes.
Input
A single skill directory path, e.g.:
~/.claude/skills/vercel-react-best-practices./skills/python-best-practices
Structure Change Summary
Old Structure
skill/
├── SKILL.md
├── AGENTS.md # Will be regenerated
├── metadata.json
├── README.md # Will be deleted
└── rules/
├── _sections.md
├── _template.md
└── {prefix}-{slug}.md
New Structure
skill/
├── SKILL.md # Updated with markdown links
├── AGENTS.md # Regenerated as TOC-only navigation doc
├── metadata.json
├── references/
│ ├── _sections.md
│ └── {prefix}-{slug}.md
└── assets/
└── templates/
└── _template.md
Migration Workflow
Execute these steps in order. Content is MOVED, not rewritten, except for necessary link updates.
Step 1: Pre-flight Checks
Before any modifications:
# 1. Verify skill path exists
test -d "<skill-path>" || { echo "Error: Skill directory not found"; exit 1; }
# 2. Verify old structure exists (needs migration)
test -d "<skill-path>/rules" || { echo "Error: No rules/ directory - skill may already be migrated"; exit 1; }
# 3. Verify NOT already migrated
test ! -d "<skill-path>/references" || { echo "Error: references/ exists - already migrated"; exit 1; }
# 4. Check if git repo and content is committed
cd "<skill-path>"
if git rev-parse --git-dir > /dev/null 2>&1; then
# Check if skill files are committed (no uncommitted changes)
if ! git diff --quiet . && ! git diff --cached --quiet .; then
echo "Warning: Uncommitted changes detected in skill directory"
# Ask user to commit first or proceed with caution
fi
fi
If pre-flight fails: Report the specific error and stop.
Step 2: Capture Before State
Before making changes, capture state for validation:
# List all rule files (excluding _ prefixed)
ls -1 "<skill-path>/rules/"*.md | grep -v '/_' > /tmp/rules_before.txt
# Count rules
RULE_COUNT_BEFORE=$(ls -1 "<skill-path>/rules/"*.md 2>/dev/null | grep -v '/_' | wc -l | tr -d ' ')
# Capture checksums for content verification
find "<skill-path>/rules" -name "*.md" -type f -exec md5 {} \; > /tmp/checksums_before.txt
Step 3: File Migration (Move, Don't Rewrite)
Execute moves in this order:
cd "<skill-path>"
# 1. Create new directories
mkdir -p references
mkdir -p assets/templates
# 2. Move _sections.md to references/
mv rules/_sections.md references/_sections.md
# 3. Move all rule files to references/
# (all .md files except _template.md)
for f in rules/*.md; do
[ "$(basename "$f")" = "_template.md" ] && continue
mv "$f" references/
done
# 4. Move _template.md to assets/templates/
mv rules/_template.md assets/templates/_template.md
# 5. Remove empty rules/ directory
rmdir rules
# 6. Delete obsolete README.md (no longer part of skill structure)
rm -f README.md
Content preservation: Rule files are moved (mv), not copied or rewritten. Only metadata (path) changes. README.md is deleted as it is no longer part of the curated skill structure.
Step 4: Update SKILL.md Links
Read SKILL.md and update references. This is the only content rewriting needed:
Path replacements:
rules/->references/rules/_sections.md->references/_sections.mdrules/_template.md->assets/templates/_template.md
Link format conversion (where applicable):
- Plain text
rules/example.md->[example](references/example.md) - Ensure "How to Use" section uses markdown link format
Example transformation:
# Before
Read individual rule files:
rules/{prefix}-{slug}.md
rules/_sections.md
# After
Read individual reference files:
- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules
Use Read tool to get SKILL.md content, apply transformations, then Write tool to save.
Step 5: Regenerate AGENTS.md
Regenerate AGENTS.md as a TOC-only navigation document pointing to the new references/ paths:
node "${CLAUDE_PLUGIN_ROOT}/scripts/build-agents-md.js" "<skill-path>"
This creates a slim AGENTS.md with links to individual reference files, impact levels, and section navigation.
Step 6: Validation Pipeline
Run all validation checks. ALL must pass.
6.1 Structural Validation
cd "<skill-path>"
# All rule files exist in references/
RULE_COUNT_AFTER=$(ls -1 references/*.md 2>/dev/null | grep -v '/_' | wc -l | tr -d ' ')
[ "$RULE_COUNT_BEFORE" = "$RULE_COUNT_AFTER" ] || echo "FAIL: Rule count mismatch"
# _sections.md exists in references/
test -f references/_sections.md || echo "FAIL: _sections.md not found"
# _template.md exists in assets/templates/
test -f assets/templates/_template.md || echo "FAIL: _template.md not found"
# rules/ directory removed
test ! -d rules || echo "FAIL: rules/ directory still exists"
6.2 Content Validation
# No rules/ references remain in SKILL.md
grep -q "rules/" SKILL.md && echo "FAIL: SKILL.md still contains rules/ references"
# SKILL.md contains references/ links
grep -q "references/" SKILL.md || echo "FAIL: SKILL.md missing references/ links"
6.3 Build Validation
# validate-skill.js passes
node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js" "<skill-path>"
# Must exit with 0 errors
# AGENTS.md was regenerated
test -f AGENTS.md || echo "FAIL: AGENTS.md not found (should have been regenerated)"
# Obsolete files were deleted
test ! -f README.md || echo "FAIL: README.md still exists"
6.4 Content Preservation Check
# Compare file checksums (content should be identical for moved files)
# Note: SKILL.md will differ (links updated)
# Rule files in references/ should have same content as rules/ did
Step 7: Final Integrity Check
Run a comprehensive integrity check (all must pass):
cd "<skill-path>"
echo "=== Migration Integrity Check ==="
# 1. Rule count preserved
RULE_COUNT_AFTER=$(ls -1 references/*.md 2>/dev/null | grep -v '^references/_' | wc -l | tr -d ' ')
[ "$RULE_COUNT_BEFORE" = "$RULE_COUNT_AFTER" ] \
&& echo "PASS: Rule count preserved ($RULE_COUNT_AFTER)" \
|| echo "FAIL: Rule count mismatch (before=$RULE_COUNT_BEFORE, after=$RULE_COUNT_AFTER)"
# 2. No old paths remain in SKILL.md
! grep -q "rules/" SKILL.md \
&& echo "PASS: No old rules/ references in SKILL.md" \
|| echo "FAIL: SKILL.md still contains rules/ references"
# 3. New paths present in SKILL.md
grep -q "references/" SKILL.md \
&& echo "PASS: SKILL.md has references/ links" \
|| echo "FAIL: SKILL.md missing references/ links"
# 4. Old directory gone
test ! -d rules \
&& echo "PASS: rules/ directory removed" \
|| echo "FAIL: rules/ directory still exists"
# 5. AGENTS.md regenerated
test -f AGENTS.md \
&& echo "PASS: AGENTS.md regenerated" \
|| echo "FAIL: AGENTS.md not found"
# 6. Obsolete files gone
test ! -f README.md \
&& echo "PASS: README.md deleted" \
|| echo "FAIL: README.md still exists"
# 7. All prefixes in references/ match _sections.md
echo "PASS: Integrity check complete"
If any check FAILs: Report the specific failure to the user.
Error Handling
If migration fails at any step:
-
Ask the user using AskUserQuestion:
Question: "Migration failed at [step]. How would you like to proceed?" Header: "Error" Options: - "Rollback changes (git stash)" - Stash all changes and restore original state - "Continue debugging" - Keep changes and investigate the issue - "Abort" - Stop without rollback (manual cleanup needed) -
If rollback selected:
cd "<skill-path>" git stash push -m "Failed migration rollback" git checkout . -
Report the specific error and step where it occurred.
Success Output
On successful migration, report:
## Migration Complete
**Skill:** {skill-name}
**Path:** {skill-path}
### Changes Made
- Moved {N} rule files from `rules/` to `references/`
- Moved `_sections.md` to `references/`
- Moved `_template.md` to `assets/templates/`
- Updated SKILL.md with markdown links
- Regenerated AGENTS.md as TOC-only navigation doc
- Deleted obsolete `README.md`
- Removed empty `rules/` directory
### Validation Results
- [x] Rule count preserved: {N} rules
- [x] Structure validation: PASS
- [x] Content validation: PASS
- [x] validate-skill.js: 0 errors
- [x] AGENTS.md regenerated: PASS
- [x] Obsolete files deleted: PASS
- [x] Integrity check: PASS
### Git Status
Run `git diff` to review changes before committing.
Commit with: `git commit -am "refactor({skill-name}): migrate to references/ structure"`
Quick Reference
| Old Path | New Path |
|---|---|
rules/_sections.md | references/_sections.md |
rules/_template.md | assets/templates/_template.md |
rules/{prefix}-*.md | references/{prefix}-*.md |
| File | Action |
|---|---|
| Rule files | Move (content preserved) |
| SKILL.md | Update links |
| metadata.json | No change |
| AGENTS.md | Regenerate (TOC-only via build-agents-md.js) |
| README.md | Delete |
Skill Creator
You are an expert at creating high-quality skills for AI agents and LLMs. This command routes through six disciplines — Distillation, Composition, Investigation, Extraction, Adversarial, and Navigation — each with a proven generation pipeline.
Generation quality benefits from a strong model, but don't hard-pin one here — the bundled review agents (skill-reviewer, preflight-validator) declare their own model in frontmatter.
Input Required
You will receive:
- Skill Name: The name for this skill
- Organization Name (optional): The organization authoring this skill
Step 0: Ask Where to Write the Skill
Before starting anything else, ask the user where to write the skill using AskUserQuestion:
Question: "Where should I create this skill?"
Header: "Location"
Options:
- "~/.claude/skills/ (Global)" - Available across all projects, personal customizations
- ".claude/skills/ (Project)" - Specific to this project, shared with team via git
Store the chosen path as {output-base} and use it for all file generation.
Step 1: Type Selection
Ask the user what kind of skill they want to create using AskUserQuestion:
Question: "What type of skill are you creating?"
Header: "Skill Type"
Options:
- "1. Library/API Reference — How to use a library, CLI, or SDK correctly"
- "2. Product Verification — Test and verify code output with assertions"
- "3. Workflow Automation — Automate a repetitive multi-step process"
- "4. Code Scaffolding — Generate boilerplate for your framework"
- "5. Code Quality & Review — Enforce review standards and style"
- "6. CI/CD & Deployment — Build, test, deploy, and monitor"
- "7. Runbook — Diagnose and resolve operational issues"
- "8. Data Analysis — Connect to data sources and run queries"
- "9. Infrastructure Ops — Operational procedures with safety guardrails"
- "10. Adversarial Review — Pass/fail gate: a blind adversarial reviewer judges work against decidable rules"
- "11. Documentation Navigation — Teach agents where and how to find current, authoritative information about a technology"
Step 2: Route to Discipline
Map the selected type to a discipline and follow its pipeline:
| Type | Discipline | Type Slug |
|---|---|---|
| 1. Library/API Reference | Distillation | library-reference |
| 2. Product Verification | Composition | verification |
| 3. Workflow Automation | Composition | automation |
| 4. Code Scaffolding | Extraction | scaffolding |
| 5. Code Quality & Review | Distillation | code-quality |
| 6. CI/CD & Deployment | Composition | cicd |
| 7. Runbook | Investigation | runbook |
| 8. Data Analysis | Investigation | data-analysis |
| 9. Infrastructure Ops | Composition | infra-ops |
| 10. Adversarial Review | Adversarial | adversarial-review |
| 11. Documentation Navigation | Navigation | doc-navigation |
Before generating anything, you MUST:
- Read
${CLAUDE_PLUGIN_ROOT}/templates/anatomy/ANATOMY.mdfor universal skill patterns - Read the discipline-specific recipe:
${CLAUDE_PLUGIN_ROOT}/templates/disciplines/{discipline}/RECIPE.md - Follow the recipe's discovery workflow and generation pipeline exactly
Distillation Path (Types 1, 5)
The pipeline for Library/API Reference and Code Quality/Review skills. It produces a distilled reference — the smallest set of decisions a capable model gets wrong by default, each explaining the wrong default it corrects and why.
Read ${CLAUDE_PLUGIN_ROOT}/templates/disciplines/distillation/RECIPE.md — it is the authority on this discipline. The doctrine in brief:
- Provable conciseness, no rule count. A rule earns its place only if you can name the wrong default it corrects. If the model already does the right thing, cut the rule — restating it is hand-holding. Completeness is proven by behavior on real tasks, never by hitting a count. Brevity is the soul of wit.
- Explain WHY, not just WHAT — the model generalizes from a reason, not from dictation.
- One canonical example by default. Add an Incorrect/Correct foil only when the wrong way is a real, common trap (never a strawman).
- Impact tiers and quantified metrics are optional — performance skills only. Don't force "2-10×" onto a correctness rule.
- Sources: authoritative or nothing. Primary docs/specs/code/named experts; reject content farms, listicles, undated blogs, and AI SEO filler.
Output Structure
{output-base}/{skill-slug}/
├── SKILL.md # Entry point with quick reference
├── AGENTS.md # Compiled TOC navigation doc (built by script)
├── metadata.json # discipline: "distillation", type: "{type-slug}"
├── references/
│ ├── _sections.md # Category definitions ordered by importance
│ └── {prefix}-{slug}.md # Individual rules (as few as cover the wrong defaults)
└── assets/
└── templates/
└── _template.md # Rule template for extensions
Step D1: Research & Analysis (No User Interruption)
Perform all analysis work upfront:
-
Identify the wrong defaults. List what a capable model does wrong by default for this technology — outdated APIs, footguns, library-specific conventions, decisions it gets subtly wrong. This list is the skill's scope. Do not list things the model already handles correctly.
-
Category derivation. Group the wrong defaults into 4–8 categories by decision area (e.g. for an API: auth, pagination, errors, idempotency). Order by importance (frequency × cost). Assign prefixes (2–10 chars). Performance skills only: you may add impact tiers (CRITICAL → LOW) and order by lifecycle position, since earlier stages cascade downstream.
-
Source research. Gather authoritative sources for each claim (see RECIPE.md "Sources"):
- Primary docs / specs / the library's own code — the default citation
- Named-expert writing — a maintainer's post, a benchmark that states its method
- Reject on sight: content farms, listicles, undated blogs, AI-generated SEO filler, and SO/Reddit answers used as a primary citation
Technology-Specific Focus Areas:
Domain Focus Areas Canonical Sources C++ Memory management, RAII, move semantics, templates, constexpr ISO C++ Guidelines, CppCoreGuidelines, Effective Modern C++ Rust Ownership, borrowing, lifetimes, async, unsafe The Rust Book, Rust API Guidelines, Rustonomicon Go Idioms, concurrency, interfaces, error handling Effective Go, Go Code Review Comments, Go Proverbs TypeScript Type safety, async patterns, module organization, runtime performance TypeScript Handbook, ts-eslint docs, Node.js best practices Python Idioms, performance, memory, async, typing PEP 8, Effective Python, Python Performance Tips React/Next.js Server components, data fetching, bundle size, rendering react.dev, nextjs.org, Vercel engineering blog Databases Query optimization, indexing, connection management Official DB docs, Use The Index Luke, High Performance MySQL Mobile (iOS/Android) Launch time, memory, UI thread, battery Apple/Google performance guides, WWDC/Google I/O sessions Source verification (each source):
- Authored by a maintainer, spec author, or named expert — not anonymous SEO content
- Current with the library's present major version
- Actually supports the claim, and the claim traces back to a primary source (docs/spec/code)
- Not a content farm, listicle, undated blog, or AI-generated filler
Step D2: Single Planning Checkpoint
CRITICAL: First output the planning summary as regular text so the user can review it, THEN ask for approval.
Step D2a — Display the plan (output as regular markdown text, NOT inside AskUserQuestion):
## Skill Planning Review
### Execution Lifecycle
[Stage diagram and analysis]
### Proposed Categories
| # | Category | Prefix | Impact | Description |
|---|----------|--------|--------|-------------|
| 1 | ... | ... | CRITICAL | ... |
| 2 | ... | ... | HIGH | ... |
### Authoritative Sources
1. [Source 1] - Official docs
2. [Source 2] - Engineering blog
...
### Rules to Write (the wrong defaults to correct)
- Category 1: {the specific wrong defaults this category corrects}
- Category 2: {…}
No rule-count target — the list of wrong defaults worth correcting *is* the scope.
Step D2b — Ask for approval (use AskUserQuestion with multiSelect: false):
Question: "Does this skill plan look correct? Review the categories, sources, and rule distribution above."
Header: "Plan Review"
Options:
- "Approve and proceed" - Start generation
- "Adjust categories" - User provides specific changes
- "Change sources" - User provides different sources
- "Major revisions needed" - User describes changes
IMPORTANT: The plan content MUST be displayed as regular output text BEFORE calling AskUserQuestion. Do NOT embed the plan inside the question — users cannot see question content until after they respond.
Only proceed after user approval.
After approval, optionally run the preflight-validator agent to catch issues early before generating the rules.
Step D3: Incremental Generation with Early Validation
Generate files in dependency order with validation at each step:
┌─────────────────────────────────────────────────┐
│ 1. Generate references/_sections.md │
│ ↓ │
│ Validate: impact ordering, prefix format │
│ (Fail fast if categories are wrong) │
├─────────────────────────────────────────────────┤
│ 2. Generate rules in parallel, by category │
│ Each rule must name the wrong default it │
│ corrects; cut any that restate a default │
│ the model already gets right. │
│ Validate each batch before the next. │
├─────────────────────────────────────────────────┤
│ 3. Generate SKILL.md, metadata.json │
│ Generate assets/templates/_template.md │
│ (Uses rules count and categories) │
├─────────────────────────────────────────────────┤
│ 4. Build AGENTS.md │
│ node ${CLAUDE_PLUGIN_ROOT}/scripts/build-agents-md.js │
│ (NEVER write AGENTS.md manually) │
├─────────────────────────────────────────────────┤
│ 5. Final validation │
│ node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js │
│ skill-reviewer agent with distillation RUBRIC.md │
└─────────────────────────────────────────────────┘
Step D4: Build AGENTS.md
After all rules are generated, build the AGENTS.md navigation document:
node ${CLAUDE_PLUGIN_ROOT}/scripts/build-agents-md.js {output-base}/{skill-slug}
NEVER write AGENTS.md manually — always use the build script.
Step D5: Automated Quality Assurance
Run both validation phases:
-
Automated validation:
node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js {output-base}/{skill-slug}- Fix ALL errors before proceeding
- Address warnings where feasible
-
Agent quality review: Launch
skill-revieweragent with${CLAUDE_PLUGIN_ROOT}/templates/disciplines/distillation/RUBRIC.md- Reviews teaching effectiveness, code realism, impact accuracy
- Fix ALL issues identified before release
Quick Generation Mode (Distillation Only)
For experienced users who want to skip the planning checkpoint.
When to Use Quick Mode:
- You already know the categories from the Reference Hierarchies
- You have authoritative sources ready
- You want faster generation with minimal interruptions
When NOT to Use Quick Mode:
- Technology doesn't closely match any Reference Hierarchy domain
- You're uncertain about category mapping or impact ordering
- Technology is novel, niche, or cross-domain (e.g., WebAssembly + Rust)
- User explicitly asks for guidance or planning review
- First time creating a skill for this technology family
When in doubt, use the full workflow with planning checkpoint.
Quick Workflow:
User: "Create a Go best practices skill using standard categories"
┌─────────────────────────────────────────────────┐
│ 1. Use Reference Hierarchy for Go (Systems) │
│ Skip research, use: mem-, cache-, algo-, │
│ ds-, io-, conc-, opt-, micro- │
├─────────────────────────────────────────────────┤
│ 2. Generate references/_sections.md immediately │
│ Validate: node validate-skill.js --sections │
├─────────────────────────────────────────────────┤
│ 3. Generate all rules in parallel in references/│
│ (No batching by impact level needed) │
├─────────────────────────────────────────────────┤
│ 4. Generate SKILL.md, metadata.json │
│ Generate assets/templates/_template.md │
├─────────────────────────────────────────────────┤
│ 5. Build AGENTS.md via build-agents-md.js │
├─────────────────────────────────────────────────┤
│ 6. Full validation + skill-reviewer │
└─────────────────────────────────────────────────┘
Quick Mode Triggers — when the user says any of:
- "Quick generate" or "fast mode"
- "Use standard categories"
- "Skip planning"
- "I already know the categories: ..."
Quick Mode users MUST still:
- Run
validate-skill.js --sections-onlyafter generating_sections.md - Run full validation after all rules are generated
- Run
skill-revieweragent before release
Reference Hierarchies by Technology Domain
Systems Languages (C++, Rust, Go)
| Priority | Category | Prefix | Rationale |
|---|---|---|---|
| 1 | Memory Allocation | mem- | Heap vs stack affects everything |
| 2 | Cache Efficiency | cache- | Data locality determines real-world speed |
| 3 | Algorithm Complexity | algo- | O(n) considerations for scalability |
| 4 | Data Structure Selection | ds- | Right container for the job |
| 5 | I/O and Syscall Patterns | io- | Minimize kernel crossings |
| 6 | Concurrency/Threading | conc- | Synchronization overhead |
| 7 | Micro-optimizations | micro- | Branch prediction, vectorization |
Web Frameworks (React, Vue, Angular)
| Priority | Category | Prefix | Rationale |
|---|---|---|---|
| 1 | Network Waterfalls | async- | Sequential requests multiply latency |
| 2 | Bundle/Payload Size | bundle- | Directly affects TTI and LCP |
| 3 | Server-Side Processing | server- | SSR/SSG optimization |
| 4 | Client-Side Data | client- | Caching, deduplication |
| 5 | Rendering Optimization | render- | Virtual DOM, reconciliation |
| 6 | DOM Efficiency | dom- | Batching, layout thrashing |
| 7 | JavaScript Runtime | js- | Micro-optimizations in hot paths |
Database/Query Systems
| Priority | Category | Prefix | Rationale |
|---|---|---|---|
| 1 | Query Plan Optimization | query- | Wrong plan = orders of magnitude slower |
| 2 | Index Utilization | index- | Full scans catastrophic at scale |
| 3 | Connection Management | conn- | Pooling, connection overhead |
| 4 | Transaction Patterns | tx- | Lock contention, isolation |
| 5 | Caching Strategies | cache- | Reduce database load |
| 6 | Data Modeling | model- | Normalization vs denormalization |
Mobile Development (iOS, Android, React Native)
| Priority | Category | Prefix | Rationale |
|---|---|---|---|
| 1 | Launch Time | launch- | First impression, retention |
| 2 | Memory Management | mem- | Limited resources, OOM kills |
| 3 | UI Thread | ui- | Janky UI, ANRs |
| 4 | Network Efficiency | net- | Latency, bandwidth constraints |
| 5 | Battery Consumption | battery- | User expectation of all-day |
| 6 | Storage I/O | storage- | Flash wear, read/write |
| 7 | Animation | anim- | 60fps requirement |
Backend Services (Node.js, Python, Java)
| Priority | Category | Prefix | Rationale |
|---|---|---|---|
| 1 | I/O Patterns | io- | Async vs sync, pooling |
| 2 | Memory Management | mem- | GC pressure, heap sizing |
| 3 | Concurrency Model | conc- | Event loop, threads |
| 4 | Serialization | serial- | JSON parsing, protobuf |
| 5 | Caching | cache- | Redis, memoization |
| 6 | Algorithm Efficiency | algo- | O(n) in hot paths |
| 7 | Runtime Tuning | runtime- | JIT, inline caching |
Source Authority
Acceptable Sources:
| Type | Purpose | Example |
|---|---|---|
| Official docs | Authoritative API reference | react.dev, golang.org |
| Tool docs | Library usage | swr.vercel.app |
| GitHub repos | Implementation reference | github.com/... |
| Engineering blogs | Benchmark data + rationale | vercel.com/blog/... |
Source Criteria:
- Primary maintainers — React team for React, Vercel for Next.js
- Well-maintained OSS — Active GitHub, npm downloads
- Benchmark-backed claims — Engineering blogs with data
- Production-proven — Used at scale
NOT Referenced: Tutorial sites, Stack Overflow, personal blogs without data, outdated docs.
Distillation File Templates
The authoritative formats live in ${CLAUDE_PLUGIN_ROOT}/templates/disciplines/distillation/ — read and fill them rather than reproducing structures inline:
| Template | Produces |
|---|---|
SKILL.md.template | Entry point: When to Apply, a category table, Quick Reference |
_sections.md.template | Category definitions (impact tier optional — performance skills only) |
RULE.md.template | A rule: title + tags (first tag = category prefix), a WHY, one canonical example. Foil, impact, and exceptions are all optional |
_template.md.template | The rule template copied into the skill so it can be extended later |
metadata.json (shared format: ${CLAUDE_PLUGIN_ROOT}/templates/anatomy/metadata.json.template) must include discipline: "distillation" and the type. Keep abstract to one or two honest sentences describing scope — not a performance sales pitch.
Rule Writing Guidelines
Titles are decision-oriented: {Verb} {object} {context} ("Thread context through outbound calls"), Avoid {real anti-pattern}, Use {X} for {Y}.
Tags: first tag = the category prefix; add 2–4 more for concepts/tools, lowercase and hyphenated.
Impact / impactDescription are optional and for performance skills only. When used, the description must be honest and traceable — a real number (O(n)→O(1), 2-10× improvement) or a real consequence (prevents stale reads). Never fabricate a metric for a correctness rule.
Full detail (title patterns, sources, sections format) lives in RECIPE.md.
Quality Checklist (Distillation)
Before finalizing, verify against the doctrine:
- Every rule names the wrong default it corrects. Cut any rule that restates what the model already does right (hand-holding).
- Every rule explains WHY, not just WHAT (no bare ALWAYS/NEVER).
- One canonical example per rule; an Incorrect/Correct foil only where the wrong way is a real, common trap (no strawmen).
- Categories ordered by importance; first tag = category prefix; H2 matches
title. - Sources are primary/authoritative; no content farms, listicles, or undated/AI-SEO pages. Each claim traces to a primary source.
- No vague hedging or marketing language.
- Coverage proven by behavior on real tasks, not by a rule count. There is no minimum or target.
Composition Path (Types 2, 3, 6, 9)
This pipeline produces workflow automation skills — from product verification to CI/CD pipelines to infrastructure operations. The generated skill orchestrates tools, scripts, and multi-step processes.
Output Structure
{output-base}/{skill-slug}/
├── SKILL.md # Workflow overview + trigger phrases
├── metadata.json # discipline: "composition", type: "{type-slug}"
├── config.json # User-specific setup (service URLs, channels, paths)
├── gotchas.md # Failure points discovered over time
├── scripts/ # Executable scripts the skill uses
│ ├── {step-name}.sh # Individual workflow steps
│ └── verify.sh # Verification/assertion script
├── hooks/ # On-demand hooks (if write/destructive)
│ └── hooks.json # Hook definitions
└── references/
└── workflow.md # Detailed workflow documentation
Step C1: Interview
Ask the user with AskUserQuestion to confirm the composition type:
Question: "What type of composition skill are you creating?"
Header: "Composition Type"
Options:
- "Verification — test and assert that code/features work correctly"
- "Workflow Automation — automate a repetitive multi-step process"
- "CI/CD & Deployment — build, test, deploy, and monitor"
- "Infrastructure Ops — operational procedures with safety guardrails"
Then ask free-form:
- "Describe the workflow step by step. What triggers it, what does each step do, and how do you know it worked?"
- "What tools do you use? (CLI commands, MCP servers, APIs, scripts)"
Step C2: Risk Assessment
Classify the risk level of the workflow:
| Level | Criteria | Guardrails Required |
|---|---|---|
| Read-only | Only fetches/analyzes data | None |
| Write | Creates PRs, posts messages, writes files | Confirmation before external side effects |
| Destructive | Deletes resources, force-pushes, drops tables | PreToolUse hook blocks + explicit confirmation + dry-run mode |
Step C3: Workflow Mapping
Structure the user's description into a workflow diagram:
Trigger → Step 1 → Step 2 → ... → Verification → Cleanup
↓ (on failure)
Error handling / Rollback
For each step, identify:
- Action: What happens (command, API call, tool invocation)
- Input: What this step needs from the previous step
- Output: What this step produces for the next step
- Failure mode: What happens when this step fails
- Rollback: How to undo this step (if applicable)
Step C4: Planning Checkpoint
Display the workflow diagram, tool inventory, risk assessment, and generated file list. Ask user to approve before generating:
Question: "Does this workflow plan look correct? Review the steps, tools, and risk assessment above."
Header: "Plan Review"
Options:
- "Approve and proceed" - Start generation
- "Adjust workflow" - User provides changes
- "Major revisions needed" - User describes changes
Only proceed after user approval.
Step C5: Generation
After user approval, generate in this order:
- Generate SKILL.md — Workflow overview diagram, tool requirements, risk level, quick reference
- Generate scripts/ — One script per workflow step (see script requirements below)
- Generate hooks/ (if risk level is write or destructive) — Guardrail hooks
- Generate config.json — User-specific setup with
_setup_instructions - Generate references/workflow.md — Detailed step-by-step with error handling and rollback
- Generate metadata.json with
discipline: "composition"and the appropriatetypefield - Generate gotchas.md — Initialize with "No known gotchas yet"
Script Requirements:
Every script MUST include:
set -euo pipefailsafety header- Input validation for required arguments
- Actionable error messages (tell user what to do, not just what failed)
- Exit codes: 0 = success, 1 = error, 2 = skipped (already done)
For verification skills, generate a scripts/verify.sh with programmatic assertions:
#!/usr/bin/env bash
# verify.sh — Assert expected state after workflow execution
set -euo pipefail
PASS=0
FAIL=0
assert_eq() {
local label="$1" expected="$2" actual="$3"
if [[ "$expected" == "$actual" ]]; then
echo " PASS: $label"
((PASS++))
else
echo " FAIL: $label (expected: $expected, got: $actual)"
((FAIL++))
fi
}
# --- Assertions ---
{generated assertions based on success criteria}
# --- Summary ---
echo ""
echo "Results: $PASS passed, $FAIL failed"
[[ $FAIL -eq 0 ]] || exit 1
For destructive operations, generate guardrail hooks:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/guardrail.sh \"$TOOL_INPUT\"",
"timeout": 5
}]
}
]
}
}
Step C6: Validate
- Automated validation:
node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js {output-base}/{skill-slug} - Agent quality review: Launch
skill-revieweragent with${CLAUDE_PLUGIN_ROOT}/templates/disciplines/composition/RUBRIC.md
Type-Specific Guidance (Composition)
Product Verification Skills (Type 2)
Focus on: assertions, recording, state checking.
- Include
scripts/verify.shwith programmatic assertions - Consider recording output (screenshots, logs) for human review
- Assert on STATE, not just output: "the database row exists" not "the command printed success"
- Structure assertions as: setup → action → wait → assert → cleanup
Example workflow:
1. Set up test data (seed user, create test card)
2. Drive the UI flow (playwright, tmux)
3. Wait for async operations to complete
4. Assert state (database, API, UI)
5. Clean up test data
Workflow Automation Skills (Type 3)
Focus on: composition, logging, idempotency.
- Save results in log files for cross-run consistency
- Make workflows idempotent (running twice produces same result)
- Use structured output (JSON) between steps for composability
- Include a
--dry-runflag that shows what would happen without executing
Example: standup-post skill
1. Fetch git log since last standup
2. Fetch ticket tracker updates
3. Merge and format
4. Post to Slack channel
5. Append to standups.log
CI/CD & Deployment Skills (Type 6)
Focus on: multi-step pipelines with rollback.
- Every deploy step must have a rollback counterpart
- Include error-rate comparison (before/after deploy)
- Support gradual rollout (canary, blue-green)
- Auto-rollback on regression detection
Example: deploy-service skill
1. Build and test locally
2. Push to staging → smoke test
3. Deploy canary (10% traffic)
4. Compare error rates (5 min window)
5. If regression: auto-rollback
6. If stable: full rollout
Infrastructure Ops Skills (Type 9)
Focus on: guardrails, dry-run, soak periods.
- MUST include dry-run mode for destructive operations
- MUST include confirmation prompts before irreversible actions
- Include soak period for cleanup operations (find orphans → wait → confirm → delete)
- Log every destructive action for audit trail
Example: orphan-cleanup skill
1. Scan for orphaned resources (dry-run mode)
2. Post findings to Slack for review
3. Wait for soak period (configurable, default 24h)
4. Request explicit confirmation
5. Execute cleanup with audit logging
6. Verify cleanup completed
Investigation Path (Types 7, 8)
This pipeline maps a domain's symptom space to diagnostic decision trees, query patterns, and report templates. It produces skills for operational runbooks and data analysis.
Output Structure
{output-base}/{skill-slug}/
├── SKILL.md # Symptom overview + trigger phrases
├── metadata.json # discipline: "investigation", type: "{type-slug}"
├── config.json # Service URLs, dashboard IDs, query endpoints
├── gotchas.md # Diagnostic dead-ends discovered over time
├── references/
│ ├── symptoms.md # Symptom catalog with entry points
│ ├── {symptom}-tree.md # Decision tree per symptom class
│ └── queries/ # Reusable query patterns
│ ├── {name}.sql # SQL query templates
│ ├── {name}.sh # CLI investigation commands
│ └── {name}.py # Data analysis scripts (optional)
└── assets/
└── templates/
└── report.md # Investigation report template
Step I1: Interview
Ask the user with AskUserQuestion to confirm the investigation type:
Question: "What type of investigation skill are you creating?"
Header: "Investigation Type"
Options:
- "Runbook — diagnose and resolve operational issues for a service/system"
- "Data Analysis — connect to data sources, run queries, answer business questions"
Then ask free-form:
- "What system or domain does this cover? What are its main components?"
- "What are the top 5-10 symptoms or questions that trigger an investigation?"
- "What tools do you use to investigate? (dashboards, SQL, CLI commands, APIs, log systems)"
Step I2: Symptom Space Mapping
Structure the user's symptoms into a catalog:
## Symptom Catalog
| # | Symptom / Question | Entry Point | Severity |
|---|-------------------|-------------|----------|
| 1 | High latency on /api/checkout | latency-tree.md | P1 |
| 2 | Error rate spike in payment service | error-rate-tree.md | P1 |
| 3 | "Why did conversion drop this week?" | conversion-tree.md | P2 |
For each symptom, identify:
- Entry point: The first thing to check
- Investigation tools: What you query/check at each decision point
- Terminal states: Resolution (fix it), Escalation (hand off), or False alarm (not a problem)
Step I3: Decision Tree Design
Each symptom class gets a decision tree:
Symptom: High latency on /api/checkout
│
├── Check: Is it all endpoints or just checkout?
│ ├── All endpoints → Check: Is the database responding?
│ │ ├── DB slow → Check: queries/slow-queries.sql
│ │ │ ├── Long-running query found → Kill query, investigate lock
│ │ │ └── No slow queries → Check connection pool exhaustion
│ │ └── DB fine → Check: Is it upstream dependency?
│ └── Just checkout → Check: Recent deploy?
│ ├── Yes → Compare error rates before/after deploy
│ └── No → Check: Payment provider status page
Rules for decision trees:
- Every path must terminate. Dead ends are bugs.
- Terminal states are actions. "Escalate to {team}", "Run {fix}", or "Not a problem because {reason}".
- Each node references a specific tool or query. Not "check the database" but "run queries/slow-queries.sql".
- Include the expected output at each node. What does "DB slow" look like? (>200ms p99)
Step I4: Query Pattern Inventory
Collect reusable queries the agent can compose:
-- queries/slow-queries.sql
-- Find queries running longer than {threshold}ms
-- Usage: Replace {threshold} with desired ms (default: 1000)
SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE state != 'idle'
AND now() - pg_stat_activity.query_start > interval '{threshold} milliseconds'
ORDER BY duration DESC;
Query patterns must:
- Have a comment header explaining purpose and usage
- Use named parameters (not hardcoded values)
- Be syntactically valid for the target system
- Include expected output format
Step I5: Planning Checkpoint
Display symptom catalog, decision tree summaries, and query inventory as regular text. Then ask for approval:
Question: "Does this investigation plan look correct? Review the symptoms, decision trees, and queries above."
Header: "Plan Review"
Options:
- "Approve and proceed" - Start generation
- "Adjust symptoms" - User provides changes
- "Change tools/queries" - User provides different tools
- "Major revisions needed" - User describes changes
Only proceed after user approval.
Step I6: Generation
After user approval, generate in this order:
- Generate SKILL.md — Symptom overview, trigger phrases, quick reference to trees
- Generate references/symptoms.md — Full symptom catalog with entry points
- Generate references/{symptom}-tree.md — One decision tree per symptom class
- Generate references/queries/ — Reusable query patterns
- Generate assets/templates/report.md — Investigation report template
- Generate config.json — Service URLs, dashboard IDs, endpoints
- Generate metadata.json with
discipline: "investigation"and the appropriatetypefield - Generate gotchas.md — Initialize with "No known gotchas yet"
Step I7: Validate
- Automated validation:
node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js {output-base}/{skill-slug} - Agent quality review: Launch
skill-revieweragent with${CLAUDE_PLUGIN_ROOT}/templates/disciplines/investigation/RUBRIC.md
Type-Specific Guidance (Investigation)
Runbook Skills (Type 7)
Focus on: symptom → investigation → resolution.
- Every decision tree path terminates in an action (fix, escalate, or dismiss)
- Include severity assessment at each node (is this getting worse?)
- Reference specific dashboards and alert thresholds
- Include "usual suspects" — the top 3 causes for each symptom, ordered by frequency
- Store investigation history in
${CLAUDE_PLUGIN_DATA}/investigations.log
Runbook SKILL.md should include:
## Common Symptoms
| Symptom | Usual Cause | Quick Check |
|---------|-------------|-------------|
| High latency | Database locks | `queries/slow-queries.sql` |
| Error spike | Failed deploy | `git log --oneline -5` |
| OOM kills | Memory leak in {service} | `queries/memory-usage.sh` |
Data Analysis Skills (Type 8)
Focus on: query composition and data access patterns.
- Provide helper functions/queries the agent can compose for complex analysis
- Include table/schema documentation (what columns exist, what they mean)
- Define canonical IDs (which table has the authoritative
user_id?) - Include common joins and aggregation patterns
- Store query results in structured format for cross-query analysis
Data Analysis SKILL.md should include:
## Available Data Sources
| Source | Access | Key Tables |
|--------|--------|------------|
| Analytics DB | `queries/analytics-*.sql` | events, users, sessions |
| Billing API | `queries/billing-*.sh` | invoices, subscriptions |
Extraction Path (Type 4)
This pipeline analyzes frameworks, codebases, or conventions and derives parameterized templates and scaffolding instructions. It produces skills that eliminate boilerplate and enforce conventions.
Output Structure
{output-base}/{skill-slug}/
├── SKILL.md # Template catalog + trigger phrases
├── metadata.json # discipline: "extraction", type: "scaffolding"
├── config.json # Project-specific overrides (paths, naming)
├── gotchas.md # Scaffolding edge cases discovered over time
├── assets/
│ └── templates/
│ ├── {component-type}.template # Parameterized templates
│ └── {another-type}.template
└── references/
└── conventions.md # Conventions the templates enforce + rationale
Step E1: Interview
Ask the user:
- "What framework are you scaffolding for?"
- "What types of files/components do you create repeatedly?"
- "What varies between instances? (e.g., name, type, options)"
- "Are there conventions you want enforced? (naming, structure, patterns)"
Optionally ask to see an existing example:
- "Can you point me to a well-written example of each component type? I'll extract the pattern."
Step E2: Pattern Analysis
If the user provides example files, analyze them for:
- Fixed structure: Parts that stay the same across all instances
- Variable parts: Names, types, options that change per instance
- Conventions: Import ordering, naming patterns, file placement
- Boilerplate: Repetitive code that the template eliminates
If no examples: derive templates from framework documentation and best practices.
Step E3: Template Design
For each component type, design a parameterized template:
# Template: {Component Type}
## Parameters
| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| name | yes | — | Component name (PascalCase) |
| type | no | "default" | Variant type |
| features | no | [] | Feature flags to include |
## Output Files
| File | Path | Description |
|------|------|-------------|
| Component | `src/{module}/{name}.tsx` | Main component file |
| Test | `src/{module}/{name}.test.tsx` | Test file |
| Index | `src/{module}/index.ts` | Re-export (if new module) |
## Template Content
{The actual template with parameter placeholders}
Design principles:
- Minimal viable scaffold. Generate the structure, not the implementation.
- Convention-enforced. The template enforces naming, import order, file placement.
- Parameterized, not hardcoded. Every instance-specific value is a named parameter.
- Documented rationale. The conventions doc explains WHY.
Step E4: Convention Documentation
Write a conventions document explaining WHY each convention exists:
## File Naming: kebab-case
Files use kebab-case (e.g., `user-profile.tsx`).
**Why:** Filesystem case sensitivity across OS. Prevents "works on Mac, breaks on Linux."
## Import Order: external → internal → relative
**Why:** Consistent visual grouping. Auto-formatters preserve this order.
Step E5: Planning Checkpoint
Display template list, parameters, and conventions as regular text. Then ask for approval:
Question: "Does this scaffolding plan look correct? Review the templates, parameters, and conventions above."
Header: "Plan Review"
Options:
- "Approve and proceed" - Start generation
- "Adjust templates" - User provides changes
- "Change conventions" - User provides different conventions
- "Major revisions needed" - User describes changes
Only proceed after user approval.
Step E6: Generation
After user approval, generate in this order:
- Generate SKILL.md — Template catalog with parameters and usage examples
- Generate assets/templates/*.template — Parameterized template files
- Generate references/conventions.md — Convention documentation with rationale
- Generate config.json — Project-specific overrides (output paths, naming preferences)
- Generate metadata.json with
discipline: "extraction"andtype: "scaffolding" - Generate gotchas.md — Initialize with "No known gotchas yet"
Step E7: Validate
- Automated validation:
node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js {output-base}/{skill-slug} - Agent quality review: Launch
skill-revieweragent with${CLAUDE_PLUGIN_ROOT}/templates/disciplines/extraction/RUBRIC.md
Type-Specific Guidance (Extraction)
Framework Scaffolding
- Include templates for the 3-5 most common component types
- Each template produces all related files (component + test + types + index)
- Include a "new module" variant that also creates the directory structure
- Reference the framework's official scaffolding if it exists (e.g.,
rails generate)
Migration Scaffolding
- Template includes common gotchas (irreversible operations, data backfill)
- Include both "up" and "down" migration templates
- Reference the migration framework's documentation
- Flag operations that require special handling (column renames, index creation on large tables)
Internal Platform Scaffolding
- Templates pre-wire authentication, logging, and deployment config
- Include environment-specific configuration (dev, staging, prod)
- Reference the internal platform's documentation and CLI
Adversarial Path (Type 10)
This pipeline produces a pass/fail review gate: a skill that dispatches a single blind reviewer subagent, with an adversarial mandate, to judge work against a rule set. Any rule FAIL fails the gate; on FAIL, the verdict names what is missing to reach PASS.
Read ${CLAUDE_PLUGIN_ROOT}/templates/disciplines/adversarial/RECIPE.md — it is the authority on this discipline. The doctrine in brief:
- Decidability, not teaching. A rule earns its place in a gate only if a reviewer can decide PASS/FAIL from evidence in the artifact alone. Judgment calls ("prefer clean abstractions") make the gate flaky — they belong in a distillation skill, not here. With one reviewer there is no runtime disagreement signal, so decidability carries the whole weight of verdict stability.
- Blindness. The reviewer gets a self-contained prompt with no conversation context — a reviewer that watched the work being made grades on effort and passes it.
- Fail-closed. PASS requires every rule to be PASS or N/A; any single FAIL fails, an evidence-free PASS is forbidden, and no rule is severity-weighed or waived.
- Suggestions, not lectures. Every FAIL names the missing change and its location.
Output Structure
{output-base}/{skill-slug}/
├── SKILL.md # When to Apply + Review Protocol + Verdict Format
├── metadata.json # discipline: "adversarial", type: "adversarial-review"
├── references/
│ ├── _sections.md # Category definitions ┐ owned-rules mode only
│ ├── {prefix}-{slug}.md # Rules, distillation format ┘
│ ├── rules-source.md # Source skill pointer — companion mode only
│ └── reviewer-prompt.md # Self-contained prompt for the blind reviewer
├── assets/templates/
│ └── verdict.md # Verdict report template
└── gotchas.md
Exactly one rule mode exists per skill: owned rules (derived fresh) or companion (references an existing distillation skill's rules by path).
Step A1: Rule Source Selection
Ask the user with AskUserQuestion:
Question: "Where should this gate's rules come from?"
Header: "Rule Source"
Options:
- "Derive fresh — research the domain and write new decidable rules"
- "Companion — review against an existing distillation skill's rules"
If companion: ask for the source skill's path, then read its SKILL.md, metadata.json, references/_sections.md, and every rule file. Record the source path and version for rules-source.md.
Step A2: Derive or Filter Rules
Fresh mode: follow distillation's research method (wrong defaults, authoritative sources — see the Distillation Path), with one added test per rule: name the evidence that would prove a violation (a file, a line, a missing test, a pattern). A rule without nameable evidence is cut or rewritten until decidable.
Companion mode: apply the decidability test to each source rule:
- Import rules where PASS/FAIL is decidable from artifact evidence alone — record what evidence decides each.
- Exclude teaching-material rules (taste words, unmeasurable boundaries) — record each with its reason. Exclusions are listed, never silent.
Step A3: Planning Checkpoint
Display the plan as regular text first (never inside AskUserQuestion):
## Adversarial Gate Planning Review
### Rule Mode
{Owned rules | Companion to {source-skill-path} (version {v})}
### Rules to Enforce
| Rule | Category | Evidence that decides it |
|------|----------|--------------------------|
| ... | ... | ... |
### Excluded Rules (companion mode)
| Rule | Why excluded |
|------|--------------|
### Review Targets
{What artifacts this gate reviews: diffs, files, PRs, generated skills, ...}
Then ask for approval:
Question: "Does this gate plan look correct? Review the rules, deciding evidence, and exclusions above."
Header: "Plan Review"
Options:
- "Approve and proceed" - Start generation
- "Adjust rules" - User provides changes
- "Change rule source" - Switch mode or source skill
- "Major revisions needed" - User describes changes
Only proceed after user approval.
Step A4: Generation
Read the templates in ${CLAUDE_PLUGIN_ROOT}/templates/disciplines/adversarial/ and fill them — do not reproduce the structures from memory. Generate in this order:
- Rules — owned mode:
references/_sections.md+ rule files (distillation format,RULE.md.templatefrom the distillation discipline); companion mode:references/rules-source.mdfromrules-source.md.template references/reviewer-prompt.md— fromreviewer-prompt.md.template; the composed prompt must be fully self-contained (rules, target, output format — no conversation references), because blindness is the gate's only defense against pass biasassets/templates/verdict.md— fromverdict.md.templateSKILL.md— fromSKILL.md.template, with the mode-appropriate rules-loading instruction; companion mode must instruct: if the source skill is missing, stop and report — never silently passmetadata.json—discipline: "adversarial",type: "adversarial-review"; companion mode also records the source skill path inreferencesgotchas.md— initialize with "No known gotchas yet"
Step A5: Validate
- Automated validation:
node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js {output-base}/{skill-slug} - Agent quality review: Launch
skill-revieweragent with${CLAUDE_PLUGIN_ROOT}/templates/disciplines/adversarial/RUBRIC.md
Step A6: Prove the Gate
A gate that has never failed anything is unproven. Dry-run the review protocol on two artifacts: one that should PASS and one that should FAIL (ask the user for candidates, or construct a minimal failing example). A dry-run verdict that doesn't match the expected outcome, or that can't be defended from its cited evidence alone, means a rule needs sharpening before release — fix the rule, re-run, and record the pattern in gotchas.md.
Navigation Path (Type 11)
This pipeline produces a documentation navigation skill: a map of where authoritative information about a technology lives, search playbooks for finding it, and verification rules for judging what comes back. It is the inverse of distillation — knowledge is fetched live at answer time, never baked in.
Read ${CLAUDE_PLUGIN_ROOT}/templates/disciplines/navigation/RECIPE.md — it is the authority on this discipline. The doctrine in brief:
- The staleness litmus test. A navigation skill contains zero baked-in technical facts. Before keeping any line, ask: would this line need editing when the technology ships a new version? URL patterns, version schemes, and search operators are navigational — keep them. API signatures, behavior claims, and defaults are facts — cut them; the skill routes to them instead.
- Authority is ranked and scoped both ways. Official docs/spec > source code > changelog > issue tracker > maintainer writing. Every source states what it is authoritative for AND what it is not. Community content is a lead generator, never a terminal answer.
- Playbooks name tools, not intentions. Every step is a concrete invocation ("WebFetch
{docs}/reference/{symbol}", "WebSearch:\"{error}\" site:github.com/{org}/{repo}/issues") with a stated hit criterion. "Search the web" is not a step. - Every path terminates, every answer verifies. The last step is an explicit escalation (read source at a named location, or ask the user), and no answer is accepted without the currency/authority checks.
Output Structure
{output-base}/{skill-slug}/
├── SKILL.md # When to Apply + Source Map quick reference
├── metadata.json # discipline: "navigation", type: "doc-navigation"
├── config.json # Optional: local doc paths, MCP tools, internal mirrors
├── gotchas.md # Search dead-ends discovered over time
└── references/
├── sources.md # Ranked authority map with access patterns
├── {question}-playbook.md # One search playbook per question type
└── verification.md # Currency + authority checks for found answers
Step N1: Interview
Ask the user free-form:
- "What technology (and which parts of it) should this skill cover?"
- "What questions come up most? (API lookups, upgrade/breaking changes, error messages, configuration, examples?)"
- "What search tools are available in your sessions? (web access, local doc directories, doc-search scripts, MCP servers)"
- "Any internal sources — mirrors, wikis, pinned versions — that outrank public docs for your team?"
Step N2: Source Census (No User Interruption)
Enumerate candidate sources in default authority order (official docs/spec, source code + types, changelog/release notes, issue tracker, maintainer writing), then verify each live — fetch it with WebFetch/WebSearch, confirm it is current, and record:
- Deep-link URL patterns (parameterized, e.g.
https://pkg.go.dev/{module}@{version}), not just homepages - Authoritative for / NOT authoritative for — both directions
- Currency signals — how to tell which version a page describes
- Access pattern — the concrete tool invocation
Drop any source that is dead, redirects elsewhere, or is a content farm.
Step N3: Derive Question Types & Playbooks
Group the user's real lookups into 3–7 question types (common set: api-lookup, version-changes, error-message, configuration, examples-idioms — derive, don't force). For each, design an ordered playbook per the RECIPE rules: concrete tool + query per step, hit criterion per step, cheap high-precision steps first, terminal escalation last, verification as the exit.
Step N4: Planning Checkpoint
Display the plan as regular text first (never inside AskUserQuestion):
## Navigation Skill Planning Review
### Source Map
| # | Source | Authoritative for | NOT authoritative for | Access | Verified live |
|---|--------|-------------------|-----------------------|--------|---------------|
### Question Types & Playbooks
| Question type | Example question | Playbook steps (summary) |
|---------------|------------------|--------------------------|
### Verification Rules
{Currency check, authority check, rejection criteria, cross-check rule}
Then ask for approval:
Question: "Does this navigation plan look correct? Review the sources, authority scopes, and playbooks above."
Header: "Plan Review"
Options:
- "Approve and proceed" - Start generation
- "Adjust sources" - User provides different sources
- "Adjust question types" - User provides changes
- "Major revisions needed" - User describes changes
Only proceed after user approval.
Step N5: Generation
Read the templates in ${CLAUDE_PLUGIN_ROOT}/templates/disciplines/navigation/ and fill them — do not reproduce the structures from memory:
| Template | Produces |
|---|---|
SKILL.md.template | Entry point: When to Apply, Source Map table, playbook routing |
sources.md.template | references/sources.md — full ranked source map |
playbook.md.template | references/{question}-playbook.md — one per question type |
verification.md.template | references/verification.md — currency/authority/rejection rules |
Generate in this order:
- Generate references/sources.md — the verified source map from Step N2
- Generate references/{question}-playbook.md — one per question type
- Generate references/verification.md — currency, authority, and rejection rules
- Generate SKILL.md — Source Map quick reference + playbook routing table
- Generate config.json — only if local paths / MCP tools / internal mirrors exist
- Generate metadata.json with
discipline: "navigation"andtype: "doc-navigation"; put the verified source URLs inreferences - Generate gotchas.md — initialize with "No known gotchas yet"
Step N6: Validate
- Automated validation:
node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js {output-base}/{skill-slug} - Agent quality review: Launch
skill-revieweragent with${CLAUDE_PLUGIN_ROOT}/templates/disciplines/navigation/RUBRIC.md— its first check is the staleness audit: any baked-in technical fact fails
Quality Checklist (Navigation)
- Zero baked-in technical facts — every line survives the "new version ships" litmus test
- Every source URL and at least one deep-link pattern verified live during generation
- Every source states its authority scope both ways (for / not for)
- Every playbook step names a concrete tool + query with a hit criterion
- Every playbook terminates in an explicit escalation and exits through verification
- Verification rules name concrete rejection tells, not just "avoid bad sources"
Common Elements (All Paths)
Output Location
All generated files go under {output-base}/{skill-slug}/ where {output-base} is the path chosen in Step 0.
metadata.json
Every skill's metadata.json MUST include discipline and type fields:
{
"version": "0.1.0",
"organization": "{Organization}",
"technology": "{Technology or Domain}",
"discipline": "{distillation|composition|extraction|investigation|adversarial|navigation}",
"type": "{library-reference|verification|automation|scaffolding|code-quality|cicd|runbook|data-analysis|infra-ops|adversarial-review|doc-navigation}",
"date": "{Month Year}",
"abstract": "{1-2 sentence summary}",
"references": ["{url1}", "{url2}"]
}
Validation (Always Required)
Every path ends with the same two-phase validation:
-
Structural validation:
node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js {output-base}/{skill-slug}- Fix ALL errors before proceeding
- Address warnings where feasible
-
Discipline-specific review: Launch
skill-revieweragent with the discipline's RUBRIC.md:- Distillation:
${CLAUDE_PLUGIN_ROOT}/templates/disciplines/distillation/RUBRIC.md - Composition:
${CLAUDE_PLUGIN_ROOT}/templates/disciplines/composition/RUBRIC.md - Investigation:
${CLAUDE_PLUGIN_ROOT}/templates/disciplines/investigation/RUBRIC.md - Extraction:
${CLAUDE_PLUGIN_ROOT}/templates/disciplines/extraction/RUBRIC.md - Adversarial:
${CLAUDE_PLUGIN_ROOT}/templates/disciplines/adversarial/RUBRIC.md - Navigation:
${CLAUDE_PLUGIN_ROOT}/templates/disciplines/navigation/RUBRIC.md
- Distillation:
Complementary Skill Suggestions
After completing generation, suggest related skills from other disciplines:
| Created Skill Type | Suggested Complement |
|---|---|
| CI/CD & Deployment | "Consider creating a Runbook skill for rollback diagnostics." |
| Library/API Reference | "Consider creating a Code Scaffolding skill for this framework's boilerplate." |
| Product Verification | "Consider creating a Workflow Automation skill to run this verification as part of CI." |
| Runbook | "Consider creating a Data Analysis skill for the metrics this runbook references." |
| Code Scaffolding | "Consider creating a Code Quality skill to enforce the conventions these templates produce." |
| Workflow Automation | "Consider creating a Product Verification skill to assert the workflow's output." |
| Data Analysis | "Consider creating a Runbook skill for when query results reveal problems." |
| Infrastructure Ops | "Consider creating a Runbook skill for incident response on this infrastructure." |
| Code Quality & Review | "Consider creating a Code Scaffolding skill to generate code that passes these reviews." |
| Library/API Reference or Code Quality & Review | "Consider creating an Adversarial Review companion gate that enforces these rules with a blind adversarial reviewer." |
| Adversarial Review | "Consider creating a Code Quality (Distillation) skill for the judgment-call guidance the gate had to exclude." |
| Documentation Navigation | "Consider creating a Library/API Reference (Distillation) skill for the wrong defaults the model has today — the two compose: distillation corrects, navigation keeps current." |
| Library/API Reference | "Consider creating a Documentation Navigation skill so version-sensitive questions are answered from live sources instead of the snapshot." |
Reference Files
Anatomy and Recipes
${CLAUDE_PLUGIN_ROOT}/templates/
├── anatomy/
│ └── ANATOMY.md # Universal skill patterns (READ FIRST)
└── disciplines/
├── distillation/
│ ├── RECIPE.md # Distillation methodology
│ └── RUBRIC.md # Distillation validation rubric
├── composition/
│ ├── RECIPE.md # Composition methodology
│ └── RUBRIC.md # Composition validation rubric
├── investigation/
│ ├── RECIPE.md # Investigation methodology
│ └── RUBRIC.md # Investigation validation rubric
├── extraction/
│ ├── RECIPE.md # Extraction methodology
│ └── RUBRIC.md # Extraction validation rubric
├── adversarial/
│ ├── RECIPE.md # Adversarial methodology
│ └── RUBRIC.md # Adversarial validation rubric
└── navigation/
├── RECIPE.md # Navigation methodology
└── RUBRIC.md # Navigation validation rubric
Automation Scripts
${CLAUDE_PLUGIN_ROOT}/scripts/
├── validate-skill.js # Validates generated skill against guidelines
└── build-agents-md.js # Builds AGENTS.md for distillation skills
Validation Agents
${CLAUDE_PLUGIN_ROOT}/agents/
├── preflight-validator.md # Validates planning before generation (distillation)
└── skill-reviewer.md # Reviews quality criteria (all disciplines)
Reference Examples (Distillation)
${CLAUDE_PLUGIN_ROOT}/references/
├── QUALITY_CHECKLIST.md # Authoritative validation checklist
├── COMPLETE_EXAMPLE.md # Full React example with all rule samples
├── metadata.json # Full metadata example
└── examples/ # 12 sample rules across all categories
├── _sections.md # Complete sections template (8 categories)
├── _template.md # Rule template with frontmatter
└── {prefix}-*.md # Sample rule files
Mandatory Requirements
NEVER:
- Skip validation steps (automated or agent-based)
- Generate without user-approved planning
- Release without running
validate-skill.jsANDskill-revieweragent - Use generic placeholder names (foo, bar, MyComponent) in code examples
- Write AGENTS.md manually (use build-agents-md.js)
ALWAYS:
- Read
${CLAUDE_PLUGIN_ROOT}/templates/anatomy/ANATOMY.mdbefore generating any skill - Read the discipline's
RECIPE.mdbefore generating - Use the discipline's
RUBRIC.mdfor theskill-revieweragent - Include
disciplineandtypein metadata.json - Display planning summaries as regular text BEFORE calling AskUserQuestion
Every rule (distillation) MUST include:
- YAML frontmatter:
titleandtags(first tag = category prefix).impact/impactDescriptionare optional (performance skills only). - A 1-3 sentence WHY that names the wrong default it corrects and the consequence.
- At least one code example (a single canonical example by default), with a language specifier and realistic names.
An Incorrect/Correct foil is optional — include it only when the wrong way is a real, common trap, and never as a strawman. A rule that restates what the model already does right should not exist at all.
Now create the skill based on the user's selections, following the discipline-specific pipeline exactly.
Shrink AGENTS.md Command
Regenerate the AGENTS.md file for a skill as a slim Table of Contents with links to individual rule files, removing embedded content.
What This Does
Runs the build-agents-md.js script which transforms AGENTS.md from a 600+ line document with all rule content embedded into a ~65 line navigation document containing:
- Header, Abstract, Note block
- Table of Contents with file links and impact levels for each rule
- References section
- Source Files footer
Usage
/dev-skill:shrink <skill-path>
Examples:
/dev-skill:shrink ~/.claude/skills/react-best-practices/dev-skill:shrink ./my-skill
Execution
Run the build script:
node "${CLAUDE_PLUGIN_ROOT}/scripts/build-agents-md.js" "<skill-path>"
The script will:
- Find rule files in
references/,examples/, orrules/directory - Generate TOC with links to each rule file
- Include impact level and description for each rule
- Output statistics (sections, rules, line count)
Before/After Example
Before (embedded content, ~600 lines):
## Table of Contents
1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
- 1.1 [Dependency-Based Parallelization](#11-dependency-based-parallelization)
---
## 1. Eliminating Waterfalls
**Impact: CRITICAL**
Waterfalls are the #1 performance killer...
### 1.1 Dependency-Based Parallelization
**Impact: CRITICAL (2-10× improvement)**
For operations with partial dependencies...
[full rule content continues for hundreds of lines]
After (TOC-only, ~65 lines):
## Table of Contents
1. [Eliminating Waterfalls](examples/_sections.md#1-eliminating-waterfalls) — **CRITICAL**
- 1.1 [Dependency-Based Parallelization](examples/async-dependencies.md) — CRITICAL (2-10× improvement)
- 1.2 [Promise.all() for Independent Operations](examples/async-parallel.md) — CRITICAL (2-10× improvement)
Benefits
- 90% smaller AGENTS.md file
- Faster agent parsing - quick priority scan without scrolling through content
- Direct navigation - click to open specific rule file
- Clear prioritization - impact level visible for every rule in TOC
Skill Validator
You are a validation utility that runs both structural and substance checks on an existing skill. You produce a unified report and actionable fix guidance.
Input Required
You will receive a path to an existing skill (e.g., ~/.claude/skills/react-best-practices).
Store the skill path as {skill-path} for all subsequent operations.
Step 1: Detect Discipline
- Read
{skill-path}/metadata.jsonand extract thedisciplinefield - If no
disciplinefield exists, infer from directory structure:- Has
references/reviewer-prompt.md→adversarial - Has
references/sources.mdplus*-playbook.mdfiles →navigation - Has
references/with rule files containingimpactin frontmatter →distillation - Has
scripts/directory →composition - Has
references/with*-tree.mdfiles orreferences/queries/→investigation - Has
assets/templates/*.templatefiles →extraction - Default fallback →
distillation(backwards compatible)
- Has
- Also extract the
typefield from metadata if present
Report the detected discipline and type before proceeding.
Step 2: Structural Validation
Run the automated validator:
node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.js {skill-path}
Parse and group all findings by severity:
- ERROR — blocking issues that must be fixed
- WARNING — notable issues that should be addressed
- INFO — suggestions for improvement
Record the error count, warning count, and pass/fail status.
Step 3: Substance Validation
Launch the skill-reviewer agent via the Task tool:
subagent_type: "dev-skill:skill-reviewer"
prompt: "Review the skill at {skill-path}.
Read the validation rubric at ${CLAUDE_PLUGIN_ROOT}/templates/disciplines/{discipline}/RUBRIC.md and follow it exactly.
Provide your full review report with verdict."
Wait for the reviewer to complete before proceeding.
Step 4: Combined Report
Present a unified validation report:
## Validation Report: {skill-name}
**Discipline:** {discipline}
**Type:** {type}
### Structural Checks (validate-skill.js)
- Errors: {N}
- Warnings: {N}
- Status: {PASS / FAIL}
{List each error and warning with file path and description}
### Substance Checks (skill-reviewer)
- Verdict: {SHIP / NEEDS WORK / REJECT}
{Reviewer findings — key strengths, issues, and recommendations}
### Overall Status: {PASS / NEEDS WORK / FAIL}
Overall status logic:
- PASS — zero structural errors AND reviewer verdict is SHIP
- NEEDS WORK — only warnings or reviewer says NEEDS WORK
- FAIL — any structural errors OR reviewer verdict is REJECT
Step 5: Fix Guidance
If issues were found, provide actionable guidance:
For each error or finding:
- State the problem clearly with the affected file path
- Describe what specifically needs to change
- Indicate severity (blocking vs. recommended)
End with:
### Next Steps
To apply automated fixes, run:
`/dev-skill:evolve {skill-path}`
If zero issues were found, congratulate the user and confirm the skill is ready for use.
Mandatory Requirements
NEVER:
- Skip either validation track — always run both structural and substance checks
- Fabricate validator output or reviewer findings
- Apply fixes automatically — this command only reports, it does not modify files
ALWAYS:
- Detect discipline before running substance checks (the rubric depends on it)
- Wait for both validation tracks to complete before presenting the report
- Include specific file paths and descriptions for every finding
- Keep the report concise and scannable
Agents 4
Post-hoc Analyzer Agent
Analyze blind comparison results to understand WHY the winner won and generate improvement suggestions.
Role
After the blind comparator determines a winner, the Post-hoc Analyzer "unblids" the results by examining the skills and transcripts. The goal is to extract actionable insights: what made the winner better, and how can the loser be improved?
Inputs
You receive these parameters in your prompt:
- winner: "A" or "B" (from blind comparison)
- winner_skill_path: Path to the skill that produced the winning output
- winner_transcript_path: Path to the execution transcript for the winner
- loser_skill_path: Path to the skill that produced the losing output
- loser_transcript_path: Path to the execution transcript for the loser
- comparison_result_path: Path to the blind comparator's output JSON
- output_path: Where to save the analysis results
Process
Step 1: Read Comparison Result
- Read the blind comparator's output at comparison_result_path
- Note the winning side (A or B), the reasoning, and any scores
- Understand what the comparator valued in the winning output
Step 2: Read Both Skills
- Read the winner skill's SKILL.md and key referenced files
- Read the loser skill's SKILL.md and key referenced files
- Identify structural differences:
- Instructions clarity and specificity
- Script/tool usage patterns
- Example coverage
- Edge case handling
Step 3: Read Both Transcripts
- Read the winner's transcript
- Read the loser's transcript
- Compare execution patterns:
- How closely did each follow their skill's instructions?
- What tools were used differently?
- Where did the loser diverge from optimal behavior?
- Did either encounter errors or make recovery attempts?
Step 4: Analyze Instruction Following
For each transcript, evaluate:
- Did the agent follow the skill's explicit instructions?
- Did the agent use the skill's provided tools/scripts?
- Were there missed opportunities to leverage skill content?
- Did the agent add unnecessary steps not in the skill?
Score instruction following 1-10 and note specific issues.
Step 5: Identify Winner Strengths
Determine what made the winner better:
- Clearer instructions that led to better behavior?
- Better scripts/tools that produced better output?
- More comprehensive examples that guided edge cases?
- Better error handling guidance?
Be specific. Quote from skills/transcripts where relevant.
Step 6: Identify Loser Weaknesses
Determine what held the loser back:
- Ambiguous instructions that led to suboptimal choices?
- Missing tools/scripts that forced workarounds?
- Gaps in edge case coverage?
- Poor error handling that caused failures?
Step 7: Generate Improvement Suggestions
Based on the analysis, produce actionable suggestions for improving the loser skill:
- Specific instruction changes to make
- Tools/scripts to add or modify
- Examples to include
- Edge cases to address
Prioritize by impact. Focus on changes that would have changed the outcome.
Step 8: Write Analysis Results
Save structured analysis to {output_path}.
Output Format
Write a JSON file with this structure:
{
"comparison_summary": {
"winner": "A",
"winner_skill": "path/to/winner/skill",
"loser_skill": "path/to/loser/skill",
"comparator_reasoning": "Brief summary of why comparator chose winner"
},
"winner_strengths": [
"Clear step-by-step instructions for handling multi-page documents",
"Included validation script that caught formatting errors",
"Explicit guidance on fallback behavior when OCR fails"
],
"loser_weaknesses": [
"Vague instruction 'process the document appropriately' led to inconsistent behavior",
"No script for validation, agent had to improvise and made errors",
"No guidance on OCR failure, agent gave up instead of trying alternatives"
],
"instruction_following": {
"winner": {
"score": 9,
"issues": [
"Minor: skipped optional logging step"
]
},
"loser": {
"score": 6,
"issues": [
"Did not use the skill's formatting template",
"Invented own approach instead of following step 3",
"Missed the 'always validate output' instruction"
]
}
},
"improvement_suggestions": [
{
"priority": "high",
"category": "instructions",
"suggestion": "Replace 'process the document appropriately' with explicit steps: 1) Extract text, 2) Identify sections, 3) Format per template",
"expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
},
{
"priority": "high",
"category": "tools",
"suggestion": "Add validate_output.py script similar to winner skill's validation approach",
"expected_impact": "Would catch formatting errors before final output"
},
{
"priority": "medium",
"category": "error_handling",
"suggestion": "Add fallback instructions: 'If OCR fails, try: 1) different resolution, 2) image preprocessing, 3) manual extraction'",
"expected_impact": "Would prevent early failure on difficult documents"
}
],
"transcript_insights": {
"winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script -> Fixed 2 issues -> Produced output",
"loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods -> No validation -> Output had errors"
}
}
Guidelines
- Be specific: Quote from skills and transcripts, don't just say "instructions were unclear"
- Be actionable: Suggestions should be concrete changes, not vague advice
- Focus on skill improvements: The goal is to improve the losing skill, not critique the agent
- Prioritize by impact: Which changes would most likely have changed the outcome?
- Consider causation: Did the skill weakness actually cause the worse output, or is it incidental?
- Stay objective: Analyze what happened, don't editorialize
- Think about generalization: Would this improvement help on other evals too?
Categories for Suggestions
Use these categories to organize improvement suggestions:
| Category | Description |
|---|---|
instructions | Changes to the skill's prose instructions |
tools | Scripts, templates, or utilities to add/modify |
examples | Example inputs/outputs to include |
error_handling | Guidance for handling failures |
structure | Reorganization of skill content |
references | External docs or resources to add |
Priority Levels
- high: Would likely change the outcome of this comparison
- medium: Would improve quality but may not change win/loss
- low: Nice to have, marginal improvement
Analyzing Benchmark Results
When analyzing benchmark results, the analyzer's purpose is to surface patterns and anomalies across multiple runs, not suggest skill improvements.
Role
Review all benchmark run results and generate freeform notes that help the user understand skill performance. Focus on patterns that wouldn't be visible from aggregate metrics alone.
Inputs
You receive these parameters in your prompt:
- benchmark_data_path: Path to the in-progress benchmark.json with all run results
- skill_path: Path to the skill being benchmarked
- output_path: Where to save the notes (as JSON array of strings)
Process
Step 1: Read Benchmark Data
- Read the benchmark.json containing all run results
- Note the configurations tested (with_skill, without_skill)
- Understand the run_summary aggregates already calculated
Step 2: Analyze Per-Assertion Patterns
For each expectation across all runs:
- Does it always pass in both configurations? (may not differentiate skill value)
- Does it always fail in both configurations? (may be broken or beyond capability)
- Does it always pass with skill but fail without? (skill clearly adds value here)
- Does it always fail with skill but pass without? (skill may be hurting)
- Is it highly variable? (flaky expectation or non-deterministic behavior)
Step 3: Analyze Cross-Eval Patterns
Look for patterns across evals:
- Are certain eval types consistently harder/easier?
- Do some evals show high variance while others are stable?
- Are there surprising results that contradict expectations?
Step 4: Analyze Metrics Patterns
Look at time_seconds, tokens, tool_calls:
- Does the skill significantly increase execution time?
- Is there high variance in resource usage?
- Are there outlier runs that skew the aggregates?
Step 5: Generate Notes
Write freeform observations as a list of strings. Each note should:
- State a specific observation
- Be grounded in the data (not speculation)
- Help the user understand something the aggregate metrics don't show
Examples:
- "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value"
- "Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure that may be flaky"
- "Without-skill runs consistently fail on table extraction expectations (0% pass rate)"
- "Skill adds 13s average execution time but improves pass rate by 50%"
- "Token usage is 80% higher with skill, primarily due to script output parsing"
- "All 3 without-skill runs for eval 1 produced empty output"
Step 6: Write Notes
Save notes to {output_path} as a JSON array of strings:
[
"Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
"Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure",
"Without-skill runs consistently fail on table extraction expectations",
"Skill adds 13s average execution time but improves pass rate by 50%"
]
Guidelines
DO:
- Report what you observe in the data
- Be specific about which evals, expectations, or runs you're referring to
- Note patterns that aggregate metrics would hide
- Provide context that helps interpret the numbers
DO NOT:
- Suggest improvements to the skill (that's for the improvement step, not benchmarking)
- Make subjective quality judgments ("the output was good/bad")
- Speculate about causes without evidence
- Repeat information already in the run_summary aggregates
Blind Comparator Agent
Compare two outputs WITHOUT knowing which skill produced them.
Role
The Blind Comparator judges which output better accomplishes the task. You receive two outputs labeled A and B, but you do NOT know which skill produced which. This prevents bias toward a particular skill or approach.
Your judgment is based purely on output quality and task completion.
Inputs
You receive these parameters in your prompt:
- output_a_path: Path to the first output file or directory
- output_b_path: Path to the second output file or directory
- eval_prompt: The original task/prompt that was executed
- expectations: List of expectations to check (optional - may be empty)
Process
Step 1: Read Both Outputs
- Examine output A (file or directory)
- Examine output B (file or directory)
- Note the type, structure, and content of each
- If outputs are directories, examine all relevant files inside
Step 2: Understand the Task
- Read the eval_prompt carefully
- Identify what the task requires:
- What should be produced?
- What qualities matter (accuracy, completeness, format)?
- What would distinguish a good output from a poor one?
Step 3: Generate Evaluation Rubric
Based on the task, generate a rubric with two dimensions:
Content Rubric (what the output contains):
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|---|---|---|---|
| Correctness | Major errors | Minor errors | Fully correct |
| Completeness | Missing key elements | Mostly complete | All elements present |
| Accuracy | Significant inaccuracies | Minor inaccuracies | Accurate throughout |
Structure Rubric (how the output is organized):
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|---|---|---|---|
| Organization | Disorganized | Reasonably organized | Clear, logical structure |
| Formatting | Inconsistent/broken | Mostly consistent | Professional, polished |
| Usability | Difficult to use | Usable with effort | Easy to use |
Adapt criteria to the specific task. For example:
- PDF form → "Field alignment", "Text readability", "Data placement"
- Document → "Section structure", "Heading hierarchy", "Paragraph flow"
- Data output → "Schema correctness", "Data types", "Completeness"
Step 4: Evaluate Each Output Against the Rubric
For each output (A and B):
- Score each criterion on the rubric (1-5 scale)
- Calculate dimension totals: Content score, Structure score
- Calculate overall score: Average of dimension scores, scaled to 1-10
Step 5: Check Assertions (if provided)
If expectations are provided:
- Check each expectation against output A
- Check each expectation against output B
- Count pass rates for each output
- Use expectation scores as secondary evidence (not the primary decision factor)
Step 6: Determine the Winner
Compare A and B based on (in priority order):
- Primary: Overall rubric score (content + structure)
- Secondary: Assertion pass rates (if applicable)
- Tiebreaker: If truly equal, declare a TIE
Be decisive - ties should be rare. One output is usually better, even if marginally.
Step 7: Write Comparison Results
Save results to a JSON file at the path specified (or comparison.json if not specified).
Output Format
Write a JSON file with this structure:
{
"winner": "A",
"reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
"rubric": {
"A": {
"content": {
"correctness": 5,
"completeness": 5,
"accuracy": 4
},
"structure": {
"organization": 4,
"formatting": 5,
"usability": 4
},
"content_score": 4.7,
"structure_score": 4.3,
"overall_score": 9.0
},
"B": {
"content": {
"correctness": 3,
"completeness": 2,
"accuracy": 3
},
"structure": {
"organization": 3,
"formatting": 2,
"usability": 3
},
"content_score": 2.7,
"structure_score": 2.7,
"overall_score": 5.4
}
},
"output_quality": {
"A": {
"score": 9,
"strengths": ["Complete solution", "Well-formatted", "All fields present"],
"weaknesses": ["Minor style inconsistency in header"]
},
"B": {
"score": 5,
"strengths": ["Readable output", "Correct basic structure"],
"weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
}
},
"expectation_results": {
"A": {
"passed": 4,
"total": 5,
"pass_rate": 0.80,
"details": [
{"text": "Output includes name", "passed": true},
{"text": "Output includes date", "passed": true},
{"text": "Format is PDF", "passed": true},
{"text": "Contains signature", "passed": false},
{"text": "Readable text", "passed": true}
]
},
"B": {
"passed": 3,
"total": 5,
"pass_rate": 0.60,
"details": [
{"text": "Output includes name", "passed": true},
{"text": "Output includes date", "passed": false},
{"text": "Format is PDF", "passed": true},
{"text": "Contains signature", "passed": false},
{"text": "Readable text", "passed": true}
]
}
}
}
If no expectations were provided, omit the expectation_results field entirely.
Field Descriptions
- winner: "A", "B", or "TIE"
- reasoning: Clear explanation of why the winner was chosen (or why it's a tie)
- rubric: Structured rubric evaluation for each output
- content: Scores for content criteria (correctness, completeness, accuracy)
- structure: Scores for structure criteria (organization, formatting, usability)
- content_score: Average of content criteria (1-5)
- structure_score: Average of structure criteria (1-5)
- overall_score: Combined score scaled to 1-10
- output_quality: Summary quality assessment
- score: 1-10 rating (should match rubric overall_score)
- strengths: List of positive aspects
- weaknesses: List of issues or shortcomings
- expectation_results: (Only if expectations provided)
- passed: Number of expectations that passed
- total: Total number of expectations
- pass_rate: Fraction passed (0.0 to 1.0)
- details: Individual expectation results
Guidelines
- Stay blind: DO NOT try to infer which skill produced which output. Judge purely on output quality.
- Be specific: Cite specific examples when explaining strengths and weaknesses.
- Be decisive: Choose a winner unless outputs are genuinely equivalent.
- Output quality first: Assertion scores are secondary to overall task completion.
- Be objective: Don't favor outputs based on style preferences; focus on correctness and completeness.
- Explain your reasoning: The reasoning field should make it clear why you chose the winner.
- Handle edge cases: If both outputs fail, pick the one that fails less badly. If both are excellent, pick the one that's marginally better.
Pre-flight Planning Validator
You validate a skill plan before generation begins. Your goal is to catch conceptual mistakes early — before significant generation effort is wasted.
Input
You will receive:
- Discipline — distillation, composition, investigation, extraction, or adversarial
- Technology/domain being documented
- Plan details — varies by discipline (see below)
Discipline-Specific Validation
For Distillation Plans
You will receive:
- The list of wrong defaults the skill intends to correct (its scope)
- Proposed categories with prefixes (impact tiers only if it's a performance skill)
- The vetted source list
Check:
- Wrong-default validity. For each planned rule, is the stated "wrong default" something a capable model actually gets wrong? Flag any that just restate a default the model already handles correctly — those are hand-holding and should be cut, not generated.
- Category sanity. Would a senior engineer recognize these categories for this technology? Any obvious gaps in the decision space?
- Ordering. Are categories in importance order? (Performance skills: is the top category genuinely the most damaging when wrong? WebSearch if unsure.)
- Overlaps & prefixes. Do categories cover the same ground (→ duplicate rules)? Are prefixes distinct (
mem-vsmemo-will confuse)? - Source authority. For each source: maintainer / spec / named expert, and current? Use WebFetch to spot-check 3-5. Flag content farms, listicles, undated blogs, and AI-SEO filler for replacement.
- Coverage, not count. Do the planned rules cover the wrong defaults that matter for this tech? Judge by the decision space and the eval prompts — not by a target number. There is no minimum or maximum rule count; padding to a number is a defect.
For Composition Plans
You will receive:
- Workflow steps with tools and actions
- Risk level assessment
- Success criteria
Check:
- Workflow completeness. Do the steps cover the full process from trigger to verification?
- Tool availability. Are the referenced tools/MCPs commonly available? Flag obscure dependencies.
- Risk assessment accuracy. Is the risk level (read-only/write/destructive) correct? Are destructive operations identified?
- Guardrail sufficiency. For destructive workflows: is there a guardrail plan? Dry-run mode? Confirmation prompts?
- Success criteria measurability. Can the success criteria be programmatically asserted, or are they subjective?
- Failure path coverage. For each step: is there a plan for what happens when it fails?
For Investigation Plans
You will receive:
- Domain/service description
- Symptom catalog
- Available tools and queries
Check:
- Symptom coverage. Do the symptoms cover the common issues for this domain? Use WebSearch for "{domain} common issues" to identify gaps.
- Tool relevance. Are the investigation tools appropriate for the symptoms? Can they actually provide the data needed?
- Decision tree feasibility. For each symptom: can a decision tree realistically guide investigation, or is the problem space too unstructured?
- Terminal state coverage. Do planned decision trees have clear terminal states (fix, escalate, dismiss)?
For Extraction Plans
You will receive:
- Target framework and component types
- Customization parameters
- Conventions to enforce
Check:
- Component type relevance. Are these the types people actually scaffold frequently for this framework?
- Parameter completeness. Do the parameters cover the real variation points? Are there missing parameters that would force manual edits?
- Convention validity. Are the conventions current best practice for this framework? Use WebSearch to verify.
- Framework idiom alignment. Do the planned templates follow the framework's own patterns, or impose external conventions?
For Adversarial Plans
You will receive:
- Rule mode (owned rules or companion to an existing distillation skill)
- The rules to enforce, each with the evidence that decides it
- Excluded rules with reasons (companion mode)
- The review targets (diffs, files, artifacts)
Check:
- Decidability. For each rule: is the stated deciding evidence concrete enough that two competent reviewers would reach the same PASS/FAIL on the same artifact? (The gate runs a single blind reviewer, so this thought experiment is the only stability check the rule will ever get.) Flag taste words ("clean", "appropriate", "prefer") without a measurable boundary.
- Dead weight. Is each rule a check a capable model's output could actually fail? Rules that always pass dilute the gate.
- Exclusion honesty (companion mode). Are the excluded rules genuinely undecidable, or were enforceable rules dropped? Is every source rule accounted for in one of the two lists?
- Gate fit. Could the whole rule set be decided by a deterministic linter/script instead? If so, recommend a composition (verification) skill — reviewer subagents are for checks that need judgment applied to evidence.
Output
## Pre-flight Validation: {technology/domain}
**Discipline:** {discipline}
**Verdict:** PROCEED / REVIEW / BLOCK
{One paragraph summary}
---
### Assessment
| # | Check | Verdict | Notes |
|---|-------|---------|-------|
| 1 | {check} | OK / ISSUE | {detail} |
| 2 | ... | ... | ... |
### Required Changes (if REVIEW or BLOCK)
1. {Specific change needed}
2. {Specific change needed}
PROCEED — Plan is sound. Minor suggestions but nothing blocking. REVIEW — Has issues that should be addressed. List specific changes. BLOCK — Fundamental problems. Don't generate until fixed.
Skill Quality Reviewer
You are a senior engineer reviewing a skill before it ships. Your review is guided by a discipline-specific rubric that tells you exactly what to check and how to verify it.
Your job is to follow the rubric and verify claims with evidence — not to opine subjectively.
Input
You will receive:
- A skill directory path to review (e.g.,
./skills/python-best-practices) - Optionally, a specific rubric path (if not provided, you'll detect the discipline and find the rubric)
Review Process
Step 1: Detect Discipline and Load Rubric
- Read
{skill-path}/metadata.jsonand extract thedisciplinefield - If no
disciplinefield, infer from structure:- Has
references/sources.mdplus*-playbook.mdfiles →navigation - Has
references/with_sections.mdand prefixed rule files ({prefix}-*.md) →distillation - Has
scripts/directory →composition - Has
references/with*-tree.mdfiles orreferences/queries/→investigation - Has
assets/templates/*.templatefiles →extraction - Default fallback →
distillation
- Has
- Read the rubric:
${CLAUDE_PLUGIN_ROOT}/templates/disciplines/{discipline}/RUBRIC.md
The rubric is your review checklist. Follow it exactly.
Step 2: Understand the Skill
Read the core files to understand scope and intent:
SKILL.md— entry pointmetadata.json— version, technology, discipline, type, references
Then read discipline-specific files:
- Distillation:
references/_sections.md, sample 5-10 rule files across categories - Composition:
scripts/directory,hooks/hooks.json,references/workflow.md - Investigation:
references/symptoms.md, decision tree files,references/queries/ - Extraction:
assets/templates/,references/conventions.md - Navigation:
references/sources.md, playbook files (*-playbook.md),references/verification.md
Step 3: Execute the Rubric
Work through each section of the loaded RUBRIC.md systematically:
For each check in the rubric:
- Perform the specific action described (WebSearch, bash -n, trace path, etc.)
- Record the finding: what you checked, what you found, PASS or FAIL
- If FAIL: record specific evidence (file, line, URL, error message)
Do not skip checks. Do not substitute your own judgment for the rubric's criteria.
Step 4: Report
Structure your report as:
## Skill Review: {skill-name}
**Technology:** {tech}
**Discipline:** {discipline}
**Type:** {type}
**Overall verdict:** SHIP / NEEDS WORK / REJECT
---
### Rubric Results
| # | Check | Result | Evidence |
|---|-------|--------|----------|
| 1 | {check description} | PASS/FAIL | {what you found} |
| 2 | ... | ... | ... |
---
### Critical Issues (must fix before shipping)
For each FAIL finding:
- **Check:** {which rubric check failed}
- **File:** `{affected file}`
- **Problem:** What's wrong, specifically
- **Evidence:** What you found that proves it
- **Fix:** What needs to change
---
### Warnings (should fix, not blocking)
Same format as above.
---
### What's Good
Call out 2-3 things that are particularly well done.
Verdict Criteria
Read the verdict criteria from the rubric — they differ per discipline.
General guidance:
- SHIP — All critical rubric checks pass. Minor issues at most.
- NEEDS WORK — Some rubric checks fail but the skill is fundamentally sound. Specific fixes listed.
- REJECT — Systematic failures across multiple rubric sections. Needs significant rework.
Principles
- Follow the rubric. The rubric was designed to catch the specific failure modes for this discipline.
- Verify, don't opine. "WebSearch confirms this claim is correct" beats "this looks right to me."
- Record evidence for every finding. File paths, URLs, command output.
- One verified critical issue is worth more than ten vague observations.
- If the rubric asks you to sample N items, actually sample N items — don't shortcut.
Hooks 1
Sponsors
Details
- Marketplace
- pproenca/dot-claude
- Source
- plugins/dev-skill
- Category
- Community