Agent skill
project-encyclopedia
<ONBOARD> Use on first session in a project, or when user asks for codebase overview. Creates persistent glossary, architecture maps, and decision records to solve agent amnesia.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/project-encyclopedia-axiomantic-spellbook-2
SKILL.md
Project Encyclopedia
Invariant Principles
-
Overview Only: Encyclopedias contain key abstractions, not implementation details. If it could go stale within a sprint, it doesn't belong.
-
Offer, Don't Force: Always ask before creating. "Would you like me to create an encyclopedia?" Never auto-generate.
-
Reference, Don't Duplicate: If README/CLAUDE.md/configs already specify something, reference the location. Never copy.
-
Staleness Detection: Check mtime. Encyclopedias older than 30 days get refresh offers, not silent reads.
-
Context Budget: Target 500-1000 lines. An encyclopedia that doesn't fit in context defeats its purpose.
Inputs
| Input | Required | Description |
|---|---|---|
project_root |
Yes | Path to project being documented |
existing_encyclopedia |
No | Path if encyclopedia already exists |
refresh_request |
No | User explicitly requesting update |
Outputs
| Output | Type | Description |
|---|---|---|
encyclopedia |
File | ~/.local/spellbook/docs/<project-encoded>/encyclopedia.md |
staleness_warning |
Inline | If existing encyclopedia > 30 days old |
Session Integration
Add to CLAUDE.spellbook.md under Session Start:
## Encyclopedia Check
BEFORE first substantive work in a project:
1. Compute project path: `~/.local/spellbook/docs/<project-encoded>/encyclopedia.md`
2. Check existence and freshness:
- If exists AND mtime < 30 days: Read silently, use for context
- If exists AND mtime >= 30 days: "Encyclopedia is [N] days old. Refresh?"
- If not exists: "I don't have an encyclopedia for this project. Create one?"
3. User declines: Proceed without. Do not ask again this session.
4. User accepts: Invoke `project-encyclopedia` skill
Workflow
Phase 1: Discovery
Gather via exploration:
- Project type (language, framework, monorepo?)
- Entry points (main files, CLI commands, API routes)
- Key directories and their purposes
- Test configuration and commands
- Build/run commands
Phases 2-5: Build Content
Dispatch subagent with the encyclopedia-build command.
Subagent builds: Glossary (Phase 2), Architecture Skeleton (Phase 3), Decision Log (Phase 4), Entry Points & Testing (Phase 5).
Phase 6: Validate & Write
Dispatch subagent with the encyclopedia-validate command.
Subagent assembles all sections, validates against quality checklist, and writes to output path.
Refresh Workflow
When updating existing encyclopedia:
- Read current version
- Scan for major changes:
- New entry points
- Renamed/removed components
- New glossary terms in recent commits
- Present diff of proposed changes
- User approves: Apply updates, reset mtime
- User declines: Keep existing
Template
# Project Encyclopedia: [Name]
> Last updated: YYYY-MM-DD | Created by: [model]
> Purpose: Cross-session context for AI assistants
## Glossary
| Term | Definition | Location |
|------|------------|----------|
## Architecture
```mermaid
graph TD
A[Component] --> B[Component]
Key boundaries:
- (to be filled)
Decisions
| Decision | Alternatives | Rationale | Date |
|---|
Entry Points
| Entry | Path | Purpose |
|---|
Testing
- Command:
- Framework:
- Key patterns:
See Also
- README.md for setup instructions
- CLAUDE.md for development conventions
## Anti-Patterns
<FORBIDDEN>
- Auto-creating without asking
- Including implementation details that change frequently
- Duplicating content from existing docs
- Diagrams with more than 7 nodes
- Encyclopedias exceeding 1000 lines
- Skipping staleness check on existing encyclopedias
- Regenerating from scratch instead of surgical refresh
</FORBIDDEN>
## Self-Check
Before completing encyclopedia work:
- [ ] User explicitly consented to creation/refresh
- [ ] Total content < 1000 lines
- [ ] No duplication of existing documentation
- [ ] Architecture diagram <= 7 nodes
- [ ] Glossary contains only project-specific terms
- [ ] Decisions explain rationale, not just facts
- [ ] File written to `~/.local/spellbook/docs/<project>/encyclopedia.md`
- [ ] Mtime reflects current date
If ANY unchecked: Revise before completing.
<reflection>
After each phase, verify: outputs produced match template sections, no duplication of existing docs, content stays within context budget, staleness metadata is current.
</reflection>
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?