Skip to main content
documentation-guide Guide documentation structure, content requirements, and project documentation best practices.
Use when: creating README, documentation, docs folder, project setup, technical docs.
Keywords: README, docs, documentation, CONTRIBUTING, CHANGELOG, ARCHITECTURE, API docs.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/AsiaOstrich/universal-dev-standards --skill documentation-guideThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository [UDS] ไปฅ Claude ๅ็ Agent tool ็ผๆๅคไปปๅกๆง่ก่ฎกๅ๏ผDAG-based๏ผๆ ๅค้จๅผๆ๏ผใ
Use when: executing a plan.json file with parallel/sequential task dependencies.
Keywords: orchestrate, plan, execute, DAG, task plan, ็ผๆ, ๆง่ก่ฎกๅ, ๅนถ่ก.
[UDS] ไป Spec ๆๆกฃใOpenSpec ๅๆดๆ่ช็ฑๆๆฌ้ๆฑ็ๆ plan.jsonใ
Use when: converting specifications into executable task plans for /orchestrate.
Keywords: plan, spec, task plan, ่ฎกๅ, ่งๆ ผ, ไปปๅก, plan.json, DAG.
[UDS] AI ่พ
ๅฉ git push ๅฎๅ
จๅฑ๏ผ่ดจ้้จ็ฆ + ๅไฝๆคๆ ใ
Use when: pushing commits, force pushing, pushing to protected branches, pushing feature branches.
Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation, ๆจ้, ไฟๆคๅๆฏ, ่ดจ้้จ็ฆ.
documentation-structure.md 6.9 KB name documentation-guide scope universal description Guide documentation structure, content requirements, and project documentation best practices.
Use when: creating README, documentation, docs folder, project setup, technical docs.
Keywords: README, docs, documentation, CONTRIBUTING, CHANGELOG, ARCHITECTURE, API docs.
Documentation Guide
Language : English | ็น้ซไธญๆ
Version : 2.1.0
Last Updated : 2026-03-17
Applicability : Claude Code Skills
Purpose
This skill provides comprehensive guidance on project documentation, including:
Documentation structure and file organization
Content requirements by project type
Writing standards for technical documents
Templates for common documentation types
Quick Reference (YAML Compressed)
document_matrix:
new: [REQ , REQ , if_app , if_app , REQ , NO , REC , REQ , REC
refactor:
REQ
REQ
REQ
REQ
REQ
REQ
REQ
REQ
REC
migration:
REQ
REQ
REQ
REQ
REQ
REQ
REQ
REQ
REC
maintenance:[REQ,
REC,
REC,
REC,
REC,
NO
,
if_app,
REQ,
if_app]
pyramid:
level_1:
"README.md โ Entry point, quick overview"
level_2:
"ARCHITECTURE.md โ System overview"
level_3:
"API.md, DATABASE.md, DEPLOYMENT.md โ Technical details"
level_4:
"ADR/, MIGRATION.md, CHANGELOG.md โ Change history"
root_files:
README.md:
required:
true
purpose:
"Project overview, quick start"
CONTRIBUTING.md:
required:
"recommended"
purpose:
"Contribution guidelines"
CHANGELOG.md:
required:
"recommended"
purpose:
"Version history"
LICENSE:
required:
"for OSS"
purpose:
"License information"
docs_structure:
INDEX.md:
"Documentation index"
ARCHITECTURE.md:
"System architecture"
API.md:
"API documentation"
DATABASE.md:
"Database schema"
DEPLOYMENT.md:
"Deployment guide"
MIGRATION.md:
"Migration plan (if applicable)"
ADR/:
"Architecture Decision Records"
naming:
root:
"UPPERCASE.md (README.md, CONTRIBUTING.md, CHANGELOG.md)"
docs:
"lowercase-kebab-case.md (getting-started.md, api-reference.md)"
quality:
format:
language:
"English (or project-specified)"
encoding:
"UTF-8"
line_length:
"โค120 characters recommended"
diagrams:
"Mermaid preferred, then ASCII Art"
links:
"Relative paths for internal links"
maintenance:
sync:
"Update docs when code changes"
version:
"Mark version and date at top"
review:
"Include docs in code review"
periodic:
"Review quarterly for staleness"
diataxis:
tutorial:
"Learning-oriented (getting-started.md)"
how_to:
"Task-oriented (deployment.md, migration.md)"
reference:
"Information-oriented (api-reference.md, CHANGELOG.md)"
explanation:
"Understanding-oriented (architecture.md, ADR/)"
header:
"Add **Document Type**: Tutorial | How-to | Reference | Explanation"
llm_discovery:
llms_txt:
"Structured index at project root for LLM retrieval"
llms_full_txt:
"Optional full concatenated docs"
when:
"Public projects, public APIs, projects using AI tools"
quality_metrics:
leading:
"Coverage โฅ90%"
"Freshness โค90d"
"Link Health 100%"
"Example Validity 100%"
lagging:
"Support ticket reduction"
"Onboarding time"
"Doc-related PR comments"
tools:
markdown-link-check
lychee
remark-lint
vale
textstat
adr_enhanced:
new_fields:
Date
Deciders
Drivers
"supersedes/superseded-by"
lifecycle:
"proposed โ accepted โ [deprecated | superseded]"
decision_matrix:
"impact ร reversibility โ ADR required?"
translation_friendly:
rules:
"Complete sentences"
"No idioms"
"Consistent terminology"
"Simple SVO"
"Explicit references"
glossary:
"Maintain glossary.md for term consistency"
status_tracking:
"YAML frontmatter with translation_status, source_version"
Project Type Document Requirements
Document Requirements Matrix Document New Project Refactoring Migration Maintenance README.md โ
Required โ
Required โ
Required โ
Required ARCHITECTURE.md โ
Required โ
Required โ
Required โช Recommended API.md โช If applicable โ
Required โ
Required โช Recommended DATABASE.md โช If applicable โ
Required โ
Required โช Recommended DEPLOYMENT.md โ
Required โ
Required โ
Required โช Recommended MIGRATION.md โ Not needed โ
Required โ
Required โ Not needed ADR/ โช Recommended โ
Required โ
Required โช If applicable CHANGELOG.md โ
Required โ
Required โ
Required โ
Required
Project Type Quick Reference ๐ New Project โ README + ARCHITECTURE + DEPLOYMENT + CHANGELOG
๐ Refactoring โ All documents + MIGRATION + ADR (document "why refactor")
๐ Migration โ All documents + MIGRATION (core document) + data verification
๐ง Maintenance โ README + CHANGELOG (update based on change scope)
Documentation Pyramid โโโโโโโโโโโโโโโ
โ README โ โ Entry point, quick overview
โโโโโโโโโโโโโโโค
โโโโดโโโโโโโโโโโโโโดโโโ
โ ARCHITECTURE โ โ System overview
โโโโโโโโโโโโโโโโโโโโโค
โโโโดโโโโโโโโโโโโโโโโโโโโดโโโ
โ API / DATABASE / DEPLOY โ โ Technical details
โโโโโโโโโโโโโโโโโโโโโโโโโโโค
โโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโ
โ ADR / MIGRATION / CHANGELOG โ โ Change history
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Document Templates (YAML Compressed)
readme:
minimum:
- "# Project Name"
- "Brief one-liner description"
- "## Installation"
- "## Usage"
- "## License"
recommended:
- "# Project Name + Badges"
- "## Features (bullet list)"
- "## Installation"
- "## Quick Start / Usage"
- "## Documentation (link to docs/)"
- "## Contributing (link to CONTRIBUTING.md)"
- "## License"
architecture:
required:
- system_overview: "Purpose, scope, main functions"
- architecture_diagram: "Mermaid or ASCII Art"
- module_description: "Responsibilities, dependencies"
- technology_stack: "Frameworks, languages, versions"
- data_flow: "Main business process"
recommended:
- deployment_architecture: "Production topology"
- design_decisions: "Key decisions (or link to ADR)"
api:
required:
- api_overview: "Version, base URL, authentication"
- authentication: "Token acquisition, expiration"
- endpoint_list: "All API endpoints"
- endpoint_specs: "Request/response format"
- error_codes: "Error codes and descriptions"
recommended:
- code_examples: "Examples in common languages"
- rate_limiting: "API call frequency limits"
endpoint_format: |
### POST /api/v1/resource
**Request**: | Field | Type | Required | Description |
**Response**: | Field | Type | Description |
**Errors**: | Code | Description |
database:
required:
- db_overview: "Type, version, connection info"
- er_diagram: "Entity relationship diagram"
- table_list: "All tables with purposes"
- table_specs: "Column definitions"
- index_docs: "Indexing strategy"
- migration_scripts: "Script locations"
recommended:
- backup_strategy: "Frequency, retention"
table_format: |
### TableName
**Columns**: | Column | Type | Nullable | Default | Description |
**Indexes**: | Name | Columns | Type |
**Relations**: | Related | Join | Relationship |
deployment:
required:
- environment_requirements: "Hardware, software, network"
- installation_steps: "Detailed process"
- configuration: "Config file parameters"
- verification: "Confirm successful deployment"
- troubleshooting: "Common issues and solutions"
recommended:
- monitoring: "Health checks, log locations"
- scaling_guide: "Horizontal/vertical scaling"
migration:
required:
- overview: "Goals, scope, timeline"
- prerequisites: "Required preparation"
- migration_steps: "Detailed process"
- verification_checklist: "Post-migration checks"
- rollback_plan: "Steps on failure"
- backward_compatibility: "API/DB compatibility"
recommended:
- partner_notification: "External systems to notify"
adr:
filename: "NNN-kebab-case-title.md (e.g., 001-use-postgresql.md)"
required:
- title: "Decision name"
- status: "proposed | accepted | deprecated | superseded"
- context: "Why this decision is needed"
- decision: "Specific decision content"
- consequences: "Impact (positive/negative)"
recommended:
- alternatives: "Other options considered"
File Location Standards project-root/
โโโ README.md # Project entry document
โโโ CONTRIBUTING.md # Contribution guide
โโโ CHANGELOG.md # Change log
โโโ LICENSE # License file
โโโ docs/ # Documentation directory
โโโ INDEX.md # Documentation index
โโโ ARCHITECTURE.md # Architecture document
โโโ API.md # API document
โโโ DATABASE.md # Database document
โโโ DEPLOYMENT.md # Deployment document
โโโ MIGRATION.md # Migration document (if needed)
โโโ ADR/ # Architecture decision records
โโโ 001-xxx.md
โโโ ...
README.md Required Sections
Minimum Viable README # Project Name
Brief one-liner description.
## Installation
```bash
npm install your-package
Usage const lib = require ('your-package' );
lib.doSomething ();
License
### Recommended README Sections
1. **Project Name & Description**
2. **Badges** (CI status, coverage, npm version)
3. **Features** (bullet list)
4. **Installation**
5. **Quick Start / Usage**
6. **Documentation** (link to docs/)
7. **Contributing** (link to CONTRIBUTING.md)
8. **License**
---
## ADR Template
```markdown
# ADR-001: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded
**Deciders**: [List of people involved]
**Supersedes**: ADR-NNN (if applicable)
**Superseded by**: ADR-NNN (if applicable)
## Drivers
- [Key factor 1]
- [Key factor 2]
## Context
[Why this decision is needed...]
## Decision
[Specific decision...]
## Consequences
### Positive
- Benefit 1
- Benefit 2
### Negative
- Drawback 1
- Drawback 2
## Alternatives Considered
### Alternative A: [Name]
- **Pros**: ...
- **Cons**: ...
- **Rejected because**: ...
When to write ADR (impact ร reversibility):
High impact + Hard to reverse โ ADR requiredHigh impact + Easy to reverse โ OptionalLow impact + Hard to reverse โ OptionalLow impact + Easy to reverse โ No ADR needed
Documentation Audit Checklist When reviewing a project's documentation:
โก README.md exists with essential sections
โก Installation instructions are clear and tested
โก Usage examples are provided and work
โก License specified
โก ARCHITECTURE.md exists (for non-trivial projects)
โก API.md exists (if APIs exposed)
โก DATABASE.md exists (if databases used)
โก DEPLOYMENT.md exists (for deployed projects)
โก ADR/ exists for major decisions
โก CHANGELOG.md follows Keep a Changelog format
โก All internal links working
โก Diagrams are up to date
โก No outdated information
Configuration Detection
Detection Order
Check CONTRIBUTING.md for "Disabled Skills" section
Check CONTRIBUTING.md for "Documentation Language" section
Check existing documentation structure
If not found, default to English
First-Time Setup If documentation is missing:
Ask: "This project doesn't have complete documentation. Which language should I use? (English / ไธญๆ)"
Determine project type (new/refactor/migrate/maintain)
Create required documents based on matrix
Suggest documenting in CONTRIBUTING.md:
## Documentation Standards
### Language
This project uses **English** for documentation.
### Required Documents
Based on project type, we maintain:
- README.md
- ARCHITECTURE.md
- DEPLOYMENT.md
- CHANGELOG.md
Detailed Guidelines For complete standards, see:
Next Steps Guidance | ไธไธๆญฅๅผๅฐ After /docs-guide completes, the AI assistant should suggest:
ๆไปถ็ตๆง่้ๆฑๅทฒ้ๆธ
ใๅปบ่ญฐไธไธๆญฅ / Documentation structure and requirements clarified. Suggested next steps:
ๅท่ก /docs ๆ นๆๆๅ็ดๆฅ็ข็ๅฐๆกๆไปถ โญ Recommended / ๆจ่ฆ โ ็ซๅณๅฐๆไปถๆๅๅ็บ่กๅ / Turn documentation guidelines into action immediately
ๅท่ก /changelog ๅปบ็ซๆๆดๆฐ CHANGELOG.md โ ็ขบไฟ่ฎๆดๆญทๅฒๅฎๆด / Ensure change history is complete
ๅท่ก /sdd ๅฐๆไปถ้ๆฑ็ดๅ
ฅ่ฆๆ ผ้ฉ
ๅ้็ผ โ ็ขบไฟๆไปถ่ๅ่ฝๅๆญฅ / Ensure docs stay in sync with features
Related Standards
Version History Version Date Changes 2.1.0 2026-03-17 Added: Diรกtaxis classification, LLM discovery, quality metrics, enhanced ADR template, translation-friendly writing 2.0.0 2026-01-12 Added: Project type matrix, document templates, documentation pyramid 1.0.0 2025-12-24 Initial release
License Related occupations SOC
Based on SOC occupation classification
