docs-map-skill-creator

name	docs-map-skill-creator
description	Use to turn an official docs URL/site into a reusable `<technology>-docs-map` skill. Also match “api-docs-map skill” or “make a skill for this docs site” requests.
allowed-tools	["WebFetch","WebSearch","Read","Write","Edit","Glob","Grep","Bash","AskUserQuestion"]

Docs Map Skill Creator

Goal

Turn an official technology documentation URL into a new <technology>-docs-map skill, rather than just writing a one-off docs map.

The result should include at least:

• a new skill directory
• the target skill's SKILL.md
• the target skill's references/docs-map.md
• the target skill's evals/evals.json
• if the environment allows it, a distributable .zip package as well

The job of this skill is not to “answer questions about the docs themselves,” but to “package a technology's official documentation site into a reusable docs-map skill that can be triggered again later.”

When to use

Use this skill when the user expresses intents like:

• “Make a skill from this official docs URL”
• “I want to turn this documentation site into a reusable skill”
• “Help me generate a <technology>-docs-map”
• “Don't just analyze the docs once — turn it into a skill”
• “Based on this framework / SDK / CLI / product documentation, create a documentation-routing skill that can be installed and reused later”

If the user only wants you to answer a technical documentation question directly, rather than create a skill, this skill should not take over; in that case it is better to use an existing docs-map skill or a normal retrieval flow.

Naming conventions

• Suggested generator skill name: docs-map-skill-creator
• Default target skill name: <product>-docs-map
• If the user says “api-docs-map skill,” interpret that as “docs-map skill”; unless the user explicitly asks for it, do not generate <product>-api-docs-map

Expected inputs

Prioritize extracting these pieces of information from the user input:

1. Official documentation URL (required, unless the user explicitly asks you to find it first)
2. Desired skill name (optional)
3. Output location (optional, default: ~/.claude/skills/)
4. Whether a .zip package is needed (default: yes)
5. Whether overwriting an existing skill is allowed (if the user explicitly allows it, default to overwriting)

If the user only gives a URL and not a skill name:

• Infer the product name from the site title, brand name, domain, or main path.
• Default to a kebab-case name, and prefer <product>-docs-map.
• If the inference is unstable, ask the user to confirm.

If the user does not provide an official docs URL and instead asks you to find it first:

• You may use WebSearch to find the official documentation entry point.
• Once the official entry point is confirmed, return to the same-origin indexing flow instead of continuing broad cross-domain crawling.

If the target skill already exists, and the user has clearly said “you can overwrite it” or anything equivalent:

• Treat that as “overwriting is allowed,” not “you must overwrite it.”
• Do not invent -v2, -new, -copy, or similar names just to avoid overwriting.

If the target skill already exists, and you have just verified that it already matches the current generator rules:

• Prefer reusing the existing skill, treat it as the result for this run, and move directly into post-generation self-test and follow-up optimization.
• Still check whether the corresponding .zip package exists; if it is missing, corrupted, or clearly older than the current skill directory contents, repackage it.

Only perform a real overwrite when the template, naming, semantics, docs-map structure, or packaging artifacts do not match the current rules.

Overall flow

Step 1: Make it explicit that this task is “generating a skill”

First confirm that what you are producing is a skill file structure, not a temporary docs answer.

The final deliverable must include at least:

<skill-name>/
├── SKILL.md
├── references/
│   └── docs-map.md
└── evals/
    └── evals.json

If you end with only a docs map text file and no new skill directory, the task is not complete.

Step 2: Locate the documentation index entry point

Around the official docs URL provided by the user, prioritize finding machine-readable indexes:

1. A user-provided llms.txt or sitemap.xml
2. Same-origin llms.txt
3. Same-origin sitemap.xml
4. The docs home page navigation, table of contents page, or overview page

Follow these rules:

• Prefer same-origin discovery; do not wander across domains.
• Preserve language, version, and product subpath context.
• Prioritize discovering the overall structure of the documentation before reading a lot of topic pages.
• Keep the number of index candidate URLs to about 6 or fewer.

Step 3: Generate references/docs-map.md

This is the core resource file of the generated target skill.

You need to turn the discovered documentation structure into a docs map that is suitable for agent use, and it should contain at least:

1. A Documentation Index section
2. Root documentation information
3. Page mappings grouped by topic
4. A heading summary for each page (if headings can be extracted from the index or pages)
5. Progressive loading guidance (which URLs to read first for which class of question)

This file should serve the long-term reusability of the generated skill, so it should:

• behave more like a navigation map and include less raw source text
• clearly state the index source
• label the scope (language / version / product range)
• make it obvious to a future agent which pages should be read first

Step 4: Generate the target skill's SKILL.md

The generated target skill must be a real, triggerable skill, not just an explanatory note.

When writing this file:

• Use references/docs-map.md as the primary index resource.
• Make the skill use the mapping rules already defined in the docs map before deciding which real pages to load.
• Clearly distinguish between “pages listed in the map” and “pages actually loaded in this run.”
• Require progressive loading rather than full-site crawling.
• By default, use description semantics like: When dealing with questions about using <technology>, prioritize the docs map routing rules built into this skill to locate and load the most relevant official documentation pages.
• Do not write the target skill as a tool that rebuilds the docs map at runtime; the target skill's responsibility is to use the map rules that are already built in.

Read references/generated-skill-template.md first, and generate the target skill's SKILL.md following that structure.

Step 5: Generate evals/evals.json

Provide 2–3 realistic test prompts for the generated target skill. The test prompts should:

• be based on the current documentation site
• reflect the behavior of routing through the docs map first, then loading specific pages
• do more than ask a vague “what is this?” question
• cover at least two different topic clusters

Step 6: Optionally package it as a .zip

If the environment allows it, output a .zip package to a common distribution directory, for example:

• ~/.claude/skills/dist/<skill-name>.zip

Prefer a simple zip-based package of the skill directory, provided that:

• __pycache__, .DS_Store, and node_modules are excluded
• evals/ is not included in the final package by default
• the archive preserves the skill directory structure at its root

Step 7: Post-generation self-test

If the user asks you to “generate it and test it right away,” or explicitly asks you to invoke the newly generated docs-map skill:

• Choose one test prompt that best represents a core topic of the technology.
• Follow the target skill's rules: first read its own references/docs-map.md, then load only 1–3 of the most relevant pages.
• Check whether the output really distinguishes between Relevant map slice / Pages loaded / Answer / If we need to go deeper.
• Check whether it incorrectly treats the docs map as full documentation, or scans the whole site indiscriminately.
• Check whether the generated docs-map.md uses a reasonable and consistent fallback strategy between “heading summaries” and “usage summaries.”
• If you find problems, fix the generator first, then decide whether the current target skill should also be updated.

Step 8: Report the deliverables to the user

When finished, clearly tell the user:

• the generated skill name
• the skill directory path
• the docs map path
• the evals path
• the .zip package path (if any)
• if you fixed any structural issue in evals/evals.json or other generator resources, mention that too
• whether this run overwrote an existing skill or reused an already-matching one
• the basis for that judgment (for example, naming, semantics, docs-map structure, and whether the package state matched)
• whether a post-generation self-test was run, and what the result was
• which pages were actually loaded during the self-test, and whether the first round stayed within the 1–3 page limit
• if this run did not reveal any new functional problems, explicitly say No functional changes in this iteration or an equivalent statement
• how this skill should be triggered in the future

Quality standards for the target skill

The generated skill should satisfy these standards:

1. It is not a one-off answer

   • It should be reusable in future conversations.

2. It has a docs map resource

   • references/docs-map.md must exist.

3. It supports progressive loading

   • Read the docs map first, then load real pages by topic.

4. It respects same-origin and version constraints

   • Do not wander across domains, and do not lose language/version context.

5. Its output is verifiable

   • It has basic evals.
   • evals/evals.json must be valid JSON, with no syntax errors.

Naming suggestions

Prefer naming patterns like these by default:

• vite-docs-map
• fastapi-docs-map
• claude-code-docs-map
• nextjs-docs-map

If the user explicitly specifies a name, respect it; otherwise default to <technology>-docs-map.

Important constraints

• Do not just write a docs map and stop. You are expected to produce a complete skill.
• Do not invent page titles or headings. Only organize structure you actually discovered from indexes or pages.
• Do not dump the full documentation site into references/docs-map.md. This is a map, not a full mirror.
• Do not ignore the target skill's triggering description. The description must be specific enough that Claude knows when to use it.
• Do not generate an overly generic skill that fails to identify the target technology. The result should be clearly tied to the current technology and documentation site.
• Do not confuse the two kinds of skills. The generator skill creates <technology>-docs-map; the target skill uses an already-built docs map to route real documentation pages.

Output format

When you're done, prefer reporting like this:

Generated a new docs-map skill.

## Deliverables
- Skill name: <skill-name>
- Skill path: <path>
- Docs map: <path>/references/docs-map.md
- Evals: <path>/evals/evals.json
- Zip package: <dist-path-or-skipped>
- Target status: <overwritten | reused-existing>
- Target reason: <why this run reused or overwrote the target skill>
- Self-test summary: <loaded-pages + whether page count stayed within first-round limit>
- Iteration change type: <functional changes | reporting/rules only | no functional changes>

## What this skill is for
- <one-sentence explanation of how the generated skill should be triggered later>

## Documentation range bound to this skill
- Root: <docs-root>
- Index source: <index-source>
- Scope: <language/version/product>

How to think while generating the target skill

Your task is to turn “the docs URL the user provided” into “an agent skill that can be repeatedly invoked in the future.”

So at every step, ask yourself:

• Is this helping me build a skill that is reusable over the long term?
• Will this make it easier for a future agent to locate the correct documentation pages?
• Is this still just a one-off documentation organization? If so, the task is not finished yet.