Agent skill

managing-docs

Expert at organizing and managing documentation structure across projects. Auto-invokes when organizing documentation files, setting up documentation frameworks, creating documentation directories, managing doc site configurations, or establishing documentation standards for a project. Provides guidance on documentation architecture and tooling.

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/c0ntr0lledcha0s/managing-docs

SKILL.md

Managing Documentation Skill

You are an expert at organizing, structuring, and managing documentation across software projects.

When This Skill Activates

This skill auto-invokes when:

  • User asks about documentation structure or organization
  • User wants to set up documentation for a project
  • User needs to configure documentation tools (Sphinx, MkDocs, etc.)
  • User asks about documentation best practices for organization
  • User wants to restructure existing documentation

Documentation Architecture Patterns

Pattern 1: Simple Project (README-Centric)

Best for: Small projects, libraries, single-purpose tools

project/
├── README.md           # Main documentation
├── CONTRIBUTING.md     # Contribution guidelines
├── CHANGELOG.md        # Version history
├── LICENSE             # License file
└── docs/
    └── api.md          # API reference (if needed)

Pattern 2: Standard Project (Docs Directory)

Best for: Medium projects, applications with multiple features

project/
├── README.md           # Overview and quick start
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
└── docs/
    ├── index.md        # Documentation home
    ├── getting-started.md
    ├── installation.md
    ├── configuration.md
    ├── usage/
    │   ├── basic.md
    │   └── advanced.md
    ├── api/
    │   ├── index.md
    │   └── [module].md
    ├── guides/
    │   └── [topic].md
    └── troubleshooting.md

Pattern 3: Large Project (Full Documentation Site)

Best for: Large projects, frameworks, platforms

project/
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
└── docs/
    ├── mkdocs.yml          # Doc site config
    ├── index.md
    ├── getting-started/
    │   ├── index.md
    │   ├── installation.md
    │   ├── quick-start.md
    │   └── first-project.md
    ├── guides/
    │   ├── index.md
    │   └── [topic]/
    │       └── index.md
    ├── reference/
    │   ├── index.md
    │   ├── api/
    │   ├── cli/
    │   └── configuration/
    ├── tutorials/
    │   └── [tutorial]/
    ├── concepts/
    │   └── [concept].md
    ├── examples/
    │   └── [example]/
    └── contributing/
        ├── index.md
        ├── development.md
        └── style-guide.md

Pattern 4: Monorepo Documentation

Best for: Monorepos with multiple packages

monorepo/
├── README.md               # Monorepo overview
├── docs/
│   ├── index.md           # Overall documentation
│   ├── architecture.md
│   └── packages.md
└── packages/
    ├── package-a/
    │   ├── README.md      # Package-specific docs
    │   └── docs/
    └── package-b/
        ├── README.md
        └── docs/

Documentation Types

1. Reference Documentation

  • API documentation
  • Configuration options
  • CLI commands
  • Data types and schemas

Characteristics:

  • Comprehensive and exhaustive
  • Organized alphabetically or by module
  • Auto-generated when possible
  • Linked from tutorials and guides

2. Conceptual Documentation

  • Architecture overviews
  • Design decisions
  • How things work internally
  • Theoretical background

Characteristics:

  • Explains the "why"
  • Provides context
  • Uses diagrams when helpful
  • Links to reference docs

3. Procedural Documentation (How-To Guides)

  • Step-by-step instructions
  • Task-oriented content
  • Specific goals in mind
  • Common workflows

Characteristics:

  • Numbered steps
  • Clear prerequisites
  • Expected outcomes
  • Troubleshooting tips

4. Tutorial Documentation

  • Learning-oriented content
  • Hands-on exercises
  • Progressive complexity
  • Complete examples

Characteristics:

  • Beginner-friendly
  • Self-contained
  • Working code included
  • Builds on previous steps

Documentation Tools Setup

MkDocs (Python Projects)

Installation:

bash
pip install mkdocs mkdocs-material

Basic mkdocs.yml:

yaml
site_name: Project Name
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - search.highlight

nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
  - Guides:
    - guides/index.md
  - API Reference:
    - reference/index.md

plugins:
  - search
  - autorefs

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - admonition
  - toc:
      permalink: true

Commands:

bash
mkdocs serve      # Local development server
mkdocs build      # Build static site
mkdocs gh-deploy  # Deploy to GitHub Pages

Docusaurus (JavaScript Projects)

Installation:

bash
npx create-docusaurus@latest docs classic

Key Configuration (docusaurus.config.js):

javascript
module.exports = {
  title: 'Project Name',
  tagline: 'Project tagline',
  url: 'https://your-domain.com',
  baseUrl: '/',
  themeConfig: {
    navbar: {
      title: 'Project',
      items: [
        { to: '/docs/intro', label: 'Docs', position: 'left' },
        { to: '/blog', label: 'Blog', position: 'left' },
      ],
    },
  },
};

Sphinx (Python API Docs)

Installation:

bash
pip install sphinx sphinx-rtd-theme
sphinx-quickstart docs

conf.py Setup:

python
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
]

html_theme = 'sphinx_rtd_theme'

# Napoleon settings for Google-style docstrings
napoleon_google_docstring = True
napoleon_numpy_docstring = False

TypeDoc (TypeScript Projects)

Installation:

bash
npm install typedoc --save-dev

typedoc.json:

json
{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "exclude": ["**/*.test.ts"],
  "excludePrivate": true,
  "includeVersion": true
}

Documentation Standards

File Naming Conventions

✓ getting-started.md      # Lowercase with hyphens
✓ api-reference.md        # Clear and descriptive
✓ installation.md         # Single word when possible

✗ GettingStarted.md       # No PascalCase
✗ getting_started.md      # No underscores
✗ GETTING-STARTED.md      # No all caps (except special files)

Special Files

README.md       # Project overview (required)
CONTRIBUTING.md # Contribution guidelines
CHANGELOG.md    # Version history
LICENSE         # License text
CODE_OF_CONDUCT.md # Community standards
SECURITY.md     # Security policy

Documentation Structure Checklist

Project Root:

  • README.md with overview and quick start
  • CONTRIBUTING.md with contribution guidelines
  • CHANGELOG.md with version history
  • LICENSE file

Documentation Directory:

  • Clear navigation structure
  • Getting started guide
  • API/reference documentation
  • Examples directory
  • Search functionality (if using doc site)

Individual Documents:

  • Clear title
  • Table of contents (for long docs)
  • Logical section organization
  • Code examples where relevant
  • Links to related content

Versioned Documentation

For projects with multiple versions:

Strategy 1: Branch-Based

docs/
├── latest/           # Symlink to current version
├── v2.0/
├── v1.5/
└── v1.0/

Strategy 2: Docusaurus Versioning

bash
npm run docusaurus docs:version 1.0

Strategy 3: ReadTheDocs Versioning

Automatic version switching based on git tags.

Migration Strategies

Migrating to Docs Directory

  1. Create docs/ directory structure
  2. Move inline docs to appropriate files
  3. Update links and references
  4. Add navigation configuration
  5. Set up doc site generator (if using)
  6. Redirect old documentation URLs

Consolidating Documentation

  1. Audit all existing documentation
  2. Identify duplicates and conflicts
  3. Create canonical versions
  4. Remove or redirect duplicates
  5. Update all internal links

Automation

GitHub Actions for Docs

yaml
name: Deploy Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

Pre-commit Hooks for Docs

yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.37.0
    hooks:
      - id: markdownlint
        args: ['--fix']

Integration

This skill works with:

  • analyzing-docs skill for assessing current documentation state
  • writing-docs skill for creating documentation content
  • docs-analyzer agent for comprehensive documentation projects

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results