/skill-gen

description: Generate a complete Agent Skill from a documentation URL using Firecrawl
argument-hint: <documentation-url>

Generate Skill from Documentation

Create a complete, production-ready Agent Skill by scraping documentation with Firecrawl. The skill you build is for an AI agent to use — include information that is beneficial and non-obvious. Consider what procedural knowledge, domain-specific details, or reusable assets would help an agent execute tasks more effectively.

The user provided this documentation URL: **$ARGUMENTS**

Step 1: Scrape the documentation

Use the `firecrawl` skill to fetch the documentation at `$ARGUMENTS`:

1. **Map the site** to discover all relevant pages:

   firecrawl map $ARGUMENTS --search "<tool-name> API reference getting started"

2. **Scrape the key pages** (API reference, quickstart, core concepts, auth, examples):

   firecrawl scrape <page-url> --format markdown

3. For large doc sites, crawl with limits:

   firecrawl crawl $ARGUMENTS --maxDepth 2 --limit 15

Focus on API references, getting started guides, core concepts, authentication, and code examples. Skip changelogs, blog posts, and community pages.

Step 2: Clarify the skill scope

After scraping, ask the user 1-2 brief questions (skip if already clear):

• What should the skill be named? (suggest a kebab-case name based on the docs)
• What are the 2-3 primary use cases? (e.g., "What would a user say that should trigger this skill?")

Step 3: Plan the skill contents

Analyze each use case by considering how to execute it from scratch, then identify what reusable resources would help when doing it repeatedly.

Decision guide for resource types:

• **Scripts** (`scripts/`) — when the same code would be rewritten each time (e.g., a `pdf-editor` skill for "rotate this PDF" → `scripts/rotate_pdf.py`)
• **References** (`references/`) — when the agent needs to re-discover schemas, specs, or domain knowledge each time (e.g., a `big-query` skill → `references/schema.md` for table schemas)
• **Assets** (`assets/`) — when the same boilerplate is needed each time (e.g., a `webapp-builder` skill → `assets/hello-world/` template)

Step 4: Present the plan for approval

**MANDATORY — do NOT write any files before this step.**

Present the user with a complete overview of what will be created:

1. The proposed directory tree (all files and folders) 2. A brief summary of what each file will contain 3. The proposed SKILL.md frontmatter (`name` and `description`)

Wait for the user to approve the plan before proceeding. If the user requests changes, revise the plan and present it again.

Step 5: Ask where to place the skill

**MANDATORY — do NOT write any files before asking.**

Ask the user where the skill should be saved. Present these options:

1. **Project** — `.claude/skills/<skill-name>/` in the current working directory. The skill will only be available in this project. 2. **Global** — `~/.claude/skills/<skill-name>/` in the user's home directory. The skill will be available across all projects. 3. **Custom path** — let the user specify any directory.

Do NOT default to any location. Always ask and wait for the user's explicit choice before writing any files.

Step 6: Build the skill

Only after the user has approved the plan AND chosen a location, write all files following the skill format reference below.

If the skill includes scripts, test them by running them to verify they work before delivering. If there are many similar scripts, test a representative sample.

Step 7: Validate the skill

After writing all files, run these concrete checks and report results:

1. **Frontmatter check** — read SKILL.md and verify:

• Has `name` field (kebab-case, max 64 chars, no consecutive hyphens, doesn't start/end with hyphen)
• Has `description` field (non-empty, max 1024 chars)
• `name` matches the parent directory name exactly

2. **Line count check** — count lines in SKILL.md and confirm it is under 500 lines:

   wc -l <path-to-SKILL.md>

3. **No junk files check** — confirm the skill directory does NOT contain README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or any other auxiliary documentation 4. **References depth check** — confirm all reference files are one level deep from SKILL.md (no nested subdirectories inside references/)

Report each check as PASS or FAIL. If any check fails, fix the issue before delivering.

Step 8: Deliver

Present to the user:

• Summary of what was built
• Full directory tree with line counts
• Validation results (all checks should be PASS)
• The location where files were saved

---

Skill format reference

SKILL.md structure

<skill-name>/
├── SKILL.md          (required)
├── scripts/          (optional — executable code for deterministic tasks)
├── references/       (optional — docs loaded into context on-demand)
└── assets/           (optional — templates/files used in output, not loaded into context)

Frontmatter

---
name: <skill-name>
description: |
  What this skill does AND when to use it. Max 1024 chars.
  Include specific triggers and contexts. This is the primary activation mechanism.
  All "when to use" info goes HERE — not in the body (the body loads after triggering).
---

• `name`: kebab-case, max 64 chars, lowercase + numbers + hyphens, must match directory name
• `description`: the most important field — the agent uses this to decide when to activate the skill

Good description example:

description: |
  Comprehensive document creation, editing, and analysis with support for tracked
  changes, comments, formatting preservation, and text extraction. Use when working
  with professional documents (.docx files) for: (1) Creating new documents,
  (2) Modifying or editing content, (3) Working with tracked changes,
  (4) Adding comments, or any other document tasks.

Body

• Keep under 500 lines. Use imperative/infinitive form.