03-shadow-areas — Claude Code skill: find gaps in documents
03-shadow-areas — a skill that scans written artifacts (ideas, user stories, PRDs, specs) and produces a structured report of blind spots—what the author has not addressed. Runs on Claude Code, Cursor, Codex, GitHub Copilot, and OpenCode.
MIT ★ 571 updated 2026-10-29
/plugin marketplace add ai-driven-dev/framework
/plugin install aidd-refine@aidd-frameworkWhat 03-shadow-areas does
03-shadow-areas analyzes text artifacts to surface gaps: missing requirements, unclear sections, insufficient detail. Each gap gets a category from a fixed taxonomy, a severity level (blocker, major, minor), and a direct question the author can act on immediately. It works as an analytical scanner, not as dialogue—one pass through the document and a ready report.
The skill has three actions: detect parses the artifact and extracts gaps, render-report formats them into markdown grouped by category and sorted by severity, and diff compares the current result against a prior report to show which gaps closed, which remain open, and which are newly found. Categories and severity rules live in references/locked-sets.json.
Use it when you need to find what is missing in a document before moving forward. This is not for interactive Q&A or code review—it targets written work.
What it helps with
- surface gaps in a technical specification before development starts
- verify a user story has enough detail
- spot missing requirements in a PRD
- track which gaps you closed in a revised document
- flag the most critical omissions in a project idea
Example prompts for the agent
- Scan
spec.mdfor gaps and show a report grouped by category - Find blind spots in this user story text: [paste text]
- Compare the new PRD version against the prior report in
reports/prd-v1.md
How to install 03-shadow-areas
1Plugin marketplace
/plugin marketplace add ai-driven-dev/framework/plugin install aidd-refine@aidd-frameworkThis installs the whole aidd-refine plugin with all its skills
2Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a claude-code3Manually: put the files in place
~/.claude/skills/03-shadow-areas/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/03-shadow-areas/
1Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a codex2Manually: put the files in place
.agents/skills/03-shadow-areas/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a cursor2Manually: put the files in place
.cursor/skills/03-shadow-areas/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ai-driven-dev/framework plugins/aidd-refine/skills/03-shadow-areas2Manually: put the files in place
.github/skills/03-shadow-areas/SKILL.md1Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a gemini-cli2Platform CLI
gemini skills install https://github.com/ai-driven-dev/framework --path plugins/aidd-refine/skills/03-shadow-areasManually: put the files in place
.devin/skills/03-shadow-areas/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about 03-shadow-areas
How do I install 03-shadow-areas in Claude Code?
Run /plugin marketplace add ai-driven-dev/framework, then /plugin install aidd-refine@aidd-framework and npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a claude-code. The skill file goes to ~/.claude/skills/03-shadow-areas/SKILL.md.
What does 03-shadow-areas do?
It scans a document and produces a structured report of gaps: each omission gets a category, severity level, and a concrete question so the author knows what to clarify or fill in.
How do I install it in other IDEs?
For Cursor: npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a cursor. For Codex: npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a codex. For GitHub Copilot: gh skill install ai-driven-dev/framework 03-shadow-areas. For OpenCode: npx skills add ai-driven-dev/framework --skill 03-shadow-areas -a opencode.
Source text
SKILL.md · MIT
--- name: 03-shadow-areas description: Scan a markdown artifact (idea, stories, PRD, spec) for blind spots into a shadow report grouped by category and severity. Use to find gaps or what is missing in a written artifact. Not for interactive Q&A or code review. argument-hint: file | text --- # Shadow Areas Analytically scans a written artifact for gaps the author has not addressed. Unlike iterative Q&A clarification, this skill reads the existing material and emits a structured report: each gap carries a category from a locked 7-category taxonomy, a 3-tier severity, and a direct-question probe the author can act on immediately. ## Actions | # | Action | Role | Input | | --- | ---------------- | ------------------------------------------------------------------------ | ---------------------------------------- | | 01 | `detect` | Parse input, extract gaps, classify category and severity, emit probes | file path or inline text | | 02 | `render-report` | Render markdown grouped by category and sorted by severity, write report | gap list from detect | | 03 | `diff` | Load prior report, classify gaps as closed / still-open / newly-introduced | gap list from detect + prior report path | Dispatch by context: with no prior report run `detect` then `render-report`; with one, run `detect` then `diff`. Before running an action, read its file in `actions/`, not only the table or assets. ## Transversal rules - Never modify the source artifact. - Every gap carries all three: a category, a severity, and a probe question. - Every probe is a direct question ending with `?`. - Categories and severities come from the locked sets in `references/locked-sets.json`. - When zero blockers and zero majors remain, stamp the report `status: clean`. - On re-runs, gaps are matched by category and snippet, never by question wording, so rephrasing a question never creates a spurious "newly introduced" gap. ## References - `references/categories.md`: locked 7-category taxonomy with definition and example per category. - `references/severity-rubric.md`: blocker / major / minor decision rules and examples. - `references/probe-style.md`: direct-question form rules. - `references/locked-sets.json`: machine-readable sets reused by the validator. ## Assets - `assets/report-template.md`: report skeleton with header, per-category sections, and `status: clean` block.
© AI-Driven Dev · MIT · ai-driven-dev/framework