documentation-standards · pr-pm — Claude Code skill: how to install
documentation-standards defines repository documentation layout: keeps internal contributor docs in development/docs/, public manuals in docs/, and root files like README.md.
MIT 1 installs ★ 125 updated 2026-10-14
npx skills add pr-pm/prpm --skill documentation-standards -a claude-codeWhat documentation-standards does
This skill enforces directory conventions across the PRPM repository. Internal notes covering CI/CD workflows, publishing steps, and Docker runbooks belong in development/docs/. Public tutorials, package authoring guides, and CLI references live in root docs/.
Markdown rules mandate kebab-case file names, heading hierarchy, and a table of contents whenever a file exceeds 200 lines. The setup uses markdownlint to inspect formatting and markdown-link-check to catch broken relative links.
Because the rules enforce PRPM-specific paths, running them inside a different project requires manual adjustments to folder targets.
What it helps with
- sort user guides and internal developer runbooks into dedicated directories
- format markdown files over 200 lines with proper headings and a table of contents
- validate relative links and markdown syntax using automated checkers
- follow a migration checklist when moving documents to prevent broken links
Example prompts for the agent
- Where should I place an internal runbook for Docker setup?
- Structure this new user guide according to repository standards
- Help migrate a guide to the public docs folder using the checklist
How to install documentation-standards
1Skills CLI (Vercel)
npx skills add pr-pm/prpm --skill documentation-standards -a claude-code2Manually: put the files in place
~/.claude/skills/documentation-standards/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/documentation-standards/
1Skills CLI (Vercel)
npx skills add pr-pm/prpm --skill documentation-standards -a codex2Manually: put the files in place
.agents/skills/documentation-standards/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pr-pm/prpm --skill documentation-standards -a cursor2Manually: put the files in place
.cursor/skills/documentation-standards/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pr-pm/prpm .claude/skills/documentation-standards2Manually: put the files in place
.github/skills/documentation-standards/SKILL.md1Skills CLI (Vercel)
npx skills add pr-pm/prpm --skill documentation-standards -a gemini-cli2Platform CLI
gemini skills install https://github.com/pr-pm/prpm --path .claude/skills/documentation-standardsManually: put the files in place
.devin/skills/documentation-standards/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pr-pm/prpm --skill documentation-standards -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about documentation-standards
How to install documentation-standards in Claude Code?
Run npx skills add pr-pm/prpm --skill documentation-standards -a claude-code.
What does documentation-standards do?
It establishes documentation placement rules, separating internal engineering guides in development/docs/ from end-user material in docs/ and AI assistant knowledge.
Which linting tools does it use?
It uses markdownlint for Markdown syntax verification and markdown-link-check to test relative hyperlinks.
Source text
SKILL.md · MIT
---
name: documentation-standards
description: Standards and guidelines for organizing, structuring, and maintaining documentation in the PRPM repository - ensures consistency across user docs, development docs, and internal references
---
# PRPM Documentation Standards
## Documentation Organization
### Internal Documentation (development/docs/)
**Purpose:** Documentation for developers working on PRPM itself
**Location:** `development/docs/`
**Files:**
- `GITHUB_WORKFLOWS.md` - GitHub Actions workflows reference
- `PUBLISHING.md` - NPM package publishing process and order
- `DEVELOPMENT.md` - Development setup, environment, and workflows
- `DOCKER.md` - Docker setup, services, and troubleshooting
**Audience:** PRPM contributors, maintainers, CI/CD systems
---
### User-Facing Documentation (docs/)
**Purpose:** Documentation for PRPM users and package authors
**Location:** `docs/` (at project root)
**Files:**
- User guides
- API documentation
- Package authoring guides
- CLI command reference
- Examples and tutorials
**Audience:** PRPM end users, package authors, integrators
---
### Project-Level Documentation (root)
**Purpose:** Standard project files that belong at repository root
**Location:** Project root `/`
**Files:**
- `README.md` - Project overview, quick start, installation
- `CONTRIBUTING.md` - Contribution guidelines
- `CHANGELOG.md` - Version history and changes
- `LICENSE` - License information
- `ROADMAP.md` - Project roadmap and future plans
**Audience:** Everyone (first impression)
---
### Claude Skills (.claude/skills/)
**Purpose:** Knowledge base and reference materials for AI assistants
**Location:** `.claude/skills/`
**Files:**
- `postgres-migrations-skill.md` - PostgreSQL migrations guidance
- `pulumi-troubleshooting-skill.md` - Pulumi troubleshooting
- `NEW_SKILLS.md` - How to create new skills
- `documentation-standards.md` - This file
**Subdirectories:**
- `prpm-development/` - PRPM-specific development knowledge
- `self-improving/` - Self-improvement patterns
- `thoroughness/` - Thoroughness and quality guidelines
**Audience:** AI assistants (Claude, etc.)
---
## Rules for Documentation Placement
### When to use development/docs/
✅ GitHub Actions workflows and CI/CD
✅ Internal build/release processes
✅ Development environment setup
✅ Architecture decision records
✅ Internal troubleshooting guides
✅ Database schema documentation
✅ Infrastructure documentation
❌ User-facing tutorials
❌ CLI usage guides
❌ API reference for end users
### When to use docs/
✅ User guides and tutorials
✅ CLI command reference
✅ Package authoring guides
✅ API documentation for users
✅ Integration examples
✅ FAQ for users
❌ Internal development workflows
❌ CI/CD documentation
❌ Build/release processes
### When to use .claude/skills/
✅ Specialized knowledge for AI assistants
✅ Domain-specific best practices
✅ Troubleshooting patterns
✅ Code review guidelines
✅ Project-specific conventions
❌ General documentation
❌ User guides
❌ API references
---
## Documentation Standards
### Markdown Files
- Use clear, descriptive filenames (kebab-case)
- Include table of contents for docs > 200 lines
- Use proper heading hierarchy (# → ## → ###)
- Include code examples with syntax highlighting
- Add frontmatter if using a static site generator
### Example Structure
```markdown
# Title
Brief description (1-2 sentences)
## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)
## Section 1
Content...
### Subsection 1.1
Details...
## Examples
\`\`\`bash
# Example command
prpm install @username/package-name
\`\`\`
## See Also
- [Related Doc](./related.md)
```
### Cross-References
- Use relative paths for links
- Keep links within same category when possible
- Update links when moving files
**Internal → Internal:**
```markdown
See [Publishing Guide](./PUBLISHING.md)
```
**Internal → User:**
```markdown
See [User Guide](../../docs/user-guide.md)
```
---
## Migration Checklist
When reorganizing documentation:
1. ✅ Move file to correct location
2. ✅ Update all references to moved file
3. ✅ Update README.md links if needed
4. ✅ Update .gitignore if needed
5. ✅ Test that all links work
6. ✅ Commit with clear message explaining move
---
## Package-Specific Documentation
Each package should have its own README:
```
packages/
├── cli/
│ └── README.md # CLI package overview
├── registry/
│ └── README.md # Registry server docs
├── registry-client/
│ └── README.md # Client library docs
├── types/
│ └── README.md # Type definitions docs
└── webapp/
└── README.md # WebApp docs
```
---
## Maintenance
### Regular Reviews
- Quarterly review of docs/ for accuracy
- Remove outdated documentation
- Update examples to use latest version
- Check for broken links
### When Adding Features
- Update relevant user docs in `docs/`
- Update internal docs in `development/docs/` if needed
- Add examples
- Update CHANGELOG.md
### When Deprecating Features
- Add deprecation notice to docs
- Provide migration guide
- Keep docs until feature is removed
- Update CHANGELOG.md
---
## Quick Reference
| Documentation Type | Location | Audience | Examples |
|--------------------|----------|----------|----------|
| Internal Dev | `development/docs/` | Contributors | CI/CD, publishing |
| User-Facing | `docs/` | Users | Guides, tutorials |
| Project Root | `/` | Everyone | README, LICENSE |
| AI Skills | `.claude/skills/` | AI assistants | Troubleshooting |
| Package Docs | `packages/*/README.md` | Package users | API reference |
---
## Tools
### Documentation Generators
- **TypeDoc** - For TypeScript API docs (future)
- **VitePress** or **Docusaurus** - For docs/ site (future)
### Linting
```bash
# Check markdown
markdownlint docs/
# Check links
markdown-link-check docs/**/*.md
```
### Building Docs Site (Future)
```bash
cd docs/
npm run build
```
---
## Examples
### Good Documentation Structure
```
prpm/
├── README.md # Project overview
├── CONTRIBUTING.md # How to contribute
├── CHANGELOG.md # Version history
├── ROADMAP.md # Future plans
├── development/
│ └── docs/
│ ├── GITHUB_WORKFLOWS.md # CI/CD reference
│ ├── PUBLISHING.md # Release process
│ ├── DEVELOPMENT.md # Dev setup
│ └── DOCKER.md # Services setup
├── docs/
│ ├── getting-started.md # User onboarding
│ ├── cli-reference.md # Command reference
│ ├── package-authoring.md # Creating packages
│ └── api/
│ └── registry-client.md # API docs
└── .claude/
└── skills/
├── documentation-standards.md
├── postgres-migrations-skill.md
└── pulumi-troubleshooting-skill.md
```
### Bad Documentation Structure ❌
```
prpm/
├── README.md
├── WORKFLOWS.md # Should be in development/docs/
├── USER_GUIDE.md # Should be in docs/
├── dev-setup.md # Should be in development/docs/
└── troubleshooting.md # Unclear audience/location
```
---
## Version
**Last Updated:** 2025-10-21
**Applies To:** PRPM v2+
**Review Date:** 2026-01-21
© pr-pm · MIT · pr-pm/prpm
Similar skills
All skills for Writing and docs →documentation-standards by other authors comes first.