# Skill Forge

> Scaffolds, validates, and indexes a new skill in this repo's conventions using the existing root scripts, making the marketplace self-hosting. Use when creating a new skill for this repository, fixing a skill that fails validation, or refreshing the README index and marketplace manifest after adding one.

- Skill: `sujanbhuiyan/skill-forge` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add sujanbhuiyan/skill-forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sujanbhuiyan/skill-forge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: sujanbhuiyan (https://skillmd.com/u/sujanbhuiyan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sujanbhuiyan/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`](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`.