When this skill is activated, always start your first response with the 🔨 emoji.

skill-forge

Generate production-ready AbsolutelySkilled skills from any source - GitHub repos, documentation URLs, or pure domain knowledge. This is the bootstrapping tool for the registry.

Slash command

/skill-forge <url-or-topic>

Setup

On first run, check for ${CLAUDE_PLUGIN_DATA}/forge-config.json. If it doesn't exist, ask the user these questions:

1. Default output directory - skills/ (registry PR) or custom path?
2. Auto-propagate recommendations? - yes/no
3. Skill type preference - code-heavy, knowledge-heavy, or balanced?

Forge history

After every successful forge, append an entry to ${CLAUDE_PLUGIN_DATA}/forge-log.jsonl:

{"skill": "api-design", "type": "domain", "date": "2025-01-15", "lines": 245, "refs": 3, "evals": 12}

Step 0 - Detect input type

• URL input -> Phase 1A
• Domain topic -> Phase 1B
• Ambiguous -> ask the user

Phase 1A - Research (URL-based)

Crawl order

1. /llms.txt or /llms-full.txt   - AI-readable doc map
2. README.md                      - overview, install, quickstart
3. /docs/                         - main documentation index
4. API reference                  - endpoints, params, errors
5. Guides / tutorials             - real-world usage patterns
6. Changelog                      - breaking changes

Discovery questions

1. What does this tool do? (1 sentence)
2. Who uses it?
3. What are the 5-10 most common agent tasks?
4. What are the gotchas? (auth, rate limits, pagination, SDK quirks)
5. What's the install/auth story?
6. Are there sub-domains needing separate references/ files?

Uncertainty handling

Flag ambiguous or missing detail inline:

<!-- VERIFY: Could not confirm from official docs. Source: https://... -->

Phase 1B - Brainstorm Discovery (domain-based)

HARD GATE: Do NOT write any SKILL.md until the user approves the scope.

Ask questions one at a time:

1. Target audience?
2. Scope? (offer 2-3 options with your recommendation)
3. Top 5-8 things an agent should know?
4. Common mistakes to prevent?
5. Sub-domains needing their own references/ files?

Present a proposed outline. Wait for approval before proceeding.

Phase 2 - Write SKILL.md

Key principles

Focus on what pushes Claude out of its defaults. Claude already knows how to write markdown and structure content. Your skill should teach it things it would get wrong without the skill - the gotchas, the non-obvious patterns, the domain quirks that trip up even experienced developers.

Build the Gotchas section first. This is the highest-signal content in any skill. Start with 3-5 known failure points and expect the section to grow.

Use progressive disclosure. SKILL.md should be the entry point, not the encyclopedia. Point to references/ files for deep detail.

Phase 3 - Write references/

Create a references/ file when a topic has more than ~10 API endpoints or needs its own mental model.

Every references file must start with:

<!-- Part of the <ToolName> AbsolutelySkilled skill. Load this file when
     working with <topic>. -->

Phase 4 - Write evals.json

Write 10-15 evals covering: trigger tests (2-3), core tasks (4-5), gotcha/edge cases (2-3), anti-hallucination (1-2), references load (1).

Phase 5 - Write sources.yaml

Only for URL-based skills. Domain skills can omit this.

Phase 6 - Output

Write to skills/<skill-name>/:

skills/<skill-name>/
  SKILL.md
  sources.yaml       (optional for domain skills)
  evals.json
  references/        (if needed)

Gotchas

1. Description too vague - Include tool name, 3-5 task types, and common synonyms.
2. Stuffing everything into SKILL.md - If you're past 300 lines, move detail to references/.
3. Stating what Claude already knows - Focus on non-obvious: auth quirks, deprecated methods.
4. No gotchas - Every skill should have inline gotchas next to relevant tasks.
5. Railroading - Give guidelines, not rigid procedures.
6. Forgetting the folder is the skill - Scripts, templates, data files make skills useful.
7. Not checking for duplicates - Always check the registry before forging.

Quality checklist

• Description is a trigger condition
• Gotchas are present and inline
• SKILL.md under 300 lines
• Progressive disclosure: references/ files listed with when-to-read guidance
• Evals cover all 5 categories
• Forge history log updated

References

• references/frontmatter-schema.md - YAML template (Phase 2)
• references/body-structure-template.md - Markdown scaffold (Phase 2)
• references/evals-schema.md - JSON schema (Phase 4)
• references/sources-schema.md - YAML schema (Phase 5)