skill-forge

Skill Forge

What this does

Orchestrates this repo's own tooling to add a correct, well-formed skill: it scaffolds the folder, fills the frontmatter against the three-axis taxonomy, validates it, regenerates the README index, and registers it in the marketplace manifest. It is the meta skill that lets the marketplace extend itself.

When to use it

• Creating a brand-new skill in this repository.
• A skill fails validate_frontmatter.py and you need to bring it to spec.
• Refreshing the README index / marketplace manifest after adding a skill.

How to use it

Run all commands from the repo root. The heavy lifting lives in the repo's root scripts/ — this skill drives them; it does not reimplement them.

1. Scaffold the folder with the root script (it pre-fills + validates the name and taxonomy values you pass):

   python scripts/new_skill.py <name> \
     --category "Data & Analysis" --lifecycle Plan --domain Finance \
     --description "Does X. Use when Y."
   

   <name> must be kebab-case, equal the folder name, and not contain claude/anthropic.
2. Write the body of skills/<name>/SKILL.md following template/SKILL.md and the three-axis taxonomy in docs/taxonomy.md. Keep the body order: Title → What this does → When to use it → How to use it (numbered) → Inputs → Output → Notes & constraints. Keep it tight (< ~250 lines); push detail into references/, deterministic steps into scripts/, templates into assets/. See references/authoring-rules.md for the full self-check.
3. Add bundles as needed (references/, scripts/, assets/) and link them from the body with forward-slash relative paths. Scripts must run on stock Python 3 or guard optional imports with a clear pip install message; no destructive actions or hidden network calls.
4. Validate: python scripts/validate_frontmatter.py — confirm the new skill prints OK. Fix any reported errors and re-run.
5. Index: python scripts/gen_index.py — regenerates the three README tables and the skill count from frontmatter.
6. Register the skill in .claude-plugin/marketplace.json under the correct plugin's skill list so it ships in the marketplace.
7. Re-validate clean before opening a PR: run steps 4–5 once more and confirm validate_frontmatter.py exits 0 and gen_index.py --check is up to date.

Frontmatter rules (enforced by the validator)

• name equals the folder name, kebab-case, ≤ 64 chars, no claude/anthropic.
• description is one line, third person, ≤ 1024 chars, and must contain a "when to use" trigger (write Use when …).
• metadata.category / lifecycle / domain must each be an exact value from docs/taxonomy.md (and scripts/_skilllib.py TAXONOMY).
• metadata.version is semver (start at 1.0.0); license: MIT.

Progressive-disclosure best practices

Claude only reads the description to decide whether to load a skill, then the body, then bundles on demand. So: make the description specific with a real trigger; keep the body focused on how to drive the skill; and move reference material, runnable logic, and templates into bundles rather than inlining them.

Inputs

• The new skill's name and its three taxonomy values (category/lifecycle/domain).
• A one-line description with a "Use when" trigger.
• The intended body content and any bundle files.

Output

• A new skills/<name>/ with a spec-valid SKILL.md (+ optional bundles).
• An updated README index and an updated .claude-plugin/marketplace.json.
• A clean run of validate_frontmatter.py and gen_index.py.

Notes & constraints

• Run scripts from the repo root; they resolve paths relative to it.
• To add a new taxonomy value you must edit both docs/taxonomy.md and the TAXONOMY map in scripts/_skilllib.py, then open a PR — don't invent values.
• This skill orchestrates scripts/new_skill.py, validate_frontmatter.py, and gen_index.py; do not duplicate their logic inside a skill.
• Use forward-slash paths. Fully qualify any MCP tools as Server:tool.