# Update Docs > Update SDK documentation by analyzing source code changes and regenerating affected doc pages. Use when new features are added, APIs change, or docs need refresh. Use when this capability is needed. - Skill: `tomevault-io/update-docs-29` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/update-docs-29` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/update-docs-29/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/update-docs-29 --- # SDK Documentation Update Skill You are updating the documentation for the copilot-sdk-clojure project. Your goal is to keep docs accurate, comprehensive, and aligned with the source code. ## Style Guide **CRITICAL**: Before writing any documentation, read the full style guide at `doc/style.md`. Key principles: 1. **Code-first** — Lead with working Clojure examples, then explain 2. **Progressive disclosure** — Simplest usage first, layer complexity 3. **Direct tone** — Imperative mood, no filler ("simply", "just", "let's") 4. **Clojure-idiomatic** — Use Clojure terminology (namespaces, vars, maps, keywords) Every doc must pass the checklist in `doc/style.md` before completion. ## Documentation Structure ``` doc/ ├── index.md # Doc hub / navigation ├── getting-started.md # Step-by-step tutorial ├── style.md # Authoring conventions ├── guides/ # Topic guides ├── reference/ │ └── API.md # Complete API reference ├── auth/ │ ├── index.md # Authentication overview │ └── byok.md # Bring Your Own Key guide ├── mcp/ │ ├── overview.md # MCP server integration │ └── debugging.md # MCP troubleshooting └── api/ # Auto-generated Codox HTML ``` ## Source Code → Documentation Mapping | Doc Area | Primary Sources | Affected Docs | |----------|----------------|---------------| | Helpers API | `src/github/copilot_sdk/helpers.clj` | `doc/reference/API.md` (Helpers section), `doc/getting-started.md` | | Client API | `src/github/copilot_sdk/client.clj` | `doc/reference/API.md` (Client section) | | Session API | `src/github/copilot_sdk/session.clj` | `doc/reference/API.md` (Session section) | | Tools | `src/github/copilot_sdk/client.clj` (`define-tool`, `result-success`) | `doc/reference/API.md` (Tools section) | | Specs | `src/github/copilot_sdk/specs.clj`, `src/github/copilot_sdk/instrument.clj` | `doc/reference/API.md` | | MCP | `src/github/copilot_sdk/util.clj` (`mcp-server->wire`), `src/github/copilot_sdk/client.clj` | `doc/mcp/overview.md`, `doc/mcp/debugging.md` | | Auth/BYOK | `src/github/copilot_sdk/client.clj` (`:provider` in `create-session`) | `doc/auth/index.md`, `doc/auth/byok.md` | | Events | `src/github/copilot_sdk/client.clj` (`event-types`, `subscribe-events!`) | `doc/reference/API.md` (Events section) | | Examples | `examples/*.clj` | `examples/README.md`, related doc pages | ## Update Workflow ### 1. Identify Scope If the user specifies a scope (e.g., "update mcp docs"), focus on that area only. If no scope is specified, scan for changes: ```bash git diff --name-only HEAD~10 -- src/ examples/ ``` Map changed files to affected docs using the source mapping table above. ### 2. Analyze Source Code For each affected area, use the `explore` agent to gather information: ``` task agent_type: explore prompt: "In /path/to/repo, find all public functions in src/github/copilot_sdk/helpers.clj. List function name, arglists, and docstring." ``` Key things to check in source: - Public function signatures (`defn`, `defmacro` — skip `defn-` private fns) - Docstrings - Spec definitions in `specs.clj` (option keys, types, defaults) - Default values and option maps - Event type constants ### 3. Generate/Update Documentation in Parallel **IMPORTANT**: When multiple doc files need updates, use parallel `general-purpose` subagents via the `task` tool. For each doc file that needs updating, launch a subagent: ``` task agent_type: general-purpose prompt: | You are updating Clojure SDK documentation. **STYLE GUIDE**: Read and follow doc/style.md strictly: - Lead with working Clojure code examples - Short paragraphs (1-3 sentences max) - Use tables for options/config keys - Use imperative mood - Show require forms in code blocks - Use ;; => for return values **YOUR TASK**: Update doc/reference/API.md — Helpers API section **RESEARCH**: Analyze src/github/copilot_sdk/helpers.clj for: - All public functions, their arglists, and docstrings - Option keys accepted (check specs.clj for spec definitions) - Return types and behavior **REQUIREMENTS**: - Update function signatures if changed - Add any new functions - Ensure code examples match current API - Use relative links for cross-references ``` ### 4. Update Examples README If examples changed, also update `examples/README.md`: - Verify all listed examples still exist as files - Update walkthroughs for changed examples - Add entries for new examples ### 5. Regenerate Codox HTML After updating source docstrings or markdown docs, regenerate the Codox API HTML: ```bash bb docs # or: clojure -X:codox ``` This regenerates `doc/api/*.html` from source docstrings. Always run this after changing docstrings in `src/` so the HTML stays in sync with the source. ### 6. Quality Gate After all updates, run validation: ```bash bb validate-docs ``` Fix any errors (broken links, unparseable code blocks) before finishing. Also verify: - [ ] Code examples use correct `require` aliases (`copilot`, `h`, `session`) - [ ] Tables have consistent formatting - [ ] Cross-references use relative paths - [ ] No filler language - [ ] `doc/index.md` links are up to date - [ ] `doc/api/` HTML is regenerated if source docstrings changed ## Common Tasks ### New Public Function Added 1. Read the function from its source file 2. Add to the appropriate section in `doc/reference/API.md` 3. Include signature, description, options table, and example 4. If it's a major feature, consider updating `doc/getting-started.md` ### New Example Added 1. Add entry to the examples table in `README.md` 2. Add detailed walkthrough to `examples/README.md` 3. Include difficulty level, concepts covered, and usage command ### New Config/Session Option 1. Read from `specs.clj` and `client.clj` 2. Add to the session options table in `doc/reference/API.md` 3. Add example usage if behavior is non-obvious ### Auth/BYOK Changes 1. Read from `client.clj` (create-session provider handling) 2. Update `doc/auth/index.md` and/or `doc/auth/byok.md` 3. Verify example provider configs still work ### MCP Changes 1. Read from `util.clj` (mcp-server->wire) and `client.clj` 2. Update `doc/mcp/overview.md` 3. Update `doc/mcp/debugging.md` if error handling changed ## Arguments $ARGUMENTS ### Usage Modes **Mode 1: Full docs refresh (default)** ``` /update-docs /update-docs all ``` Compares all source files against all docs. Updates everything out of sync. **Mode 2: Specific section** ``` /update-docs helpers /update-docs mcp /update-docs auth /update-docs getting-started ``` Only updates docs for the specified area. Valid: `helpers`, `client`, `session`, `tools`, `events`, `mcp`, `auth`, `getting-started`, `examples`. **Mode 3: Branch delta** ``` /update-docs branch ``` Compares your branch against `main`, identifies changed source files, and updates only affected docs. ### Mode Detection Parse `$ARGUMENTS` to determine mode: 1. If arguments contain `branch`: Use Mode 3 (branch delta) 2. If arguments contain a section name: Use Mode 2 (specific section) 3. If arguments are empty or `all`: Use Mode 1 (full refresh) ### Branch Delta Workflow (Mode 3) ```bash # Get changed source files vs main git diff --name-only main...HEAD -- src/ examples/ # Map to affected docs using source mapping table # Launch parallel subagents for each affected doc ``` Example: If `src/github/copilot_sdk/helpers.clj` changed, update `doc/reference/API.md` (Helpers section) and `doc/getting-started.md`. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/copilot-community-sdk) — claim your Tome and manage your conversions.