document-service

Name: document-service
Author: awslabs

843stars132forks

How to install document-service?

awslabs/agent-plugins/document-service

$npx -y skills add awslabs/agent-plugins --skill document-service

Installs into the current project.

Summary

This skill should be used when the user asks to \"analyze this codebase\", \"document this service\", \"generate technical docs\", \"I inherited this code\", \"help me understand this system\", \"create docs for this project\", \"what does this system look like\", \"onboard me to

Files · 1

View on GitHub

SKILL.md

1	# Document Service
2
3	Analyze codebases to produce structured technical documentation and architecture diagrams with source-of-truth citations. Every finding links back to the exact file and line it was derived from. Optimized for AWS workloads but works with any codebase.
4
5	## Core Principles
6
7	- Explain WHY, not just WHAT. The reader inherited this codebase and has zero context. Listing components is not enough — explain why the architecture is shaped this way. Search for code comments, TODOs, and commit messages that reveal design rationale. When no rationale exists, mark it `[RATIONALE UNKNOWN]`.
8	- Trace end-to-end flows. For every API endpoint or message handler, trace the complete request path from entry to response. Note every intermediate step, transformation, timeout, and failure point. This is the "if it breaks at 3am, where do I look?" analysis.
9	- Deep-dive complex logic. Identify the most complex or domain-specific code paths (ML pipelines, business rule engines, state machines, custom algorithms). Document HOW they work at the implementation level — the algorithm, key parameters, edge cases, and where production bugs will occur. Surface-level summaries of complex code provide no value over a naive AI prompt.
10	- Surface implicit knowledge. Look for hardcoded values, magic numbers, environment-dependent behavior, and undocumented assumptions. These are the tribal knowledge items that disappear when teams leave.
11	- Every claim must be traceable. Include `file:line` citations for every finding. See [citation-format.md](references/citation-format.md). Verify citations precisely — re-read the cited file and confirm the line number is within ±3 lines. Anchor with function/variable names.
12	- Code is the source of truth. Document what actually exists in code, not what READMEs or wikis claim. Flag every discrepancy between documentation and reality.
13	- Mark unknowns and risks explicitly. Use `[UNKNOWN]` for items not inferable from code, `[RISK]` for unhandled failure modes, `[INFERRED]` for educated guesses, `[RATIONALE UNKNOWN]` for unexplained architecture choices. Omitting markers undermines trust.
14	- Verify quantitative claims. List directory entries programmatically and use exact counts.
15
16	## Workflow
17
18	The workflow runs autonomously from Step 2 onward. Step 1 is the only interactive step.
19
20	### Step 1: Gather Context
21
22	Gather from the user:
23
24	- Target directory or service to analyze
25	- Any existing documentation, design docs, or business context (accept "nothing" — this skill is designed for undocumented codebases)
26
27	If existing docs are provided, read them first to establish baseline context. If the target directory and context are already known (e.g., provided via automation or a pre-configured prompt), skip the interactive step and proceed directly to Step 2.
28
29	Check whether `CODEBASE_ANALYSIS.md` already exists at the output path. If so, ask the user: "Overwrite or write to a different filename?" Resolve this before proceeding — the rest of the workflow runs autonomously.
30
31	### Step 2: Build File Tree and Detect Project Type
32
33	1. List all files recursively in the target directory
34	2. Apply exclusion patterns from [exclusion-patterns.md](references/exclusion-patterns.md). Also respect `.gitignore`.
35	3. Detect project type and framework from characteristic files. See [discovery-patterns.md](references/discovery-patterns.md).
36	4. Identify entry points based on detected project type. See [discovery-patterns.md](references/discovery-patterns.md).
37	5. Read the README, CLAUDE.md, or AGENTS.md if present — these contain project context.
38	6. Check git branch names (`git branch -a`) for strategic context (e.g., a `dev/rust` branch signals a language migration in progress). Note active branches in the Architecture Overview.
39
40	### Step 3: Generate Documentation Outline
41
42	Produce a hierarchical outline mapping each documentation section to specific source files:
43
44	```markdown
45	## Documentation Outline
46
47	1. Architecture Overview → [entry points, IaC stack files] — explain WHY, not just WHAT
48	2. [Module A: detected name] → [source files for module A]
49	3. [Module B: detected name] → [source files for module B]
50	4. Shared Utilities → [shared/common source fil

People who liked this also viewed

6 picks

Type

document-service

843stars132forks

View on GitHub

How to install document-service?

awslabs/agent-plugins/document-service

$npx -y skills add awslabs/agent-plugins --skill document-service

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Document Service
2
3	Analyze codebases to produce structured technical documentation and architecture diagrams with source-of-truth citations. Every finding links back to the exact file and line it was derived from. Optimized for AWS workloads but works with any codebase.
4
5	## Core Principles
6
7	- Explain WHY, not just WHAT. The reader inherited this codebase and has zero context. Listing components is not enough — explain why the architecture is shaped this way. Search for code comments, TODOs, and commit messages that reveal design rationale. When no rationale exists, mark it `[RATIONALE UNKNOWN]`.
8	- Trace end-to-end flows. For every API endpoint or message handler, trace the complete request path from entry to response. Note every intermediate step, transformation, timeout, and failure point. This is the "if it breaks at 3am, where do I look?" analysis.
9	- Deep-dive complex logic. Identify the most complex or domain-specific code paths (ML pipelines, business rule engines, state machines, custom algorithms). Document HOW they work at the implementation level — the algorithm, key parameters, edge cases, and where production bugs will occur. Surface-level summaries of complex code provide no value over a naive AI prompt.
10	- Surface implicit knowledge. Look for hardcoded values, magic numbers, environment-dependent behavior, and undocumented assumptions. These are the tribal knowledge items that disappear when teams leave.
11	- Every claim must be traceable. Include `file:line` citations for every finding. See [citation-format.md](references/citation-format.md). Verify citations precisely — re-read the cited file and confirm the line number is within ±3 lines. Anchor with function/variable names.
12	- Code is the source of truth. Document what actually exists in code, not what READMEs or wikis claim. Flag every discrepancy between documentation and reality.
13	- Mark unknowns and risks explicitly. Use `[UNKNOWN]` for items not inferable from code, `[RISK]` for unhandled failure modes, `[INFERRED]` for educated guesses, `[RATIONALE UNKNOWN]` for unexplained architecture choices. Omitting markers undermines trust.
14	- Verify quantitative claims. List directory entries programmatically and use exact counts.
15
16	## Workflow
17
18	The workflow runs autonomously from Step 2 onward. Step 1 is the only interactive step.
19
20	### Step 1: Gather Context
21
22	Gather from the user:
23
24	- Target directory or service to analyze
25	- Any existing documentation, design docs, or business context (accept "nothing" — this skill is designed for undocumented codebases)
26
27	If existing docs are provided, read them first to establish baseline context. If the target directory and context are already known (e.g., provided via automation or a pre-configured prompt), skip the interactive step and proceed directly to Step 2.
28
29	Check whether `CODEBASE_ANALYSIS.md` already exists at the output path. If so, ask the user: "Overwrite or write to a different filename?" Resolve this before proceeding — the rest of the workflow runs autonomously.
30
31	### Step 2: Build File Tree and Detect Project Type
32
33	1. List all files recursively in the target directory
34	2. Apply exclusion patterns from [exclusion-patterns.md](references/exclusion-patterns.md). Also respect `.gitignore`.
35	3. Detect project type and framework from characteristic files. See [discovery-patterns.md](references/discovery-patterns.md).
36	4. Identify entry points based on detected project type. See [discovery-patterns.md](references/discovery-patterns.md).
37	5. Read the README, CLAUDE.md, or AGENTS.md if present — these contain project context.
38	6. Check git branch names (`git branch -a`) for strategic context (e.g., a `dev/rust` branch signals a language migration in progress). Note active branches in the Architecture Overview.
39
40	### Step 3: Generate Documentation Outline
41
42	Produce a hierarchical outline mapping each documentation section to specific source files:
43
44	```markdown
45	## Documentation Outline
46
47	1. Architecture Overview → [entry points, IaC stack files] — explain WHY, not just WHAT
48	2. [Module A: detected name] → [source files for module A]
49	3. [Module B: detected name] → [source files for module B]
50	4. Shared Utilities → [shared/common source fil

People who liked this also viewed

6 picks

Type