Conditional Docs Setup Skill
Set up conditional documentation loading to prevent context pollution.
When to Use
- Setting up documentation for a new project
- Reducing context pollution in existing projects
- Creating just-in-time documentation loading
- Optimizing agent context usage
Core Concept
Load documentation only when conditions match the current task.
"IMPORTANT: Only read the documentation if any one of the conditions match your task."
Setup Workflow
Step 1: Inventory Documentation
List all documentation files in the project:
# Find documentation files
find . -name "*.md" -path "*/docs/*"
find . -name "README*"
find . -name "CONTRIBUTING*"
Step 2: Categorize by Purpose
Group documentation by what it helps with:
| Category | Examples |
|---|---|
| Setup | README, INSTALL, CONTRIBUTING |
| API | api-reference, endpoints, schemas |
| Architecture | design-docs, system-overview |
| Features | feature-specific guides |
| Testing | test-patterns, fixtures |
Step 3: Define Loading Conditions
For each document, identify when it's relevant:
- docs/api-reference.md
- Conditions:
- When working with API endpoints
- When adding new routes
- When modifying request/response formats
- docs/database-schema.md
- Conditions:
- When modifying database tables
- When adding new models
- When writing migrations
Step 4: Create Conditional Docs File
Create the conditional documentation manifest:
# Conditional Documentation
This helps determine what documentation to read based on
the specific changes you need to make in the codebase.
IMPORTANT: Only read documentation if conditions match your task.
---
- README.md
- Conditions:
- When first understanding the project
- When setting up the development environment
- docs/api/endpoints.md
- Conditions:
- When working with REST endpoints
- When adding new API routes
- docs/database/schema.md
- Conditions:
- When modifying database tables
- When creating migrations
- docs/testing/patterns.md
- Conditions:
- When writing new tests
- When debugging test failures
Step 5: Integrate with Commands
Add conditional docs check to planning commands:
## Relevant Documentation
Read `.claude/commands/conditional_docs.md` to check if your task
requires additional documentation. If your task matches any conditions
listed, include those documentation files.
Condition Writing Guidelines
Be Specific
# Good - Specific conditions
- When adding a new API endpoint
- When modifying user authentication
# Bad - Vague conditions
- When doing backend work
- When coding
Cover Common Scenarios
- docs/auth.md
- Conditions:
- When implementing login/logout
- When adding new permissions
- When debugging auth issues
- When integrating OAuth
- When working with sessions
Avoid Overlap
Each document should have distinct conditions:
# Good - Distinct conditions
- api-reference.md → API endpoints
- database-schema.md → Database tables
# Bad - Overlapping conditions
- api-reference.md → When doing backend work
- database-schema.md → When doing backend work
Maintenance Workflow
When Documentation is Added
- Create the new documentation file
- Add entry to conditional_docs.md
- Define appropriate loading conditions
When Documentation is Updated
- Review existing conditions
- Add/remove conditions as needed
- Update documentation content
When Documentation is Removed
- Delete the documentation file
- Remove entry from conditional_docs.md
Template: Conditional Docs File
# Conditional Documentation
This helps determine what documentation to read based on
the specific changes you need to make in the codebase.
IMPORTANT: Only read documentation if conditions match your task.
Excessive documentation loading wastes context and reduces focus.
---
## Project Setup
- README.md
- Conditions:
- When first understanding the project
- When setting up development environment
- When learning available commands
## Backend
- docs/api/reference.md
- Conditions:
- When working with API endpoints
- When adding new routes
- docs/database/schema.md
- Conditions:
- When modifying database tables
- When writing migrations
## Frontend
- docs/components/guide.md
- Conditions:
- When creating new components
- When modifying UI patterns
## Testing
- docs/testing/patterns.md
- Conditions:
- When writing tests
- When debugging test failures
Memory References
- @conditional-docs-pattern.md - Full pattern documentation
- @minimum-context-principle.md - Why this matters
- @one-agent-one-purpose.md - Context affects focus
Version History
- v1.0.0 (2025-12-26): Initial release
Last Updated
Date: 2025-12-26 Model: claude-opus-4-5-20251101
Converted and distributed by TomeVault — claim your Tome and manage your conversions.