/new-skill

New Skill Builder

Build a new ClawBio skill from the official template with full conformance enforcement.

Input: $ARGUMENTS (skill name in lowercase-with-hyphens, e.g. "pathway-enrichment")

Step 1: Validate the Name

Parse `$ARGUMENTS` to get the skill name. If empty, ask the user what the skill should do and derive a name.

Rules:

• Lowercase with hyphens only (e.g. `pathway-enrichment`, not `PathwayEnrichment`)
• Must not already exist in `skills/`
• Should be 2-4 words maximum

Store as `SKILL_NAME`. Also derive `SKILL_NAME_UNDERSCORE` by replacing hyphens with underscores (e.g. `pathway-enrichment` becomes `pathway_enrichment`). Use this for Python filenames and test files.

Step 2: Interview the User

Before writing any code, ask these questions one at a time. Wait for each answer.

1. **What does this skill do?** (one sentence, this becomes the `description` in YAML) 2. **What input does it take?** (file format: VCF, CSV, TSV, TXT, JSON, h5ad, or free text query) 3. **What output does it produce?** (report, table, plot, JSON, or combination) 4. **What domain databases or algorithms does it use?** (e.g. ClinVar, gnomAD, PGS Catalog, custom logic) 5. **What should the agent NEVER do with this skill?** (this seeds the Gotchas and Agent Boundary)

Step 3: Create the Skill Directory

mkdir -p skills/$SKILL_NAME/tests
mkdir -p skills/$SKILL_NAME/examples

Step 4: Generate SKILL.md from Template

Read the template at `templates/SKILL-TEMPLATE.md`.

Fill in every section using the interview answers. Be specific and concrete:

Trigger Section (MOST IMPORTANT)

• Write at least 5 "fire when" phrases covering synonyms, abbreviations, and natural language variations
• Write at least 2 "do NOT fire when" entries pointing to similar skills that handle adjacent queries
• Copy the trigger phrases into `trigger_keywords` in the YAML metadata

Scope Section

• One sentence: "This skill does X and nothing else."
• If the user's description implies two tasks, flag it and recommend splitting

Workflow Section

• Numbered steps only, no prose
• Mark each step as prescriptive (exact) or flexible (room for reasoning)
• Include validation as step 1

Example Output Section

• Write an actual rendered sample based on the output format
• Use realistic-looking synthetic values, not placeholder text

Gotchas Section

• Seed with at least 3 gotchas from the user's "never do" answer
• Add 1-2 common model failure patterns for this domain (e.g. hallucinating gene associations, inventing p-values, assuming ancestry)

Maintenance Section

• Identify what upstream sources could make this skill stale
• Set review cadence (default: monthly)

Write the completed SKILL.md to `skills/$SKILL_NAME/SKILL.md`.

Step 5: Generate Demo Data

Create a synthetic demo file that exercises the skill's logic. Rules:

• Never use real patient data
• Include at least 3-5 rows/entries to exercise basic logic
• Add a comment header: `# Synthetic demo data for $SKILL_NAME. This is NOT real patient data.`

Write to `skills/$SKILL_NAME/demo_<format>.<ext>`.

Step 6: Write Tests First (Red Phase)

Create `skills/$SKILL_NAME/tests/test_$SKILL_NAME_UNDERSCORE.py` with:

1. `test_demo_runs_without_error` - the `--demo` flag produces output without crashing 2. `test_output_structure` - output directory contains expected files (report.md, result.json, etc.) 3. `test_report_contains_disclaimer` - every report includes the ClawBio medical disclaimer 4. `test_rejects_malformed_input` - bad input raises a clean error, not a traceback 5. `test_empty_input_handled` - empty file produces a meaningful error message

Run the tests and confirm they fail (red):

python -m pytest skills/$SKILL_NAME/tests/ -v

Show the user the red output.

Step 7: Write the Python Implementation (Green Phase)

Create `skills/$SKILL_NAME/$SKILL_NAME_UNDERSCORE.py` with:

• `argparse` CLI with `--input`, `--output`, and `--demo` flags
• `run()` function that does the core work
• Pathlib for all paths, no hardcoded paths
• Output: `report.md` + `summary.json` minimum
• ClawBio disclaimer in every report
• Graceful error handling for bad input

Run the tests and confirm they pass (green):

python -m pytest skills/$SKILL_NAME/tests/ -v

Show the user the green output.

Step 8: Run the Demo

python skills/$SKILL_NAME/$SKILL_NAME_UNDERSCORE.py --demo --output /tmp/$SKILL_NAME_demo

Read and display the generated report to the user.

Step 9: Self-Audit (Conformance Check)

Run the 17-point SKILL.md conformance checklist against the new skill. Check each item:

| Check | Requirement | |-------|------------| | YAML: `name` | Present, matches folder name | | YAML: `version` | Semver format | | YAML: `author` | Present | | YAML: `description` | One line, specific | | YAML: `inputs` | Present with format and required flag | | YAML: `outputs` | Present with format | | YAML: `trigger_keywords` | At least 3 keywords | | Section: `## Trigger` | Fire/do-not-fire lists present | | Section: `## Scope` | One-skill-one-task confirmed | | Section: `## Workflow` | Numbered steps, not prose | | Section: `## Example Output` | Rendered sample present | | Section: `## Gotchas` | At least 3 entries | | Section: `## Safety` | Disclaimer referenced | | Section: `## Agent Boundary` | Present | | File: demo data | At least one demo file | | File: tests/ | Directory with at least one test | | Line count | SKILL.md under 500 lines |

Report PASS/FAIL for each. Fix any failures before proceeding.

Step 10: Update Routing Table

Add the new skill to the ClawBio CLAUDE.md routing table:

• Add a row to the `## Skill Routing Table` with user intent phrases, skill path, and action
• Add CLI reference to the `## CLI Reference` section
• Add demo data to the `## Demo Data` table
• Add demo command to the `## Demo Commands` section

Step 11: Summary

Show the user: 1. Files created (list all with paths) 2. Conformance