docs-workflow

Last Updated: 2026-01-11 Purpose: Manage project documentation throughout its lifecycle

Overview

This skill helps you:

• •Initialize documentation for new projects (CLAUDE.md, README.md, docs/)
• •Maintain CLAUDE.md to match actual project state
• •Audit all docs for staleness, broken links, outdated versions

Commands

Quick Start

New Project

# In a new project directory
/docs-init

This will:

1. •Detect project type (Cloudflare Workers, Next.js, generic)
2. •Create CLAUDE.md from appropriate template
3. •Create README.md if missing
4. •Optionally scaffold docs/ directory

Existing Project

# Audit all documentation
/docs-update

# Or just maintain CLAUDE.md
/docs-claude

What Gets Created

CLAUDE.md

Project-specific context for Claude Code, including:

• •Project overview and tech stack
• •Development setup commands
• •Architecture overview
• •Key file locations
• •Common tasks and workflows

Templates available:

• •CLAUDE-cloudflare.md - Cloudflare Workers + Vite + D1 projects
• •CLAUDE-nextjs.md - Next.js App Router projects
• •CLAUDE-generic.md - Any other project type

README.md

Standard README with:

• •Project name and description
• •Installation/setup instructions
• •Usage examples
• •Configuration
• •Contributing guidelines

docs/ Directory (Optional)

Scaffolded documentation structure:

• •docs/ARCHITECTURE.md - System architecture
• •docs/API.md - API documentation
• •docs/DATABASE.md - Database schema

Smart Maintenance

/docs-claude Features

The CLAUDE.md maintenance command checks:

1. •

   Tech Stack Match

   • •Does CLAUDE.md list technologies that match package.json?
   • •Are versions mentioned still accurate?
2. •

   Referenced Files

   • •Do paths mentioned in CLAUDE.md still exist?
   • •Are there new important files not mentioned?
3. •

   Section Freshness

   • •Is "Last Updated" date recent?
   • •Are there outdated patterns or commands?
4. •

   Critical Rules

   • •For detected tech stack, are important rules present?
   • •E.g., Cloudflare project should mention wrangler.jsonc patterns

/docs-update Features

Full documentation audit including:

1. •

   Date Freshness

   • •Compare doc dates against git history
   • •Flag docs not updated in >30 days
2. •

   Version References

   • •Check npm package versions mentioned
   • •Suggest updates for outdated versions
3. •

   Broken Links

   • •Verify internal markdown links
   • •Check that referenced files exist
4. •

   Redundancy

   • •Identify duplicate content across files
   • •Suggest consolidation
5. •

   Orphaned Files

   • •Find docs not referenced anywhere
   • •Suggest archiving or deletion

Project Type Detection

The skill auto-detects project type by looking for:

Additional indicators influence template content:

• •package.json dependencies (React, Vite, etc.)
• •Database config files (drizzle.config.ts, prisma/schema.prisma)
• •Auth config (clerk, better-auth)

Integration with Other Skills

• •project-workflow: Use /docs-init after /plan-project to add documentation
• •project-planning: Generated IMPLEMENTATION_PHASES.md referenced in CLAUDE.md
• •cloudflare-worker-base: Cloudflare template includes Workers-specific patterns

Best Practices

When to Run Each Command

CLAUDE.md Guidelines

1. •Keep it current - Update "Last Updated" when making changes
2. •Focus on project-specific - Don't duplicate generic tech docs
3. •Include common tasks - Commands you run frequently
4. •Reference, don't duplicate - Link to docs/ for detailed content

Templates

Templates are located in templates/ within this skill:

templates/
├── CLAUDE-cloudflare.md    # Cloudflare Workers projects
├── CLAUDE-nextjs.md        # Next.js projects
├── CLAUDE-generic.md       # Generic projects
└── README-template.md      # Standard README

Templates use placeholders:

• •{{PROJECT_NAME}} - Detected from package.json or folder name
• •{{DATE}} - Current date
• •{{TECH_STACK}} - Detected technologies