--- # workaround: anthropics/claude-code#13005
setup: |
All projects that depend on this skill should have as CLAUDE.md frontmatter:
```yaml
--- # workaround: anthropics/claude-code#13003
depends:
- skills/llm-collab
```
LLM-Collaborative Documentation
Principles and helpers for human-LLM agent swarm collaboration on long-running projects. Provides documentation patterns for coordination across agents, temporal conflict resolution, and just-in-time context loading through structured files (ADRs, devlogs), progressive-detail guides, and optional scripts.
Note: This skill focuses on documentation patterns. For task management across sessions, use the llm-subtask skill which handles ephemeral, tactical, and strategic task tracking.
Status: Locally maintained, iteratively improving. Expect rough edges.
Core Principles
1. Separation of Concerns
Problem: Mixing audiences wastes everyone's time.
Pattern: Different files for different audiences/purposes:
project/
├── README.md # Users: what it does, how to use
├── HACKING.md # Contributors: how to develop
├── CLAUDE.md # Agents: architecture, conventions
└── docs/dev/
├── adr/ # Why: decision rationale
├── devlog/ # When: session history
└── design/ # What/how: living design knowledge
2. Tiered Detail
Problem: Loading full docs when you need a summary wastes context tokens.
Pattern: Three-level information hierarchy:
- Top-level file: 1-2 sentence summary + link
- Main doc: 1-paragraph summary + link to deep dive
- Subdirectory: Full detail
Example:
CLAUDE.md: "Uses ADR format for decisions. See docs/adr/"
docs/adr/ directory: [Date-based ADRs, list with ls or grep]
references.kb/: [Categorized guides: file-types.kb/, guidelines.kb/, workflows.kb/]
3. Temporal Ordering
Problem: With 20+ sessions/day exploring ideas in parallel, codebase contains conflicting partial implementations. Which decision is current?
Pattern: Date-based naming provides temporal ordering:
- ADRs:
YYYY-MM-DD-NNN-title.md - Devlog:
YYYY-MM-DD.md(orYYYY-MM-DD-HHMM.md) - When conflicts found, newest decision wins
4. Baton-Passing
Problem: Agent swarm loses alignment between sessions.
Pattern: Devlogs capture what diffs can't: reasoning, principles, conventions.
- Decisions and their rationale (especially rejected alternatives)
- Conventions established and principles discovered
- Tradeoffs that shaped the approach
For task tracking: Use the subtask skill for managing ephemeral, tactical, and strategic tasks.
5. Living Documentation
Problem: Docs become stale and lie.
Pattern: Use directory listings as the source of truth:
docs/adr/directory contains decisions—ls -tto see chronologicallydocs/devlog/directory contains session history—directory itself is the index- Avoid maintaining separate index files that can drift
6. Design Knowledge
Problem: CLAUDE.md is too brief for deep understanding; ADRs are too granular.
Pattern: Use docs/dev/design/ for living design documentation:
- Deeper than CLAUDE.md, more distilled than ADRs
- Organized by abstraction level (goals → requirements → design → components)
- Linked via
why[]frontmatter for traceability
When to read: Orienting on architecture, before significant changes.
When to update: After architectural ADRs, when onboarding reveals gaps.
See references/how-to-document-design-knowledge.md for the full pattern.
Frontmatter Directives
CLAUDE.md files use frontmatter to give agents operational instructions. These are action triggers, not passive metadata.
requires:— Read these files before acting in this directory.depends:— Read when relevant.
Adaptation Guidelines
These are patterns, not rules. Adapt based on:
- Team size: Solo vs multiple humans changes needs
- Session frequency: 5 sessions/day vs 20 changes patterns
- Exploration style: Serial vs parallel affects conflict frequency
- Project phase: Early exploration vs maintenance
- Existing conventions: Respect what team already uses
Evolution is expected. As you use these patterns:
- Keep what works
- Drop what doesn't
- Modify to fit your needs
- Share improvements
Quick Reference
Common workflows:
- When to document what: https:references.kb/workflows.kb/when-to-document-what.md
- Session coordination: https:references.kb/workflows.kb/llm-document-consumption-patterns.md
Key file types:
- ADRs: https:references.kb/file-types.kb/ADRs.md
- Devlogs: https:references.kb/file-types.kb/devlog.md
- CLAUDE.md: https:references.kb/file-types.kb/CLAUDE.md
- Design knowledge: https:references/how-to-document-design-knowledge.md
- Browse all: https:references.kb/file-types.kb/
Common tasks:
# Orient yourself at session start
~/.claude/skills/llm-collab/bin/llm-collab-session-start
# Document a significant decision
~/.claude/skills/llm-collab/bin/llm-collab-adr "Decision title"
# Record what happened this session
~/.claude/skills/llm-collab/bin/llm-collab-devlog
# Backdate an entry (works with any date-based script)
DATE=2025-11-19 ~/.claude/skills/llm-collab/bin/llm-collab-adr "Decision title"
# Set up docs for new project
~/.claude/skills/llm-collab/bin/llm-collab-init
All scripts support --help for details.
Detailed References
Browse https:references.kb/ for categorized guides:
- file-types.kb/ - What each doc type should contain
- guidelines.kb/ - How to write effective docs
- workflows.kb/ - How to use and maintain docs
Standalone references:
- references/how-to-document-design-knowledge.md - Living design documentation pattern
Success Indicators
These patterns are working when:
- Agents orient quickly (<1 minute)
- "What's next?" has clear answer
- Multiple daily sessions stay aligned
- Conflicts resolve through temporal ordering
- Context loading feels efficient
- Both human and agents can drop in/out
Design Goals
These patterns address:
- Projects with 10-20+ agent sessions per day
- Parallel exploration creating conflicting partial implementations
- Agents needing to hand off work to each other
- User frequently asking "What's next?" or losing thread
- Context waste from loading irrelevant documentation