Documentation Gap Finder

MIT License

Copyright (c) 2026 OpenAgentSkills Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Documentation Gap Finder

What this skill does

This skill directs the agent to audit a codebase or documentation directory and produce a comprehensive list of documentation gaps. It checks for missing docstrings, undocumented exports, README files that don't match the current code, stale setup instructions, and any public API surface that lacks documentation. The output is a prioritized gap list that tells you exactly what to write and in what order.

Use this when preparing for a new developer joining the team, before an open-source launch, when onboarding is taking too long, or as part of a quarterly documentation review.

How to use

Claude Code / Cline

Copy this file to .agents/skills/documentation-gap-finder/SKILL.md in your project root.

Then ask:

• *"Use the Documentation Gap Finder skill on the entire repo."*
• *"Audit the documentation for src/api/ using the Documentation Gap Finder skill."*
• *"Use the Documentation Gap Finder skill — I want to know what a new developer would struggle to find."*

Cursor

Add the instructions below to your .cursorrules or paste them into the Cursor AI pane before asking for the audit.

Codex

Provide the directory tree and key files. Ask Codex to follow the instructions below to produce the gap report.

The Prompt / Instructions for the Agent

When asked to audit documentation, follow these steps:

Step 1 — Establish scope

Determine what to audit:

• If given a specific directory, focus there
• If given the whole repo, check: root-level docs, docs/ or wiki/ folder, README.md, all public API surfaces, and configuration files
• Identify the audience: internal developers, external API consumers, end users, or all three

Step 2 — Audit each documentation type

README / Project-level docs

• Does a README.md exist at the project root?
• Does it cover: what the project does, how to set it up, how to run it locally, how to run tests, how to deploy, how to contribute?
• Are the setup instructions still accurate? Check against package.json, Dockerfile, or equivalent.
• Are any listed commands or URLs broken or outdated?

Code-level documentation

• For every exported function, class, type, and constant: is there a docstring or JSDoc comment?
• Are complex algorithms or non-obvious logic blocks explained with inline comments?
• Are there any TODO/FIXME comments that have been sitting for a long time without resolution?

API documentation

• For REST APIs: is every endpoint documented? (method, path, request body, response shape, error codes)
• For library/SDK APIs: is every public export documented with parameters, return type, and an example?
• Is there an OpenAPI/Swagger spec? If so, is it up to date?

Architecture documentation

• Is there any document explaining the high-level system design?
• Are major design decisions documented (ADRs — Architecture Decision Records)?
• Are non-obvious dependencies or integrations explained?

Operational documentation

• How is the application deployed?
• Are environment variables documented (what each one does, whether it's required)?
• Is there a runbook for common operational tasks?

Onboarding documentation

• Is there a "getting started for new developers" guide?
• Are there contribution guidelines?

Step 3 — Flag outdated content

For documentation that exists, check for staleness signals:

• Setup instructions that reference packages/tools no longer in the project
• API docs that describe endpoints that have been removed or changed
• Screenshots or examples that no longer match the current UI or output
• Version numbers or dates that suggest the doc hasn't been updated recently

Step 4 — Prioritize the gaps

Score each gap:

• Critical — Without this, a new developer cannot set up or use the project
• High — A developer can get started but will waste significant time without this
• Medium — Useful documentation that reduces friction but isn't blocking
• Low — Nice to have; minor polish

Step 5 — Format the output

## Documentation Gap Report — [Project / Directory]

### Summary
- Critical gaps: N
- High-priority gaps: N
- Medium-priority gaps: N
- Low-priority gaps: N

---

### Critical Gaps

#### 1. [Gap title]
- **Type**: [Missing / Outdated / Unclear]
- **Location**: [Where it should live, e.g., `README.md` setup section]
- **Impact**: [Who is affected and how]
- **What to write**: [Specific description of what the documentation should say]

### High-Priority Gaps
[Same format]

### Medium-Priority Gaps
[Same format]

### Low-Priority Gaps
[Same format]

---

### What's Already Well-Documented
[Briefly note what's good so the team knows what not to change]

### Recommended First 3 Actions
1. [Most important thing to write first]
2. [Second]
3. [Third]

Example

Input to Agent:

> "Use the Documentation Gap Finder skill on this repo. Here's the directory tree and the current README content: [paste tree and README]"

Output from Agent:

> ## Documentation Gap Report — MyAPI

>

> ### Summary

> - Critical gaps: 2

> - High-priority gaps: 4

> - Medium-priority gaps: 6

> - Low-priority gaps: 3

>

> ### Critical Gaps

>

> #### 1. No environment variable documentation

> - Type: Missing

> - Location: README.md or new docs/environment.md

> - Impact: New developers cannot run the project locally — they don't know what .env keys to set

> - What to write: A table with every env var, whether it's required, what it does, and an example value. Found 14 undocumented env vars in server/config.ts.

>

> #### 2. No local setup instructions in README

> - Type: Missing

> - Location: README.md

> - Impact: First thing a new developer needs; currently only shows badges

> - What to write: Step-by-step: clone, npm install, copy .env.example, npm run db:push, npm run dev

>

> ### Recommended First 3 Actions

> 1. Add a local setup section to README.md

> 2. Document all environment variables (they're blocking the most people)

> 3. Add JSDoc to the 8 exported functions in src/api/auth.ts — most heavily used file with no docs

Notes

• Focus on documentation that helps a developer who has never seen the codebase. Everything that seems "obvious" to the current team is a documentation gap for a newcomer.
• If you find outdated documentation, flag it as a gap even if documentation exists — wrong documentation is often worse than no documentation.
• Use this skill together with the README Writer skill to produce the missing documents after identifying them.