Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pr-pm/prpm --skill documentation-standards -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/documentation-standards/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/documentation-standards/

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.

documentation-standards terrylica documentation-standards defines Markdown guidelines tailored for LLM parsing and clean Pandoc PDF export. It stops broken section numbering and unstructured doc sprawl. CX Codex +1 161installs markdown microsoft Defines Markdown conventions and YAML frontmatter requirements across all .md files. Keeps Claude Code aligned with markdownlint rules. CX Codex +1 ★ 1,627repo stars documentation-and-adrs addyosmani The documentation-and-adrs Claude Code skill records architecture decisions and helps detect documentation that no longer matches the code. It applies during public API changes, feature releases, and documentation checks. CX Codex +1 80,700installs documentation-writer official github documentation-writer — a skill that turns the agent into a technical writer following the Diátaxis framework: tutorials, how-to guides, reference, and explanation. Proposes structure before writing. CX Codex +1 27,757installs oo-component-documentation official github The oo-component-documentation skill creates or updates object-oriented component docs from code or an existing Markdown file. It helps keep new and revised documentation in one format. CX Codex +1 1,800installs catalog-documentation-creator eventcatalog catalog-documentation-creator generates EventCatalog documentation files for services, events, ADRs, and domains with valid YAML frontmatter. Works from prompts or scans existing codebases. CX Codex +1 1,400installs markdown-documentation aj-geddes markdown-documentation — a skill that gives the agent a fixed set of Markdown rules for READMEs, wikis and docs pages. Useful when the model writes the text and it has to look consistent. CX Codex +1 1,300installs

From the same set3

Project sponsors

Companies that keep this analytics open