docs-creator
/docs-creator
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.
- Author
- y-miyazaki ↗
- Repository
- terraform-aws-base ↗
- Licence
- Apache-2.0
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 10
- Scripts
- 0
- HTML comments
- 1
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
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.
Triggers from the description
Original author description
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.
How it works
- Input
- Output Specification
- Execution Scope
- Reference Files Guide
- Workflow
SKILL.md preview
--- name: docs-creator description: >- 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. license: Apache-2.0 metadata: author: y-miyazaki version: "2.0.0" --- **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](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](references/category-diataxis-mapping.md) (always read) - [common-checklist.md](references/common-checklist.md) (always read) - [common-output-format.md](references/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](references/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 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 | 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](references/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](references/common-checklist.md). Fix failures before reporting; list any that remain in `## Notes` with the ItemID. 10. 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](references/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`
Files in this package (10)
- SKILL.md 6 KB
- eval.yaml 1 KB
- evals/tasks/docs-creator-basic.yaml 1 KB
- evals/tasks/docs-creator-duplicate-path.yaml 1 KB
- evals/tasks/docs-creator-missing-input.yaml 1 KB
- evals/tasks/docs-creator-trigger-negative.yaml 1 KB
- evals/tasks/docs-creator-update-in-place.yaml 1 KB
- references/category-diataxis-mapping.md 1 KB
- references/common-checklist.md 2 KB
- references/common-output-format.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · y-miyazaki/terraform-aws-base | 100 | Apache-2.0 |
| y-miyazaki/terraform-aws-base | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 14f4621d3808 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95Diataxis-Documentation
Diataxis-based documentation methodology for creating, organizing, and planning documentation. USE WHEN user says 'set up docs', 'create documentation', 'document this project', 'plan documentation', 'organize docs', 'restructure docs', 'getting started guide', 'write a… - 100doc-gen
Generate documentation from source code — docstrings, READMEs, API references. Triggers on: generate docs, write documentation, document this, create README, API docs, doc-gen. - 95readme
When the user wants to create or update a README.md file for a project. Also use when the user says 'write readme,' 'create readme,' 'document this project,' 'project documentation,' or asks for he... - 100documentation-standards
This skill should be used when the user asks to "write documentation", "create docs", "document code", "improve documentation", "documentation best practices", "diataxis", "technical writing", "API documentation", "user guide", mentions documentation quality, documentation… - 90writing-documentation-with-diataxis
Applies the Diataxis framework to create or improve technical documentation. Use when being asked to write high quality tutorials, how-to guides, reference docs, or explanations, when reviewing documentation quality, or when deciding what type of documentation to create. Helps… - 100documentation
Use this skill when the user asks you to write, update, or fix project documentation — READMEs, API docs, user guides, ADRs, or other Markdown docs. Also use when code changes need user-facing docs updates. Only write Markdown files; do not use for implementation, planning or test work.