Docs Plugin¶

Name: docs

Description: Generate and keep documentation in sync with your codebase

Author: Flop (flopspm@gmail.com)

Version: 1.1.1

Keywords: documentation, sync, git, automation

The Docs plugin helps automate documentation workflows by generating initial documentation for undocumented projects and keeping existing documentation synchronized with code changes.

Installation¶

claude plugin install docs@flugins

Important: After installing the plugin, restart Claude Code to activate skills.

Tip: Enable auto-update via /plugin → Installed → select the plugin → enable auto-update.

Features¶

Commands¶

Generate Documentation - Create initial docs for undocumented areas
Sync Documentation - Update docs based on recent commits

Skills¶

Documentation Loader - Automatically loads project documentation before code tasks

Generate Documentation¶

Command: /docs:generate-docs

Analyzes your project structure and creates initial documentation for undocumented areas.

Usage¶

/docs:generate-docs

What it does¶

Asks you to specify the documentation folder (e.g., docs/, documentation/)
Scans existing documentation to understand what's already covered
Analyzes project structure:
Identifies project type (Node.js, Python, Rust, Go, etc.)
Locates main source directories
Finds entry points and configuration files
Identifies documentation gaps:
Missing API documentation
Undocumented configuration options
Missing architecture overview
Missing getting started guide
Undocumented CLI commands
Proposes 3-5 most-needed documents
Creates approved documents with proper structure and content

Example Workflow¶

# Run the command
/docs:generate-docs

# Claude will ask: "Which folder should I use for documentation?"
docs/

# Claude analyzes the project and proposes documents
# Example output:
# "I suggest creating the following documents:
#  1. api-reference.md - API endpoints and usage
#  2. architecture.md - System design and components
#  3. troubleshooting.md - Common issues and solutions
#  Confirm creation (yes/no) or specify which document numbers to create"

# Approve all or select specific documents
yes
# or
1, 3

Best Practices¶

Run this when starting a new project to establish documentation structure
Use it to fill gaps in partially documented projects
Review and customize generated documents to match your project's specific needs
Keep the generated documents as a starting point and iterate on them

Use Cases¶

New Project Setup: Generate complete initial documentation set
Documentation Audit: Identify and fill gaps in existing documentation
Onboarding: Create comprehensive guides for new team members
Open Source: Quickly establish professional documentation for public projects

Sync Documentation¶

Command: /docs:sync-docs [number_of_commits]

Analyzes recent git commits and updates documentation to reflect code changes.

Usage¶

# Analyze last 5 commits (default)
/docs:sync-docs

# Analyze specific number of commits
/docs:sync-docs 10
/docs:sync-docs 20

Parameters¶

number_of_commits (optional): Number of recent commits to analyze. Default: 5

What it does¶

Extracts the specified number of recent commits from git history
Analyzes commit messages and full diffs to understand changes
Reads the current state of all modified files
Identifies the documentation folder automatically
Compares documentation with actual code:
New features not yet documented
Removed features still mentioned in docs
Changed APIs or configurations
Outdated code examples
Broken file references
Updates all affected documentation files
Provides a summary of changes made

Example Workflow¶

# After making several code changes
git add .
git commit -m "Add authentication middleware"
git commit -m "Update API endpoints"
git commit -m "Refactor database connection"

# Sync documentation with the last 3 commits
/docs:sync-docs 3

# Claude analyzes changes and updates relevant docs
# Example output:
# "Updated documentation based on 3 recent commits:
#  - api-reference.md: Added new /auth endpoints
#  - architecture.md: Updated authentication flow diagram
#  - getting-started.md: Added authentication setup steps"

Best Practices¶

Run after completing a feature or significant change
Use higher commit counts (10-20) for major refactors
Review the changes to ensure accuracy
Combine with regular code reviews
Set up as a pre-release checklist item

Use Cases¶

Feature Development: Keep docs updated as you add new features
Refactoring: Ensure architectural changes are reflected in docs
API Changes: Automatically update endpoint documentation
Configuration Updates: Sync environment variable docs with code
Pre-Release: Verify documentation is current before releases
CI/CD Integration: Run as part of your documentation validation pipeline

Checked Areas¶

The sync command thoroughly checks:

Architecture documentation
Project structure and file listings
Environment variables and configuration
API endpoint documentation
README files and navigation links
Code examples and API usage
Installation and setup instructions
Dependencies and requirements

Tips and Tricks¶

Documentation Workflow¶

Initial Setup: Use /docs:generate-docs to create documentation structure
Continuous Sync: Use /docs:sync-docs regularly during development
Pre-Release: Run /docs:sync-docs 20 before releases to catch all changes
After Merges: Sync after merging feature branches to update docs

Performance Optimization¶

Use lower commit counts (3-5) for quick daily syncs
Use higher commit counts (10-20) for comprehensive pre-release checks
Run generate-docs once, then rely on sync-docs for updates

Integration Ideas¶

Add sync-docs to your PR checklist
Create a git hook to remind you to sync docs before pushing
Document your documentation workflow in CONTRIBUTING.md
Add Github action with Claude to update docs on commit

Documentation Loader¶

Skill: docs-loader Type: Model-invoked (automatic)

The Documentation Loader skill automatically loads relevant project documentation into context before Claude performs code-related tasks (features, refactoring, bugs, architecture). This ensures changes align with project patterns, architecture, and conventions.

How it Works¶

When you ask Claude to work with code, this skill delegates discovery and reading to the Explore subagent in a single call. The subagent:

Searches documentation directories - Looks in docs/, documentation/, or .docs/
Reads the index - Loads index.md or README.md to understand the structure
Selects relevant docs - Picks the 2–4 most relevant files for the user's task
Spot-checks claims - Verifies key file paths, function names, and patterns against the actual code
Returns the contents - Hands back file contents plus a ⚠️ DOCS MISMATCH block if any discrepancy was found

Claude then uses the loaded documentation to align with documented patterns, cite specific sections when making decisions, and warn the user about any drift between docs and code.

When it Activates¶

The skill activates proactively for:

✓ Adding new features or functionality
✓ Refactoring existing code
✓ Fixing bugs requiring architectural understanding
✓ Explaining how the codebase works
✓ Multi-file changes
✓ Tasks requiring alignment with project patterns

The skill skips activation for:

✗ Simple typo fixes
✗ One-line changes to known code
✗ Pure debugging with stack traces
✗ When explicitly told to skip docs

Example Usage¶

Without docs-loader:

User: "Add a POST /api/users endpoint"
Claude: Creates endpoint based on general best practices

With docs-loader:

User: "Add a POST /api/users endpoint"
Claude:
  1. Loads docs/architecture/api-patterns.md
  2. Loads docs/security/auth.md
  3. Creates endpoint following project's specific patterns
  4. Uses project's validation approach
  5. Matches existing API structure

Benefits¶

Consistency: New code matches existing patterns and conventions
Architecture alignment: Changes respect documented architectural decisions
Faster development: No need to manually read docs before each task
Better quality: Code follows project-specific best practices
Context awareness: Claude understands your project's unique structure

What Documentation to Provide¶

For best results, maintain documentation covering:

Architecture overview - System design and component relationships
Code patterns - Naming conventions, file structure, common patterns
API documentation - Endpoint structure, authentication, validation
Development guides - Setup instructions, testing approaches
Configuration - Environment variables, feature flags

The skill works with any documentation structure. See the SKILL.md reference for detailed behavior.