# Skill Forge

> Creates, validates, and packages Agent Skills in the SKILL.md open format used by Claude Code, Claude apps, Codex, and other compatible agents. Use when the user wants to build a new skill, scaffold a skill directory, write or fix SKILL.md frontmatter and descriptions, review an existing skill against the specification, or bundle a skill into a distributable archive.

- Skill: `aungminthu1722/skill-forge` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add aungminthu1722/skill-forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aungminthu1722/skill-forge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: AungMinThu1722 (https://skillmd.com/u/aungminthu1722)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/aungminthu1722/skill-forge

---


# Skill Forge

Produce Agent Skills that load correctly and trigger reliably. A skill is a folder whose
`SKILL.md` holds YAML frontmatter (`name`, `description`) plus a Markdown body of
instructions, optionally supported by `scripts/`, `references/`, and `assets/`.

## What good output looks like

- `name` matches the folder name exactly, kebab-case, ≤64 characters.
- `description` states **what** the skill does and **when** to use it, in third person, ≤1024 characters.
- Body stays under 500 lines; depth lives in `references/` and is loaded only when needed.
- Any script the body tells the agent to run actually exists and runs from the skill root.
- The folder passes `scripts/validate_skill.py` with zero errors before it is delivered.

## Intake: resolve these before scaffolding

Ask the user only for what is missing, then proceed. Do not scaffold a skill around a guess.

1. **Job to be done** — the one task this skill owns, in a single sentence.
2. **Triggers** — the words a user would actually type ("review this PR", "make a quote").
3. **Inputs and outputs** — file types, formats, or tools involved.
4. **Determinism** — must any step be executed by code rather than by the model
   (parsing, math, file conversion)? If yes, that step becomes a script.
5. **Deliverable form** — folder only, or a packaged `.skill` archive.

If the user has no strong opinion, choose sensible defaults, say so in one line, and build.

## Workflow

### 1. Scaffold

```bash
python3 scripts/init_skill.py <skill-name> --path <parent-dir> \
  --description "What it does. Use when ..." \
  --with-scripts --with-references --with-assets
```

Creates `<parent-dir>/<skill-name>/` with a `SKILL.md` stub and only the subfolders requested.
Add `--force` to overwrite an existing skill directory.

### 2. Write the description first

The description is the routing signal — it is the only part loaded at startup, so a weak
description means the skill never activates. Formula:

**`<What it does, third person>` + `Use when <triggers, symptoms, user phrasings>`**

| | Example |
| --- | --- |
| Weak | `description: Helps with documents.` |
| Strong | `description: Extracts line items from invoices (PDF, DOCX, scans) into a validated CSV. Use when the user uploads an invoice, asks to pull out totals or vendor details, or wants invoice data turned into a spreadsheet.` |

Rules: third person, no "I"/"You can"; include the literal words users say; no XML tags.

### 3. Write the body

Order that works: short overview → when to use / when not to use → numbered workflow →
concrete examples → error handling and safety boundaries. Write instructions as imperatives
addressed to the agent ("Read the file, then…"), not as prose about the skill.

Keep it lean:
- Body under 500 lines. Exceeding that is a signal to move detail into `references/`.
- One level of file references (`references/tables.md`), never nested chains.
- Reference filenames describe content: `form_validation_rules.md`, not `doc2.md`.
- State what to do when a step fails; silence forces the agent to improvise.

### 4. Move deterministic work into scripts

Anything with exact answers — parsing, arithmetic, format conversion, API calls — belongs in
`scripts/` and gets run, not recalled. Scripts must:
- accept paths as arguments and run from the skill root,
- print machine-readable output (JSON or CSV) to stdout, diagnostics to stderr,
- exit non-zero on failure, and never require network access unless stated in `compatibility`.

### 5. Validate, then package

```bash
python3 scripts/validate_skill.py <skill-dir> --strict
python3 scripts/package_skill.py <skill-dir> --out <dist-dir>
```

Never ship a skill with validation errors. Warnings should be fixed or consciously accepted.

## Frontmatter reference

| Field | Required | Rules |
| --- | --- | --- |
| `name` | yes | lowercase letters, digits, hyphens; ≤64 chars; no leading/trailing/consecutive hyphens; must equal the folder name; not `anthropic` or `claude` |
| `description` | yes | non-empty; ≤1024 chars; no XML tags; what + when; third person |
| `license` | no | SPDX identifier, e.g. `MIT`, `Apache-2.0` |
| `compatibility` | no | product, package, or network requirements |
| `metadata` | no | free-form map, e.g. `version`, `author` |
| `allowed-tools` | no | space-delimited pre-approved tools; support varies by host |

## Directory layout

```
<skill-name>/
├── SKILL.md          # required
├── scripts/          # executable helpers the model runs
├── references/       # depth loaded on demand (specs, tables, long procedures)
├── assets/           # templates and files copied into output
└── tests/            # checks for the skill's own scripts (optional)
```

## Quality gate

Before reporting a skill as done, confirm all of these:

- [ ] Folder name, `name`, and description all agree; description contains real trigger phrases.
- [ ] Every scaffold placeholder is replaced with real content (the validator flags leftover ones).
- [ ] Every path mentioned in the body exists in the bundle.
- [ ] Each script was executed once on real or sample input and its output inspected.
- [ ] `validate_skill.py --strict` passes.
- [ ] If packaged: archive extracts to a folder whose name matches `name`.

## Cost of a bad skill

- A vague description means the skill never fires; a greedy one hijacks unrelated tasks.
- A 900-line body burns context on every activation and buries the operative instruction.
- A script the model cannot run (missing dependency, wrong relative path) turns the skill into
  guesswork, which is worse than no skill.

## Bundled resources

- `scripts/init_skill.py` — scaffold a new skill directory.
- `scripts/validate_skill.py` — check spec compliance; `--strict` promotes warnings to errors, `--json` for machine output.
- `scripts/package_skill.py` — validate and zip into a distributable archive.
- `references/specification.md` — the full SKILL.md spec, field rules, validation semantics.
- `references/authoring-guide.md` — description craft, body patterns, anti-patterns, testing method.
- `assets/SKILL.template.md`, `assets/script.template.py`, `assets/reference.template.md` — starting points.
- `tests/run_tests.sh` — smoke tests for the three scripts.

## Example: end-to-end

User: "Make a skill that turns messy meeting notes into a structured action list."

1. Intake — job: notes → action items; triggers: "turn these notes into actions",
   "extract action items"; output: Markdown table; deterministic step: none required.
2. `python3 scripts/init_skill.py meeting-actions --path ~/.claude/skills --description "Converts raw meeting notes into a structured action list with owners and due dates. Use when the user pastes meeting notes or transcripts and asks for action items, owners, or follow-ups." --with-references`
3. Body: workflow steps + a worked example; output table format in `references/output-format.md`.
4. `python3 scripts/validate_skill.py ~/.claude/skills/meeting-actions --strict`
5. Package if the user wants a shareable file.