Document Service
Turns a codebase into CODEBASE_ANALYSIS.md with file:line citations and Mermaid diagrams
Test report
- Verdict
- Tested · Works
- Score
- Tested
- Jul 21, 2026
- Environment
- Claude Code 2.x (agent harness)
- Upstream re-checked
- Aug 10, 2026 · 8594801
Built a 7-file sample AWS service (FastAPI + CDK stack + 2 unit tests + a README that lies about the architecture) in a scratch dir, then wrote two docs for it: BASELINE.md without the skill body and CODEBASE_ANALYSIS.md following SKILL.md and references/technical-doc-template.md strictly. The baseline was a clean but flat description with zero citations that reported "tests cover two cases, run with pytest"; the skill run — because it demands verifying quantitative claims by execution — made me actually run score_receipt, which showed test_risky_merchant_bumps_score asserts >0.5 while the function returns 0.4394, i.e. the suite is red. Its mandatory Discrepancies and Failure Modes tables also surfaced four false README claims (Lambda/Aurora/Cognito/nightly export vs Fargate/DynamoDB/static bearer token/dead code), API_TOKEN never wired into the CDK environment block so the deployed service would authenticate on the literal "dev-token", ContainerImage.fromAsset("../") with no Dockerfile in the repo, and an unauthenticated GET /receipts route — none of which appear in the baseline. Install verified in a throwaway HOME (git clone + cp put SKILL.md at ~/.claude/skills/document-service/SKILL.md); all 8 referenced reference/*.md files returned HTTP 200; no curl|sh, base64 blobs, secret exfiltration or injection text found. Not exercised: the draw.io delegation to aws-architecture-diagram (not installed, Mermaid fallback used as documented), drawio PNG export (not on PATH), the AWS MCP servers, and the .codebase-documentor-progress.md resumability path for large repos.
Scored on four weighted criteria — install, triggering, output vs. baseline, docs. How scoring works
- Installs cleanly 5/5
- Triggers reliably 5/5
- Output vs. baseline 9/10
- Docs & honesty 4/5
What Document Service does
Analyzes an existing codebase and writes a single CODEBASE_ANALYSIS.md covering architecture, request lifecycle, data models, deployment, configuration, security, failure modes and timeout chains, with a clickable file:line citation behind every claim and inline Mermaid diagrams. It runs an outline-driven pipeline (file tree, project detection, per-section deep reads, discrepancy pass) and adds AWS-specific handling for CDK, CloudFormation and Terraform. Triggers on requests like "document this service", "analyze this codebase", "I inherited this code", or "this codebase has no docs"; it is scoped out of code reviews and single-function explanations.
How to install Document Service
git clone --depth 1 https://github.com/awslabs/agent-plugins.git /tmp/document-service-src
mkdir -p ~/.claude/skills
cp -R /tmp/document-service-src/plugins/codebase-documentor-for-aws/skills/document-service ~/.claude/skills/document-service
# Installs SKILL.md + references/ (8 files: template, citation format, discovery/framework/exclusion patterns, error scenarios, recursive analysis, business context).
# No API keys or runtime deps required for the core workflow; drawio CLI is optional (PNG export is skipped if absent).
# Optional: the skill tries the `aws-architecture-diagram` skill (deploy-on-aws plugin) for draw.io output and falls back to inline Mermaid when it is not installed.
# Optional MCP enrichment (awsknowledge HTTP + awsiac via uvx) ships with the parent plugin, not with this skill dir. To get those too, install the whole plugin instead:
# /plugin install codebase-documentor-for-aws@agent-plugins-for-aws
# Usage: "document this service" or "analyze <dir> and generate technical docs" -> writes CODEBASE_ANALYSIS.md into the target directory.
Skills live in ~/.claude/skills/ (global) or .claude/skills/
(per-project). Restart Claude Code after installing.
Commands — how to trigger Document Service
-
/document-serviceTurns a codebase into CODEBASE_ANALYSIS.md with file:line citations and Mermaid diagrams
It also activates on plain-language prompts like these:
-
Document this service's architecture from the code -
Generate technical docs for this inherited codebase -
Visualize the CDK architecture with source citations
Frequently asked questions
- Is the Document Service skill free?
- Yes. The skill itself is free from awslabs/agent-plugins. SkillProof publishes the install command and an independent test verdict at no cost.
- Does Document Service work with Claude Code?
- We tested it with Claude Code 2.x (agent harness) on Jul 21, 2026. Verdict: Tested · Works. Built a 7-file sample AWS service (FastAPI + CDK stack + 2 unit tests + a README that lies about the architecture) in a scratch dir, then wrote two docs for it: BASELINE.md without the skill body and CODEBASE_ANALYSIS.md following SKILL.md and references/technical-doc-template.md strictly. The baseline was a clean but flat description with zero citations that reported "tests cover two cases, run with pytest"; the skill run — because it demands verifying quantitative claims by execution — made me actually run score_receipt, which showed test_risky_merchant_bumps_score asserts >0.5 while the function returns 0.4394, i.e. the suite is red. Its mandatory Discrepancies and Failure Modes tables also surfaced four false README claims (Lambda/Aurora/Cognito/nightly export vs Fargate/DynamoDB/static bearer token/dead code), API_TOKEN never wired into the CDK environment block so the deployed service would authenticate on the literal "dev-token", ContainerImage.fromAsset("../") with no Dockerfile in the repo, and an unauthenticated GET /receipts route — none of which appear in the baseline. Install verified in a throwaway HOME (git clone + cp put SKILL.md at ~/.claude/skills/document-service/SKILL.md); all 8 referenced reference/*.md files returned HTTP 200; no curl|sh, base64 blobs, secret exfiltration or injection text found. Not exercised: the draw.io delegation to aws-architecture-diagram (not installed, Mermaid fallback used as documented), drawio PNG export (not on PATH), the AWS MCP servers, and the .codebase-documentor-progress.md resumability path for large repos.
- What is the Document Service SkillProof Score?
- 9.2/10 — installs cleanly 5/5, triggers reliably 5/5, output vs. baseline 9/10, docs & honesty 4/5.
- How do I install Document Service?
- Copy the install command from this page, run it in your terminal, and restart Claude Code. Skills live in ~/.claude/skills/ (global) or .claude/skills/ inside a project.
- Can I use Document Service with Cursor, Copilot, Gemini CLI, Codex or other AI tools?
- The SKILL.md format is native to Claude (Claude Code, Desktop, claude.ai). The instructions inside adapt to other assistants: Cursor rules, GitHub Copilot instructions, Windsurf rules, Custom GPTs, AGENTS.md for OpenAI Codex, and GEMINI.md for Google Gemini CLI — our conversion guides cover each, and the free converter on the tools page does the wrapping for you.