Claude Code Plugins

Community-maintained marketplace

Feedback

PRPM Documentation Standards

@pr-pm/prpm
10
0

Standards and guidelines for organizing, structuring, and maintaining documentation in the PRPM repository - ensures consistency across user docs, development docs, and internal references

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name PRPM 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

# 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:

See [Publishing Guide](./PUBLISHING.md)

Internal → User:

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

# Check markdown
markdownlint docs/

# Check links
markdown-link-check docs/**/*.md

Building Docs Site (Future)

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