skill-forge

Generate production-ready AbsolutelySkilled skills from any source - GitHub repos, documentation URLs, or pure domain knowledge (marketing, sales, TypeScript, design patterns, etc.). This is the bootstrapping tool for the registry.

Slash command

Register as a slash command:

/skill-forge <url-or-topic>

Where <url-or-topic> is a GitHub repo URL, docs site URL, or a domain topic (e.g. "marketing", "typescript", "sales", "design-patterns").

Step 0 - Detect input type

Classify the input to determine which Phase 1 path to follow:

• URL input (starts with http , github.com , or looks like a domain) -> Phase 1A (doc crawl)

• Domain topic (a word or phrase like "marketing", "sales strategy", "typescript best practices") -> Phase 1B (brainstorm discovery)

If ambiguous, ask the user: "Is this a URL I should crawl, or a domain topic I should brainstorm with you about?"

Phase 1A - Research (URL-based)

Before writing a single line of SKILL.md, do a thorough crawl. The quality of the skill is entirely determined by the depth of research here.

1A.1 Crawl order (priority high to low)

For every URL provided, attempt to fetch these in order. Stop fetching a category once you have good coverage - don't fetch 20 pages if 5 give you the full picture.

1. /llms.txt - curated AI-readable doc map (gold if it exists)
2. /llms-full.txt - extended version with full content
3. README.md - top-level overview, install, quickstart
4. /docs or /docs/ - main documentation index
5. API reference - endpoints, parameters, error codes
6. Guides / tutorials - real-world usage patterns
7. Changelog - recent breaking changes, versioning info
8. GitHub repo - if given a docs URL, find the repo too

1A.2 For GitHub repos specifically

github.com/org/repo -> fetch in this order: /README.md /docs/ (index any .md files found) /CHANGELOG.md or /CHANGELOG Any file named llms.txt, llms-full.txt, or ai-docs.md at root Look for /docs/api/ or similar for API reference

1A.3 Discovery heuristics

While crawling, build a mental model by answering these six questions:

• What does this tool do? (1 sentence)

• Who uses it? (developers, data scientists, devops, etc.)

• What are the 5-10 most common tasks someone would use an agent to do with this tool?

• What are the gotchas? (auth patterns, rate limits, pagination, SDK quirks, version differences)

• What's the install/auth story? (env vars, API keys, SDK vs REST)

• Are there multiple sub-domains? (e.g. Stripe has Payments, Billing, Connect, Radar - each might need a separate references/ file)

1A.4 Uncertainty handling

When the docs are ambiguous or missing detail, make a best guess and flag it with an inline comment. Never leave a section blank or skip it.

Use this comment syntax inside SKILL.md:

<!-- VERIFY: Could not confirm from official docs - best guess based on common SDK patterns. Source: https://... -->

Aim for < 5 flagged items per skill. If you're flagging more than 5, you haven't crawled enough - go back and fetch more pages.

Phase 1B - Brainstorm Discovery (domain-based)

For domain topics without a single canonical URL, run an interactive brainstorm session with the user. Use the brainstorming skill's approach: ask questions one at a time, explore scope, then synthesize.

1B.1 Scope the domain

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

• What's the target audience? Who will use this skill - beginners, senior engineers, marketers, sales reps, designers?

• What's the scope? Is this broad (all of marketing) or narrow (email marketing campaigns)? Offer 2-3 scope options with your recommendation.

• What are the 5-8 most important things an agent should know to be genuinely useful in this domain? Ask the user to list or confirm your proposal.

• What are the common mistakes people make in this domain that the skill should prevent?

• Are there sub-domains that deserve their own references/ files? E.g. "marketing" might split into content-marketing, paid-ads, analytics.

• What's the output format? Will the agent produce code, prose, templates, checklists, strategies, or a mix?

1B.2 Propose skill structure

After gathering answers, present a proposed skill outline to the user:

Proposed skill: <name> Target audience: <who> Scope: <what's in, what's out>

SKILL.md sections:

1. Overview
2. When to use
3. Key principles (replaces "Setup & auth" for non-code skills)
4. Core concepts / mental model
5. Common tasks (5-8)
6. Anti-patterns / common mistakes
7. References

references/ files:

• <topic-1>.md
• <topic-2>.md

Wait for the user to approve or revise before proceeding.

1B.3 Gather domain knowledge

Once scope is approved, build the skill content from:

• Your training knowledge - leverage what you know about the domain

• Web research (optional) - if the user points to specific articles, frameworks, or methodologies, fetch those URLs

• User expertise - ask follow-up questions on specifics where your knowledge might be generic or outdated

1B.4 Uncertainty handling

Same as 1A.4 - use <!-- VERIFY --> comments for uncertain claims. For domain skills, flag things like:

<!-- VERIFY: This conversion rate benchmark (2-5% for email) is based on general industry data. May vary significantly by vertical. -->

Phase 2 - Write SKILL.md

Write the canonical SKILL.md using the required schema and structure. Every section is required unless marked optional.

Frontmatter

See references/frontmatter-schema.md for the full YAML template, description writing guidelines, and category taxonomy.

Key rules:

• name : kebab-case tool name

• version : start at 0.1.0

• description : one tight paragraph answering what triggers this skill, what the tool does, and the 3-5 most common agent tasks. This is the PRIMARY triggering mechanism - be specific. Include tool name, common synonyms, and key verbs.

• All other fields: see the reference file for the complete list

Recommended skills

After writing the core frontmatter, add companion skill recommendations:

• Read references/skill-registry.md to find skills in the same or adjacent categories

• Pick 2-5 skills that a user of this skill would logically also benefit from

• Add the field after tags : recommended_skills: [skill-1, skill-2, ...]

• Only recommend skills that exist in the registry - never invent skill names

• Prefer skills that are complementary (not duplicative) - e.g. code-review pairs with clean-code, not with another review skill

Body structure

See references/body-structure-template.md for the full markdown scaffold with target lengths per section.

Required sections in order (adapt based on skill type):

For URL-based / code skills:

• Title + overview paragraph (3-5 sentences, distinct from frontmatter description)

• When to use this skill (5-8 trigger bullets + 2 anti-triggers)

• Setup and authentication (env vars, install, basic init)

• Core concepts (2-5 paragraphs on the domain model)

• Common tasks (5-8 subsections with working code examples)

• Error handling (3-5 most common errors in a table)

• References (pointer to references/ folder with when-to-read guidance)

For domain-based / knowledge skills:

• Title + overview paragraph (3-5 sentences)

• When to use this skill (5-8 trigger bullets + 2 anti-triggers)

• Key principles (replaces "Setup & auth" - 3-5 foundational rules of the domain)

• Core concepts / mental model (the domain's key entities and how they relate)

• Common tasks (5-8 subsections - may use prose, templates, checklists, or frameworks instead of code examples)

• Anti-patterns / common mistakes (replaces "Error handling" - what to avoid)

• References (pointer to references/ folder with when-to-read guidance)

Principles:

• For code skills: all code examples must be syntactically valid

• For domain skills: all advice must be actionable, not generic platitudes

• Use imperative/infinitive form throughout

• Keep SKILL.md under 300 lines when possible (hard limit 500)

• If approaching 300 lines, move detail to references/ files

• Always append the shared footer from references/skill-footer.md as the very last section of SKILL.md. Copy the footer block verbatim - do not modify it.

Phase 3 - Write references/

For any sub-domain too detailed for the main SKILL.md body, create a focused file in references/ . Each file should be:

• Under 400 lines

• Focused on one topic (auth, webhooks, a specific API sub-section, etc.)

• Fetched only when relevant (agent loads it on demand)

When to create a references/ file:

• The topic has more than ~10 API endpoints

• The topic requires its own mental model (e.g. Stripe Connect vs Stripe Payments)

• It would bloat SKILL.md past 300 lines if included inline

Naming:

references/ api.md - core REST/GraphQL API reference webhooks.md - event payloads and verification auth.md - detailed auth flows (if complex) <feature>.md - any major sub-feature

Header comment - 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 a test suite that validates the skill works correctly. Each eval tests whether an agent using this skill can answer a real question correctly.

See references/evals-schema.md for the full JSON schema, assertion types, and a worked example eval entry.

Coverage targets - write 10-15 evals covering:

Type Count What to test

Trigger test 2-3 Does the skill activate for on-topic prompts?

Core task 4-5 Can it produce correct code for the main tasks?

Gotcha / edge case 2-3 Does it handle auth errors, pagination, rate limits?

Anti-hallucination 1-2 Does it avoid inventing API methods that don't exist?

References load 1 Does it correctly reference a references/ file?

Phase 5 - Write sources.yaml

Track crawl provenance so humans can verify and update the skill later.

See references/sources-schema.md for the full YAML schema. Key rules:

• All URLs must be from official documentation only

• No Stack Overflow, blog posts, or community wikis

• One entry per source crawled with type , description , and accessed date

For domain-based skills: sources.yaml is optional. If you fetched specific URLs during Phase 1B.3, include them. If the skill is purely from training knowledge and user input, omit sources.yaml entirely.

Phase 6 - Output structure

Always write output to skills/<skill-name>/ in the project root. This is the canonical location for all skills - never use a temporary output directory.

skills/<skill-name>/ SKILL.md <- canonical skill (Phase 2) sources.yaml <- crawl provenance (Phase 5, optional for domain skills) evals.json <- test suite (Phase 4) references/ <- deep reference files (Phase 3, if needed) <topic>.md

Print a summary when done:

Skill generated: <tool-name>/

SKILL.md <N> lines sources.yaml <N> sources crawled evals.json <N> evals written references/ <N> files

Flagged items requiring human review:

1. SKILL.md:47 - webhook signature verification method unconfirmed
2. evals.json:23 - rate limit value (100 req/min) is a best guess

Recommendation graph updated:

• api-design: added <tool-name>
• microservices: added <tool-name> (replaced <old-skill>)
• backend-engineering: skipped (already at 5 recommendations)

Next steps:

1. Review flagged items above
2. Run: npx @askilled/cli validate ./<tool-name>/
3. Open a PR to github.com/AbsolutelySkilled/skills

Phase 7 - Propagate recommended_skills

After creating or heavily modifying a skill, update the recommendation graph so existing skills can also recommend the new/modified one.

When to run

• New skill created: always run this phase

• Major skill modification (renamed, merged, or scope changed significantly): run this phase to update any stale references

Steps

• Read the new skill's recommended_skills field to identify its companions

• For each companion skill listed, read that companion's SKILL.md

• If the companion's recommended_skills does not already include the new skill, and the companion has fewer than 5 recommendations, add the new skill name

• If the companion already has 5 recommendations, evaluate whether the new skill is a better fit than an existing entry - if so, swap it in; if not, skip

• Only add reciprocal links where the relationship is genuinely complementary - do not force bidirectional links for every recommendation

Example

If you create api-gateway with recommended_skills: [api-design, microservices] :

• Read skills/api-design/SKILL.md

• if it doesn't list api-gateway and has room, add it

• Read skills/microservices/SKILL.md

• same check

Rules

• Never remove existing recommendations without a clear reason

• Never exceed 5 recommendations per skill

• Only add the new skill if it's genuinely complementary to the companion

• Print which skills were updated in the output summary

Quality checklist

Before outputting, verify all of these:

• Every frontmatter field is populated (no empty strings)

• Description is specific - includes skill name + 3 key task types

• For URL skills: all sources in sources.yaml are from official docs only

• For domain skills: user approved the scope before writing began

• Code examples (if any) are syntactically valid; domain advice is actionable

• Evals cover all 5 type categories (trigger, task, gotcha, anti-hallucination, reference)

• Flagged items use the <!-- VERIFY: --> comment format

• references/ files each have the header comment

• Output summary is printed

• Recommended skills propagated to companion skills (Phase 7)

References

Consult these files for detailed schemas and examples. Only load a file when you need it for the current phase.

• references/frontmatter-schema.md

• Full YAML template and category taxonomy (read during Phase 2)

• references/body-structure-template.md

• Complete markdown body scaffold (read during Phase 2)

• references/evals-schema.md

• JSON schema, assertion types, worked example (read during Phase 4)

• references/sources-schema.md

• YAML schema for sources.yaml (read during Phase 5)

• references/worked-example.md

• Resend end-to-end worked example (read for first-time orientation)

• references/skill-registry.md

• Full catalog of existing and planned skills by category (read when choosing what to build next or checking for duplicates)