docs

What this skill does

Reviews all public interfaces (CLI, REST API, MCP tools, skills, agents) and generates or updates documentation in docs/ and the README.

Steps

1. Inventory public interfaces

Scan the codebase for all public-facing surfaces:

CLI commands — read charlieverse/cli/main.py to find all registered commands/typers, then read each command file for arguments, options, and help text.

REST API endpoints — read charlieverse/server.py and find all @mcp.custom_route() decorators. Extract method, path, and any docstrings.

MCP tools — read charlieverse/server.py and find all @mcp.tool decorators. Extract tool name, parameters (from type hints), and docstrings.

Bundled skills — run charlie skill list --json and read each SKILL.md for name, description, and usage.

Bundled agents — scan prompts/tools/*.md and prompts/cli/*.md for agent definitions. Extract name, description from frontmatter.

2. Check existing docs

Read docs/ directory if it exists. Compare against the inventory to find:

• New interfaces not yet documented
• Existing docs that are stale (interface changed since doc was written)
• Docs for interfaces that no longer exist

3. Generate/update docs

Create or update these files:

docs/cli.md — Full CLI reference. For each command:

• Command and subcommands
• Arguments and options with types and defaults
• Description
• Examples

docs/api.md — REST API reference. For each endpoint:

• Method + path
• Request body / query params
• Response format
• Description

docs/mcp-tools.md — MCP tool reference. For each tool:

• Tool name
• Parameters with types
• Return format
• Description

docs/skills.md — Skills reference. For each bundled skill:

• Name and description
• Usage / argument hint
• What it does

docs/agents.md — Agent reference. For each bundled agent:

• Name and description
• What it's for
• How to use it

4. Update README

Read README.md. Update these sections (create if missing):

• Feature list (should reflect current capabilities)
• CLI quick reference (table of commands)
• Link to full docs in docs/

Don't rewrite the whole README — just update the sections that reference interfaces.

5. Commit

git add docs/ README.md
charlie-commit -m "Update documentation for public interfaces

Charlie ? <charlie@charlieverse.ai>"

Rules

• Write docs for humans, not AI. Concise, scannable, with examples.
• Use tables for parameter lists.
• Don't document internal/private interfaces.
• If an interface has no docstring, document it from the code behavior and flag it as needing a docstring.
• Keep the README lean — point to docs/ for details.