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.

A common misconception is that skills are "just markdown files." That undersells them significantly. A skill is a folder, not a file. It can contain markdown instructions, scripts, reference code, data files, templates, configuration - anything an agent might need to do its job well. SKILL.md is the entry point that tells the agent what the skill does and when to use it. But the real power comes from the supporting files - reference docs give deeper context, scripts let it take action, templates give it a head start on output.

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 (use AskUserQuestion with multiple choice):

1. Default output directory - skills/ (registry PR) or custom path?
2. Skill type preference - code-heavy, knowledge-heavy, or balanced?
3. Installation target - where should the forged skill be installed?
   • Registry PR only - write to skills/<name>/ for contribution to AbsolutelySkilled (default)
   • Global (all projects) - install to ~/.agents/skills/<name>/ (canonical location, auto-symlinked to agent dirs)
   • Project-level - install to .agents/skills/<name>/ (this project only, cross-client)
   • Claude-only project - install to .claude/skills/<name>/ (this project, Claude Code only)

Store answers in ${CLAUDE_PLUGIN_DATA}/forge-config.json. Read this config at the start of every forge session.

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}

Read this log at the start of each session. It helps you:

• Avoid creating duplicate skills
• Reference patterns from previously forged skills
• Track which categories are over/under-represented

Step 0 - Detect input type

• URL input (starts with http, github.com, or looks like a domain) -> Phase 1A
• Domain topic (a word or phrase) -> Phase 1B
• Ambiguous -> ask the user

Step 0.5 - Skill or Agent?

Before proceeding, determine whether the user needs a skill or an agent definition. These are different artifacts:

• Skill = portable knowledge package (AgentSkills.io open standard). Works across Claude Code, Cursor, VS Code, Gemini CLI, and 40+ other tools. A folder with SKILL.md containing instructions and reference material.
• Agent definition = execution context (Claude Code specific). Creates an isolated subagent with its own tools, permissions, model, and system prompt. Not portable.

Decision tree:

• Primarily knowledge, best practices, or domain instructions? -> Skill
• Needs to be portable across multiple agent tools? -> Skill
• Needs isolated context, specific tool permissions, or its own model? -> Agent definition
• Needs permissionMode, maxTurns, or background execution? -> Agent definition

skill-forge creates skills, not agent definitions. If the user needs an agent, explain the distinction and point them to Claude Code's agent documentation. Load references/skills-vs-agents.md for the full breakdown.

Phase 1A - Research (URL-based)

The quality of the skill is entirely determined by the depth of research here. Do not write a single line of SKILL.md until research is complete.

Crawl order (priority high to low)

1. /llms.txt or /llms-full.txt   - AI-readable doc map (gold)
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, versioning

Stop fetching a category once you have good coverage - 5 pages that give the full picture beats 20 pages of marginal detail.

Discovery questions

While crawling, answer these six questions - they form your mental model:

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 - never skip a section:

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

Aim for < 5 flags. More than 5 means you haven't crawled enough.

Phase 1B - Brainstorm Discovery (domain-based)

For domain topics, run an interactive brainstorm with the user.

HARD GATE: Do NOT write any SKILL.md until the user approves the scope. "TypeScript" could mean best practices, migration guides, or project setup.

Ask these questions one at a time (use multiple choice when possible):

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?
6. Output format? (code, prose, templates, checklists, or mix)

Present a proposed outline. Wait for approval before proceeding.

Phase 2 - Write SKILL.md

Read references/frontmatter-schema.md for YAML fields and references/body-structure-template.md for the markdown scaffold.

The frontmatter schema distinguishes between portable fields (AgentSkills.io spec), AbsolutelySkilled registry fields, and Claude Code extensions. Default to portable fields only - add Claude-specific fields only when the skill genuinely needs hooks, context forking, or model overrides.

Key principles for writing

Focus on the delta - what the agent does NOT know. The agent already knows a lot about coding and common patterns. If a skill mostly restates common knowledge, it wastes context tokens. Focus on information that pushes the agent outside its defaults - non-obvious conventions, where the "standard" approach breaks down, domain quirks that trip up even experienced developers.

The description field is a trigger condition, not a summary. The agent scans every available skill's description at session start to decide which are relevant. Write it as a when-to-trigger condition with specific tool names, synonyms, action verbs, and common task types. A vague "Helps with deployment" will never fire. A specific "Use when deploying services to production, running canary releases, checking deploy status, or rolling back failed deploys" will.

Build the Gotchas section first. This is the highest-value content in any skill. Start with 3-5 known failure points from actual usage. Expect this section to grow over time as new edge cases appear. A mature skill's gotchas section is its most valuable asset. Put gotchas inline next to the relevant task, not in a separate section users might skip.

Use progressive disclosure. Don't dump everything into one massive SKILL.md. Tell the agent what files are available and let it read them when needed. This keeps initial context small (cheaper, faster) while making deep knowledge available on demand. The agent is good at deciding when it needs more context.

Give flexibility, not rails. Because skills are reusable across many situations, being too prescriptive backfires. Give the agent the information it needs, but let it decide how to apply it. "Tests should cover unit, integration, and e2e scenarios as appropriate" beats "Always create exactly 3 test files with at least 5 functions each."

Include scripts and composable code. One of