agentleFS
Sign inStart free
y-miyazakiy-miyazaki/config/.agents/skills/docs-creator/SKILL.md

docs-creator

Skill1 starsChanged 9 days agoApache-2.0View on GitHub

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". Not for syncing docs after code changes, source code docstrings, or Markdown linting.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create new documentation files (README, specs, architecture, tutorials, how-to guides)

    line 31
  2. Distinctive:

    No docs layout yet: use the Diataxis fallback in category-diataxis-mapping.md.

    line 54
  3. Distinctive:

    Gather context: read the sources for the document type before writing.

    line 59
  4. Very specific:

    Update docs/index.md: only when it already exists and follows the template in common-checklist.md, or when the user asks for it.

    line 75
  5. Very specific:

    Update mkdocs.yml nav: if the file exists. Place the entry in the section matching the file's directory.

    line 77
  6. Very specific:

    Self-check: every created or updated file against QV-01..QV-05 in common-checklist.md.

    line 81

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. Determine intent: new document or improvement to existing one? If neither can be inferred, stop with Status: blocked.
  2. 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.
  3. Resolve filename: kebab-case, lowercase, .md. No version numbers. If target_file is provided and exists, use it as-is. If the same filename already exists in a different docs directory, stop and ask the user.

  4. 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 typeRead first
    READMEEntry points, build/run/test commands in manifests or task files, top-level config, license
    Tutorial / How-toThe commands, scripts, and config the steps use; existing tests that exercise the same path
    ReferencePublic interfaces: CLI flags, config schemas, API signatures, environment variables
    Explanation / specModule structure, design records or ADRs, and the code paths that implement the topic
    Improving a docThe existing file in full, plus the sources above for its type, to correct stale content

  5. 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 .md extension.
  6. Update docs/index.md only 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.
  7. Update mkdocs.yml nav if the file exists. Place the entry in the section matching the file's directory.
  8. Update README markers (<!-- docs-index-start/end -->) if present.
  9. 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 ## Notes with the ItemID.
  10. Return the report.

Error Handling

ConditionSeverityAction
No docs directory existsRecoverableCreate the Diataxis fallback directory needed, continue
Ambiguous intentBlockingAsk user; report Status: blocked
Request matches DO NOT USE FORBlockingDo not edit; report Status: blocked; explain in ## Notes
target_file given but does not existRecoverableTreat as a new file at that path; note it in the report
Same filename exists in a different docs directoryBlockingStop and ask user; report Status: blocked with both paths
Topic fits no quadrant and no existing directoryBlockingAsk user for an explicit target_file
docs/index.md exists but does not follow templateRecoverableLeave unchanged; note in report
mkdocs.yml missingRecoverableSkip nav update
README markers malformedRecoverableSkip, note in report
QV check still fails after one fix attemptRecoverableKeep 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 → update README.md in place
  • Prompt: Write a getting started tutorial (no existing docs layout) → docs/tutorials/getting-started.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free