Codebase Teach
Deep-read the repo by bounded context and write ai-context/features docs plus a teach-report for agent onboarding coverage.
Overview
codebase-teach is an agent skill most often used in Build (also Validate scope, Operate iterate) that extracts bounded-context domain knowledge into ai-context/features files and a teach-report.
Install
npx skills add https://github.com/fearovex/claude-config --skill codebase-teachWhat is this skill?
- Procedural workflow with Step 0 load of stack, architecture, and conventions from ai-context
- Writes one ai-context/features/<context>.md per bounded context from source reads
- Produces teach-report.md with documentation coverage metrics
- Manual invocation only—must not run without explicit user trigger
- Complements memory-init scaffolding and memory-update session notes
- Step 0 loads three ai-context files: stack, architecture, conventions
- Outputs teach-report.md with documentation coverage metrics
Adoption & trust: 1 installs on skills.sh; 1 GitHub stars; 2/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
Your agent has stack and architecture notes but no per-feature domain docs grounded in the actual source tree.
Who is it for?
Solo builders adopting ai-context who want feature docs generated from code after memory-init stubs exist.
Skip if: Greenfield repos with almost no code to read, or teams that forbid manual-only doc generation triggers.
When should I use this skill?
/codebase-teach, teach codebase, extract domain knowledge, update feature docs, or analyze bounded contexts—manual user request only.
What do I get? / Deliverables
You get ai-context/features/<context>.md artifacts and teach-report.md coverage metrics ready for memory-update and day-to-day agent work.
- ai-context/features/<context>.md per bounded context
- teach-report.md with coverage metrics
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Structured domain docs are created while you are still building and teaching agents how the product actually works. The docs subphase is the primary shelf because outputs land in ai-context/features and teach-report.md.
Where it fits
Map bounded contexts from an existing monolith before committing to a MVP cut line.
Run /codebase-teach after memory-init so each feature folder has code-backed rules.
Refresh feature docs post-refactor and compare coverage deltas in teach-report.md.
How it compares
Deep-read documentation workflow—not a one-shot README generator or passive session logger.
Common Questions / FAQ
Who is codebase-teach for?
Indie developers and agent-first teams who maintain ai-context and need feature-level docs derived from bounded contexts in source.
When should I use codebase-teach?
During Build docs after scaffolding ai-context, during Validate scope when clarifying domains before a big build, or during Operate iterate after large refactors—always with an explicit user trigger.
Is codebase-teach safe to install?
It instructs agents to read and write project files under ai-context; review the Security Audits panel on this page and restrict repo write access as you would for any doc workflow.
SKILL.md
READMESKILL.md - Codebase Teach
# codebase-teach > Analyzes bounded contexts from the project's source tree, extracts domain knowledge per context, writes `ai-context/features/<context>.md` files, and produces `teach-report.md` with coverage metrics. **Triggers**: `/codebase-teach`, teach codebase, extract domain knowledge, update feature docs, analyze bounded contexts --- ## Purpose `codebase-teach` fills the `ai-context/features/` layer with structured domain knowledge derived from reading source code. It is the deep-read complement to `memory-update` (which records session decisions) and `memory-init` (which scaffolds empty stubs). It MUST only be invoked manually by the user. --- ## Process ### Step 0 — Load project context (non-blocking) This step is **non-blocking**: any failure (missing file, unreadable file) MUST produce at most an INFO-level note. This step MUST NOT produce `status: blocked` or `status: failed`. 1. Read `ai-context/stack.md` — tech stack, versions, key tools. 2. Read `ai-context/architecture.md` — architectural decisions and rationale. 3. Read `ai-context/conventions.md` — naming patterns, code conventions. 4. Read the project's `CLAUDE.md` (at project root) and extract the `## Skills Registry` section. For each file: - If absent: log `INFO: [filename] not found — proceeding without it.` - If present: extract `Last updated:` or `Last analyzed:` date. If date is older than 30 days: log `NOTE: [filename] last updated [date] — context may be stale. Consider running /memory-update or /project-analyze.` Also read project config file (`config.yaml` at project root) if it exists, and extract `teach_max_files_per_context` if present: - If present: `max_files = teach_max_files_per_context` - If absent: `max_files = 10` (default) Log: `"File cap per context: [max_files] (source: config.yaml)"` or `"File cap per context: 10 (default)"` --- ### Step 1 — Scan bounded contexts Identify bounded context candidates by scanning the project directory tree at depth ≤ 2 under these root directories (in order): 1. `src/` — subdirectories at depth 1 (e.g., `src/auth/`, `src/payments/`) 2. `app/` — subdirectories at depth 1 3. `features/` — subdirectories at depth 1 4. `domain/` — subdirectories at depth 1 5. `ai-context/features/` — existing feature file names (each file stem is treated as a context name) **Exclusion rules** — skip directories named: `shared`, `utils`, `common`, `lib`, `types`, `hooks`, `components`, `__tests__`, `test`, `tests`, `node_modules`, `.git` **Cross-reference with existing feature files:** Read the `ai-context/features/` directory (if it exists) and list all `.md` files, excluding files whose names begin with `_` (e.g., `_template.md`). For each detected context candidate, build a record: ``` { slug: kebab-case of directory name, dir_path, existing_feature_file: bool } ``` **Slug convention:** lowercase the directory name; replace spaces and underscores with hyphens. Example: `UserProfile` → `user-profile`, `auth_service` → `auth-service`. **If no context candidates are found:** - Log: `"No bounded context directories detected."` - Write `teach-report.md` with a Summary noting "No bounded context directories detected" and a recommendation to run `/memory-init` first. - Stop here. **If `ai-context/features/` does not exist:** - Log: `"INFO: ai-context/features/ not found — feature files will be created if possible."` - Note in `teach-report.md`: "ai-context/features/ was absent at run time. Recommend running /memory-init to scaffold the directory before re-running /codebase-teach." - Continue processing (the skill creates the directory and files as needed)