Agent-Skills.md

Agent Skills: Documentation & Codemap Specialist

Use this skill when documentation needs updating — after adding features, changing APIs, modifying architecture, or updating dependencies. Trigger on "update the docs", "generate codemap", "refresh the README", "document this", "update architecture docs", or when code changes make existing documentation stale. Generates codemaps from actual code, updates READMEs, architecture diagrams, and guides.

UncategorizedID: carvalab/k-skills/doc-updater

Repository

carvalab/k-skills
carvalab

Install this agent skill to your local

pnpm dlx add-skill https://github.com/carvalab/k-skills/tree/HEAD/skills/doc-updater

Skill Files

Browse the full folder contents for doc-updater.

Download Skill

Loading file tree…

skills/doc-updater/SKILL.md

Skill Metadata

Name
doc-updater
Description
Use this skill when documentation needs updating — after adding features, changing APIs, modifying architecture, or updating dependencies. Trigger on "update the docs", "generate codemap", "refresh the README", "document this", "update architecture docs", or when code changes make existing documentation stale. Generates codemaps from actual code, updates READMEs, architecture diagrams, and guides.

Documentation & Codemap Specialist

Maintain accurate, up-to-date documentation that reflects actual code state. Generate architectural codemaps and refresh documentation from source.

Related Skills:

  • kavak-documentation - Query for Kavak documentation standards, README templates, architecture docs format
  • Use kavak-platform/platform_docs_search MCP tool for Kavak-specific documentation patterns

Quick Start

Detect project type and use appropriate tools:

# TypeScript/Node.js
npx madge --image graph.svg src/

# Go
go mod graph | dot -Tsvg -o graph.svg

# Python
pydeps src/ --output graph.svg

Core Workflow

1. Analyze Repository Structure

a) Detect language/runtime (go.mod, package.json, pyproject.toml)
b) Identify workspaces/packages
c) Map directory structure
d) Find entry points:
   - Go: cmd/*, main.go
   - Node: apps/*, packages/*, src/index.*
   - Python: src/*/__main__.py, main.py
e) Detect framework patterns

2. Generate Codemaps

Create docs/CODEMAPS/ with one file per major architectural area. The specific files depend on the project — adapt to what exists:

docs/CODEMAPS/
├── INDEX.md          # Overview and navigation (always)
├── <area>.md         # One per major area (examples below)

Common areas: frontend, backend/api, database/models, integrations/external, workers/jobs, cli, shared/utils. Only create codemaps for areas that actually exist in the project.

3. Update Documentation

Files to refresh:

  • README.md - Setup instructions, architecture overview
  • docs/GUIDES/*.md - Feature guides and tutorials
  • CONTRIBUTING.md - Development workflow

4. Validate

  • Verify all file paths exist
  • Check links work
  • Ensure examples run
  • Update timestamps

Codemap Format

Each codemap follows this structure:

# [Area] Codemap

**Last Updated:** YYYY-MM-DD
**Entry Points:** list of main files

## Architecture

[ASCII diagram]

## Key Modules

| Module | Purpose | Exports | Dependencies |
| ------ | ------- | ------- | ------------ |

## Data Flow

[Description]

## External Dependencies

- package - Purpose, Version

See references/codemap-format.md for complete specification.

When to Update

ALWAYS update when:

  • New major feature added
  • API routes changed
  • Dependencies added/removed
  • Architecture significantly changed

OPTIONAL when:

  • Minor bug fixes
  • Cosmetic changes
  • Internal refactoring

References

Detailed documentation for specific tasks:

| Reference | Purpose | | -------------------------------- | ---------------------------------------- | | references/codemap-format.md | Complete codemap specification | | references/codemap-examples.md | Frontend, backend, integrations examples | | references/scripts.md | Generation scripts (ts-morph, madge) | | references/scripts-go.md | Go-specific tools and scripts | | references/maintenance.md | Schedule and quality checklist | | references/readme-template.md | README update template |

Quality Checklist

Before committing:

  • [ ] Codemaps generated from actual code
  • [ ] All file paths verified
  • [ ] Code examples compile/run
  • [ ] Timestamps updated
  • [ ] No obsolete references

Best Practices

  1. Single Source of Truth - Generate from code, don't manually write
  2. Freshness Timestamps - Always include last updated date
  3. Token Efficiency - Keep codemaps under 500 lines each
  4. Actionable - Include commands that actually work

Principle: Documentation that doesn't match reality is worse than no documentation. Generate from source of truth (the actual code).