Cognitive Coverage
A coding agent skill that helps measure and close the understanding gap in any codebase, research corpus, or documentation set.
Ask AI about Cognitive Coverage
Powered by Claude Β· Grounded in docs
I know everything about Cognitive Coverage. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Cognitive Coverage
Like test coverage, but for understanding.
Cognitive Coverage is a skill for AI coding agents that generates a measurement and learning system for any project β codebases, research papers, documentation wikis, or general knowledge domains. It produces coordinated artifacts that help you track, teach, verify, and quickly open genuine system understanding.
Works with any AI coding agent that supports custom instructions, including:
- GitHub Copilot (as a Copilot skill)
- Claude Code (as a custom command or CLAUDE.md instructions)
- OpenAI Codex (as a system prompt)
- Any LLM-powered agent with file access and markdown instruction support
The Problem
Technical debt is well understood. But there's a parallel form of debt that's harder to measure: cognitive debt β the gap between what a system does and what the people responsible for it actually understand.
Generative AI has accelerated this dramatically:
When a developer writes code from scratch, even messy code, the friction means they build at least a partial mental model. When an AI generates that same code, the developer may accept it without building the same understanding. At scale, this creates an accumulation of not knowing. The code works, but the mental models are missing.
Cognitive Coverage closes that gap.
What It Produces
| Artifact | File | Purpose |
|---|---|---|
| Teaching Guide | cognitive-coverage/learning-guide.html | Interactive HTML with sections, source snippets, mental models, and quiz |
| Coverage Manifest | cognitive-coverage/cognitive-coverage.json | Machine-readable inventory tracking understanding across 3 axes |
| Coverage Dashboard | cognitive-coverage/cognitive-coverage.html | Visual status board with gap analysis and teaching guide links |
| Artifact Launcher | cognitive-coverage/cognitive-coverage-open.html | Landing page that links to all generated artifacts and opens automatically after generation |
By default, all generated outputs are placed in a cognitive-coverage/ folder in the target project. The launcher is the entry point for opening the artifact set.
Reliable Artifact Writing
The skill includes shell-safe writing guidance so agents do not stall while creating large HTML files. In particular, agents are told not to use Bash heredocs such as python - <<'PY' in PowerShell, to avoid giant one-line shell strings, and to fall back to small deterministic chunks or short temporary writer scripts when native file-write tools are unavailable.
Large Codebases and Knowledge Bases
For large projects, Cognitive Coverage switches from a single exhaustive pass to Large Corpus Mode:
- Inventory the full corpus first
- Cluster sources into areas and focused learning modules
- Prioritize critical flows, entry points, security/data boundaries, and highly referenced material
- Generate
cognitive-coverage/learning-guide.htmlas the overview map - Generate optional
learning-guides/<module-id>.htmlpages for deeper modules - Keep uncovered areas visible as explicit dashboard gaps
This keeps the first run honest and useful: high-priority understanding is taught immediately, while lower-priority areas remain tracked instead of being hidden inside an oversized guide.
Three Coverage Axes
| Axis | Codebase | Research | Documentation |
|---|---|---|---|
| Files | Source files | Papers & sources | Documents & pages |
| Concepts | Algorithms & patterns | Theories & methods | Topics & processes |
| Flows | Data flows | Argument chains | Workflows & procedures |
Each axis has three status levels (e.g., uncovered β read β understood). Status terminology adapts automatically to the domain.
Quick Start
Option 1: GitHub Copilot
# Unix / macOS / WSL
git clone https://github.com/ryannadel/cognitive-coverage.git
cd cognitive-coverage
bash install.sh
# Windows PowerShell
git clone https://github.com/ryannadel/cognitive-coverage.git
cd cognitive-coverage
.\install.ps1
This copies the skill definition to ~/.copilot/skills/cognitive-coverage/SKILL.md.
Then open any project with Copilot and say:
"Generate cognitive coverage for this project"
Option 2: Claude Code
Claude Code has native skill support. Install as a project or personal skill:
# Project skill (this project only)
mkdir -p .claude/skills/cognitive-coverage
cp skill/SKILL.md .claude/skills/cognitive-coverage/SKILL.md
# Personal skill (all your projects)
mkdir -p ~/.claude/skills/cognitive-coverage
cp skill/SKILL.md ~/.claude/skills/cognitive-coverage/SKILL.md
Then invoke with /cognitive-coverage or just ask Claude to "generate cognitive coverage" β it will auto-detect the skill from the description.
See the Claude Code skills docs for more on skill placement and configuration.
Option 3: OpenAI Codex
Codex has native skill support via the .agents/skills/ directory:
# Project skill (this repo only)
mkdir -p .agents/skills/cognitive-coverage
cp skill/SKILL.md .agents/skills/cognitive-coverage/SKILL.md
# Personal skill (all your projects)
mkdir -p ~/.agents/skills/cognitive-coverage
cp skill/SKILL.md ~/.agents/skills/cognitive-coverage/SKILL.md
Then invoke with -coverage or let Codex auto-detect it from the description. Works in Codex CLI, IDE extension, and Codex app.
See the Codex skills docs for more on skill placement and configuration.
Option 4: Any Other Agent
The skill is just a markdown file (skill/SKILL.md) that tells an AI agent how to analyze a project and generate the artifact set. If your agent can:
- Read files in a project directory
- Follow markdown instructions
- Write output files
...then it can run Cognitive Coverage. Copy skill/SKILL.md into whatever instruction mechanism your agent supports.
Manual Install
If you prefer not to clone, just copy skill/SKILL.md to the appropriate location for your agent:
| Agent | Location |
|---|---|
| GitHub Copilot | ~/.copilot/skills/cognitive-coverage/SKILL.md |
| Claude Code | .claude/skills/cognitive-coverage/SKILL.md (project) or ~/.claude/skills/cognitive-coverage/SKILL.md (personal) |
| OpenAI Codex | .agents/skills/cognitive-coverage/SKILL.md (project) or ~/.agents/skills/cognitive-coverage/SKILL.md (personal) |
| Other | Wherever your agent reads instruction files |
MCP Integration (optional)
Cognitive Coverage also ships an optional MCP stdio server for agents that can call tools during a session. The skill still works without MCP; the server only exposes an existing cognitive-coverage.json manifest.
uv --directory /path/to/cognitive-coverage/mcp run python server.py \
--manifest /path/to/your/project/cognitive-coverage.json
The server provides hierarchy-aware tools:
| Tool | Purpose |
|---|---|
list_uncovered | List files, concepts, or flows still at their first status |
list_areas | List large-corpus areas and their modules |
get_area | Return one area with modules and grouped files/concepts/flows |
next_learning_targets | Suggest priority-ordered uncovered items to learn next |
get_concept | Return a concept's description, files, quiz IDs, and status |
get_flow | Return a flow's steps, file references, quiz IDs, and status |
coverage_summary | Return the manifest summary and one-line synopsis |
find_by_file | Return concepts and flows that reference a file path |
mark_status | Update one item status and rewrite the manifest atomically |
Example host config:
{
"mcpServers": {
"cognitive-coverage": {
"command": "uv",
"args": [
"--directory",
"/path/to/cognitive-coverage/mcp",
"run",
"python",
"server.py",
"--manifest",
"/path/to/your/project/cognitive-coverage.json"
]
}
}
}
Once installed, ask your agent:
"Use
coverage_summary, thenlist_uncoveredfor concepts."
See mcp/README.md for Claude Code, Codex, and Cursor setup.
How It Works
ββββββββββββββββββββββββ
β Artifact Launcher β
β cognitive-coverage β
β /cognitive-coverage β
β -open.html β
ββββββββββββ¬ββββββββββββ
β links
βΌ
ββββββββββββββββββββββββ
β Teaching Guide βββββ quiz answers βββββ
β learning-guide.html β β
ββββββββββββ¬ββββββββββββ β
β "Learn" links βΌ
ββββββββββββ΄ββββββββββββ localStorage
β Coverage Dashboard ββββββ reads βββββββββββ
β cognitive-coverage β
β .html β
ββββββββββββ¬ββββββββββββ
β reads
ββββββββββββ΄ββββββββββββ
β Coverage Manifest β
β cognitive-coverage β
β .json β
ββββββββββββββββββββββββ
- Artifact Launcher opens automatically after generation and links to every output
- Dashboard loads the manifest and renders coverage status
- Gap report shows uncovered items with "Launch Teaching" buttons
- Clicking a button opens the teaching guide at the relevant section
- Answering quiz questions correctly writes results to localStorage
- Returning to the dashboard syncs quiz results and upgrades coverage
- You can also manually set status via buttons on each card
- Export the updated manifest as JSON anytime
See docs/HOW-IT-WORKS.md for the full deep dive.
Domains
The skill auto-detects the project domain and adapts terminology:
codebaseβ Source code projects (TypeScript, Python, Rust, Go, Java, etc.)researchβ Paper collections, literature reviews, datasetsdocumentationβ Wikis, knowledge bases, runbooks, guidesknowledgeβ General-purpose (anything else)
Examples
See the examples/ directory for sample manifests:
examples/codebase/β REST API projectexamples/research/β Transformer architecture paper reviewexamples/documentation/β Platform engineering wiki
Schema
The manifest format is defined by a JSON Schema:
schemas/cognitive-coverage.schema.json
Use it to validate manifests programmatically or in CI.
Project Structure
cognitive-coverage/
βββ README.md # This file
βββ LICENSE # MIT
βββ CONTRIBUTING.md # How to contribute
βββ install.sh # Copilot installer (Unix/macOS/WSL)
βββ install.ps1 # Copilot installer (Windows)
βββ skill/
β βββ SKILL.md # The skill instructions (works with any agent)
βββ mcp/
β βββ server.py # Optional MCP stdio server
β βββ test_server.py # MCP smoke tests
β βββ pyproject.toml # MCP server dependencies
βββ schemas/
β βββ cognitive-coverage.schema.json # JSON Schema for manifests
βββ examples/
β βββ codebase/ # TypeScript REST API example
β βββ research/ # ML paper review example
β βββ documentation/ # Platform wiki example
β βββ mcp-config-claude-code.json # Claude Code MCP config snippet
β βββ mcp-config-codex.json # Codex MCP config snippet
βββ docs/
β βββ HOW-IT-WORKS.md # Detailed system documentation
βββ .github/
βββ ISSUE_TEMPLATE/
β βββ bug_report.md
β βββ feature_request.md
βββ pull_request_template.md
Contributing
Contributions welcome! See CONTRIBUTING.md for guidelines.
Ideas for contributions:
- New domain vocabularies (legal, medical, academic)
- Improved quiz question patterns
- Dashboard visualization improvements
- Additional example manifests
- Install scripts for other agents
- Integrations with other tools
License
Built to fight cognitive debt β one concept at a time.
