| name | ai-context-generator |
| description | Generates .ai-context knowledge base for coding agents. Activate when: (1) setting up a new project for AI-assisted development, (2) user asks to "create project knowledge" or "setup ai-context", (3) existing .ai-context needs regeneration. Creates tiered documentation structure optimized for agent comprehension and token efficiency.
|
AI Context Generator
A reusable skill for creating project knowledge bases that help coding agents work faster and smarter.
🎯 When to Use This Skill
Activate when:
- Setting up a new project for AI-assisted development
- User requests: "create ai-context", "setup project knowledge", "generate .ai-context"
- Existing
.ai-context is outdated and needs regeneration
- After major project restructuring
Do NOT activate when:
- Project already has fresh
.ai-context (check SKILL.md date)
- User asks for unrelated documentation
- Simple code tasks with clear existing context
📋 What This Skill Generates
Creates a .ai-context/ directory with:
.ai-context/
├── SKILL.md # Entry point with activation rules
├── DYNAMICS.md # Active issues & constraints (Dynamic)
├── references/
│ ├── PROJECT-ESSENCE.md # What & why (High stability)
│ ├── ARCHITECTURE.md # Component relationships (Medium stability)
│ └── DECISIONS.md # Design decisions (Update on change)
└── meta/
├── MAINTENANCE.md # How to maintain this knowledge
├── templates/ # (Optional) Custom templates
└── scripts/ # (Optional) Maintenance scripts
Stability Tiers
| Tier | File | Update Frequency | Token Budget |
|---|
| 0 | PROJECT-ESSENCE.md | Quarterly / Major version | ~500 tokens |
| 1 | ARCHITECTURE.md | Monthly / Sprint | ~1000 tokens |
| 2 | DECISIONS.md | Per decision change | ~800 tokens |
| 3 | DYNAMICS.md | As needed (issues) | ~600 tokens |
🔧 Generation Process
Step 1: Gather Project Intelligence
Before generating, collect:
□ Read AGENTS.md (if exists) — operational rules
□ Read README.md — user-facing description
□ Read package.json — dependencies, scripts, entry points
□ Scan directory structure — identify components
□ Read docs/ or litho.docs/ — existing documentation
□ Identify key source files — main entry points
□ Note technology stack — frameworks, languages, platforms
Step 2: Extract Knowledge
For PROJECT-ESSENCE.md:
- What is this project? (one sentence)
- Why does it exist? (problem/solution)
- Who is it for? (target users)
- What does it provide? (key features)
- Core constraints? (security, compatibility)
For ARCHITECTURE.md:
- System diagram (ASCII or Mermaid)
- Component responsibilities
- Data flow between components
- Key dependencies
- Important patterns
For DECISIONS.md:
- Non-obvious design choices
- Trade-offs made
- Constraints accepted
- Decisions that might be revisited
For DYNAMICS.md:
- Current blockers
- Known workarounds
- Temporary constraints
- Recently resolved issues (brief)
Step 3: Generate Files
Use templates from templates/ directory:
- Start with
SKILL.md — entry point with activation rules
- Generate
references/PROJECT-ESSENCE.md — core identity
- Generate
references/ARCHITECTURE.md — component map
- Generate
references/DECISIONS.md — design rationale
- Generate
DYNAMICS.md — active issues
- Generate
meta/MAINTENANCE.md — upkeep guide
Step 4: Validate Quality
□ SKILL.md has clear activation triggers
□ PROJECT-ESSENCE.md readable in 2 minutes
□ ARCHITECTURE.md shows big picture (no code)
□ DECISIONS.md justified with rationale
□ DYNAMICS.md only contains current issues
□ All files dated at top
□ Total token budget < 4000 tokens
📝 Writing Principles
Do:
- ✅ Write for someone who knows nothing about the project
- ✅ Use diagrams over paragraphs
- ✅ Focus on "why" not "how"
- ✅ Keep files under 150 lines each
- ✅ Link between related sections
- ✅ Include "Last updated" dates
Don't:
- ❌ Copy-paste code snippets (link to files instead)
- ❌ Document every file/function
- ❌ Include details that change frequently
- ❌ Duplicate content across files
- ❌ Use jargon without context
🔄 Integration with AGENTS.md
AGENTS.md = "How to work" (commands, style, rules)
.ai-context = "What the project is" (architecture, decisions, issues)
Both should be read at session start. They serve different purposes and should not overlap.
📚 Template Reference
Templates are provided in templates/:
| Template | Purpose |
|---|
skill.md.tmpl | SKILL.md with placeholder prompts |
essence.md.tmpl | PROJECT-ESSENCE.md structure |
architecture.md.tmpl | ARCHITECTURE.md with diagram prompts |
decisions.md.tmpl | DECISIONS.md with ADR format |
dynamics.md.tmpl | DYNAMICS.md with status tracking |
maintenance.md.tmpl | MAINTENANCE.md guide |
🛠️ Automation Scripts
Scripts in scripts/ can help with:
| Script | Purpose |
|---|
generate.ts | Interactive generation from templates |
check-drift.ts | Compare documented vs actual structure |
audit-dynamics.ts | Flag stale issues (>30 days) |
💡 Example Usage
User: "Setup ai-context for my project"
Agent:
- Activate this skill
- Read AGENTS.md, README.md, package.json
- Scan directory structure
- Generate each file using templates
- Ask clarifying questions if needed:
- "What's the main problem this project solves?"
- "Any non-obvious design decisions I should know about?"
- "Current blockers or workarounds?"
⚠️ Important Notes
- Generated knowledge is a starting point, not final truth
- Agent should verify against actual code during first session
- User should review generated content for accuracy
- Schedule regular audits (monthly recommended)
📖 References
This skill creates knowledge bases optimized for AI agents. For questions or improvements, see MAINTENANCE.md.
