docs-creator
Standardizes documentation authoring by following Diataxis principles for structure and placement.
Install
mkdir -p .claude/skills/docs-creator && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/12251" && unzip -o skill.zip -d .claude/skills/docs-creator && rm skill.zipInstalls to .claude/skills/docs-creator
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Create or improve documentation files with Diataxis-aware placement and consistent naming. Use when the user wants to create any new documentation, improve existing docs, write a README, or restructure documentation. Also use when asked to "write docs", "improve this doc", "add a tutorial", "update the readme", or any request involving markdown documentation authoring, even if they don't explicitly say "create documentation".Key capabilities
- →Create new documentation files for READMEs, specs, or tutorials.
- →Improve existing documentation content.
- →Apply consistent structure to unstructured documentation.
- →Resolve placement for new documents based on Diataxis mapping.
- →Resolve filenames using kebab-case, lowercase, and .md extension.
- →Gather context from relevant source files to populate documentation.
How it works
The skill determines the intent, resolves document placement and filename, gathers context from source files, then writes or updates the documentation content.
Inputs & outputs
When to use docs-creator
- →Create a new project README
- →Write a how-to guide for a feature
- →Structure technical architecture docs
About this skill
UTILITY SKILL — creates and improves documentation content.
Input
- Request (required): natural language describing what to document
- target_file (optional): explicit path when updating an existing file
Output Specification
Return structured report per references/common-output-format.md.
Execution Scope
USE FOR:
- Create new documentation files (README, specs, architecture, tutorials, how-to guides)
- Improve or rewrite existing documentation content
- Apply consistent structure to unstructured docs
DO NOT USE FOR:
- Syncing docs after code changes
- Source code comments or docstrings
- Markdown linting
- Auto-generated references (godoc, terraform-docs output)
Reference Files Guide
- category-diataxis-mapping.md (always read)
- common-checklist.md (always read)
- common-output-format.md (always read)
Workflow
-
Determine intent: new document or improvement to existing one? If neither can be inferred, stop with
Status: blocked. -
Detect the existing docs layout: list the repository's documentation directories and any
docs/index.md,mkdocs.yml, or README docs-index markers.- Existing layout found (for example
docs/guides/,docs/api/, or Diataxis directories): place the new file in the matching existing directory. - No docs layout yet: use the Diataxis fallback in category-diataxis-mapping.md.
- README → repository root.
- Existing layout found (for example
-
Resolve filename: kebab-case, lowercase,
.md. No version numbers. Iftarget_fileis provided and exists, use it as-is. If the same filename already exists in a different docs directory, stop and ask the user. -
Gather context: read the sources for the document type before writing. The document should be self-sufficient — a reader understands the system without reading source code. Remove sections that cannot be populated rather than leaving filler.
Document type Read first README Entry points, build/run/test commands in manifests or task files, top-level config, license Tutorial / How-to The commands, scripts, and config the steps use; existing tests that exercise the same path Reference Public interfaces: CLI flags, config schemas, API signatures, environment variables Explanation / spec Module structure, design records or ADRs, and the code paths that implement the topic Improving a doc The existing file in full, plus the sources above for its type, to correct stale content -
Write or update:
- New: structure content per the target directory's purpose (Diataxis quadrant intent when the fallback applies).
- Existing: preserve original structure. Additions at end of sections. Restructuring requires explicit user request.
- Cross-references: relative paths with
.mdextension.
-
Update
docs/index.mdonly when it already exists and follows the template in common-checklist.md, or when the user asks for it. Otherwise leave it unchanged and note it in the report. -
Update mkdocs.yml nav if the file exists. Place the entry in the section matching the file's directory.
-
Update README markers (
<!-- docs-index-start/end -->) if present. -
Self-check every created or updated file against QV-01..QV-05 in common-checklist.md. Fix failures before reporting; list any that remain in
## Noteswith the ItemID. -
Return the report.
Error Handling
| Condition | Severity | Action |
|---|---|---|
| No docs directory exists | Recoverable | Create the Diataxis fallback directory needed, continue |
| Ambiguous intent | Blocking | Ask user; report Status: blocked |
Request matches DO NOT USE FOR | Blocking | Do not edit; report Status: blocked; explain in ## Notes |
target_file given but does not exist | Recoverable | Treat as a new file at that path; note it in the report |
| Same filename exists in a different docs directory | Blocking | Stop and ask user; report Status: blocked with both paths |
| Topic fits no quadrant and no existing directory | Blocking | Ask user for an explicit target_file |
docs/index.md exists but does not follow template | Recoverable | Leave unchanged; note in report |
| mkdocs.yml missing | Recoverable | Skip nav update |
| README markers malformed | Recoverable | Skip, note in report |
| QV check still fails after one fix attempt | Recoverable | Keep the file; list the QV ItemID and cause in ## Notes |
Examples
- Prompt:
Create architecture doc for caching(no existing docs layout) →docs/explanation/caching-architecture.md(see category-diataxis-mapping.md) - Prompt:
Improve the README→ updateREADME.mdin place - Prompt:
Write a getting started tutorial(no existing docs layout) →docs/tutorials/getting-started.md
When not to use it
- →Syncing documentation after code changes.
- →Generating source code comments or docstrings.
- →Performing Markdown linting.
Limitations
- →Restructuring existing documentation requires an explicit user request.
- →Cannot sync documentation after code changes automatically.
- →Does not perform Markdown linting.
How it compares
This skill automates the process of structuring, naming, and populating documentation based on a defined methodology, unlike manual documentation creation.
Compared to similar skills
docs-creator side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| docs-creator (this skill) | 0 | 4mo | No flags | Beginner |
| ml-paper-writing | 48 | 9mo | Review | Advanced |
| docs-review | 10 | 11mo | No flags | Beginner |
| claude-md-improver | 21 | 10mo | Review | Beginner |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
ml-paper-writing
davila7
Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Use when drafting papers from research repos, structuring arguments, verifying citations, or preparing camera-ready submissions. Includes LaTeX templates, reviewer guidelines, and citation verification workflows.
docs-review
metabase
Review documentation changes for compliance with the Metabase writing style guide. Use when reviewing pull requests, files, or diffs containing documentation markdown files.
claude-md-improver
anthropics
Audit and improve CLAUDE.md files in repositories. Use when user asks to check, audit, update, improve, or fix CLAUDE.md files. Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates. Also use when the user mentions "CLAUDE.md maintenance" or "project memory optimization".
write-docs
tldraw
Writing SDK documentation for tldraw. Use when creating new documentation articles, updating existing docs, or when documentation writing guidance is needed. Applies to docs in apps/docs/content/.
update-docs
vercel
This skill should be used when the user asks to "update documentation for my changes", "check docs for this PR", "what docs need updating", "sync docs with code", "scaffold docs for this feature", "document this feature", "review docs completeness", "add docs for this change", "what documentation is affected", "docs impact", or mentions "docs/", "docs/01-app", "docs/02-pages", "MDX", "documentation update", "API reference", ".mdx files". Provides guided workflow for updating Next.js documentation based on code changes.
wiki-architect
microsoft
Analyzes code repositories and generates hierarchical documentation structures with onboarding guides. Use when the user wants to create a wiki, generate documentation, map a codebase structure, or understand a project's architecture at a high level.