1# Skills Mapping: Digital Brain
2 
3This document maps how [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) principles are applied in the Digital Brain implementation.
4 
5---
6 
7## Context Engineering Principles Applied
8 
9### 1. Context Fundamentals
10 
11| Concept | Source Skill | Digital Brain Application |
12|---------|--------------|---------------------------|
13| **Attention Budget** | context-fundamentals | Module separation ensures only relevant content loads. Voice file (~200 lines) loads for content tasks; contacts file loads for network tasks. Never load everything. |
14| **Progressive Disclosure** | context-fundamentals | Three-level architecture: L1 (SKILL.md metadata), L2 (module instructions), L3 (data files). Each level loads only when needed. |
15| **High-Signal Tokens** | context-fundamentals | JSONL schemas include only essential fields. Voice profiles focus on patterns, not exhaustive rules. |
16 
17**Design Decision**:
18> "Find the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome."
19 
20Applied by keeping `voice.md` focused on distinctive patterns (signature phrases, anti-patterns) rather than generic writing advice Claude already knows.
21 
22---
23 
24### 2. Memory Systems
25 
26| Concept | Source Skill | Digital Brain Application |
27|---------|--------------|---------------------------|
28| **Append-Only Logs** | memory-systems | All `.jsonl` files are append-only. Status changes via `"status": "archived"`, never deletion. Preserves full history. |
29| **Structured Recall** | memory-systems | Consistent schemas across files enable pattern matching. `contact_id` links `contacts.jsonl` to `interactions.jsonl`. |
30| **Episodic Memory** | memory-systems | `interactions.jsonl` captures discrete events. `posts.jsonl` logs content with performance metrics for retrospective analysis. |
31| **Semantic Memory** | memory-systems | `knowledge/bookmarks.jsonl` with categories and tags enables topic-based retrieval. |
32 
33**Design Decision**:
34> "Agents maintain persistent memory files to track progress across complex sequences."
35 
36Applied in `operations/metrics.jsonl` where weekly snapshots accumulate, enabling trend analysis without recomputing from raw data.
37 
38---
39 
40### 3. Tool Design
41 
42| Concept | Source Skill | Digital Brain Application |
43|---------|--------------|---------------------------|
44| **Self-Contained Tools** | tool-design | Scripts in `agents/scripts/` are standalone Python files. Each does one thing: `weekly_review.py` generates reviews, `stale_contacts.py` finds neglected relationships. |
45| **Clear Input/Output** | tool-design | Scripts read from known paths, output structured text to stdout. No side effects unless explicitly documented. |
46| **Token Efficiency** | tool-design | Scripts process data and return summaries. Agent receives results, not raw data processing logic. |
47 
48**Design Decision**:
49> "Tools should be self-contained, unambiguous, and promote token efficiency."
50 
51Applied by having `content_ideas.py` analyze bookmarks and past posts internally, returning only actionable suggestions rather than raw analysis.
52 
53---
54 
55### 4. Context Optimization
56 
57| Concept | Source Skill | Digital Brain Application |
58|---------|--------------|---------------------------|
59| **Module Separation** | context-optimization | Six distinct modules (`identity/`, `content/`, `knowledge/`, `network/`, `operations/`, `agents/`) prevent cross-contamination. Content creation never needs to load network data. |
60| **Just-In-Time Loading** | context-optimization | Module instruction files (`IDENTITY.md`, `CONTENT.md`, etc.) load only when that module is relevant. |
61| **Reference Depth** | context-optimization | Main SKILL.md links to module docs which link to data files. Maximum two hops to any information. |
62 
63**Design Decision**:
64> "Rather than pre-loading all data, maintain lightweight identifiers and dynamically load data at runtime."
65 
66Applied in network module: agent first scans `contacts.jsonl` for matching name, then loads specific `interactions.jsonl` entries only for that contact.
67 
68---
69 
70### 5. Context Degradation (Mitigation)
71 
72| Risk | Source Skill | Digital Brain Mitigation |
73|------|--------------|--------------------------|
74| **Context Rot** | context-degradation | Module separation caps any single load. Voice file stays under 300 lines. Data files stream via JSONL (read line by line). |
75| **Stale Context** | context-degradation | `last_contact` timestamps in contacts. `stale_contacts.py` proactively surfaces relationships needing attention. |
76| **Conflicting Instructions** | context-degradation | Single source of truth per domain. Voice only in `voice.md`. Goals only in `goals.yaml`. No duplication. |
77 
78**Design Decision**:
79> "As context length increases, models experience diminishing returns in accuracy and recall."
80 
81Applied by keeping SKILL.md under 200 lines, each module instruction file under 100 lines, and using external files for data rather than inline content.
82 
83---
84 
85## Architecture Decisions
86 
87### Why JSONL for Logs?
88 
89```
90✓ Append-only by design
91✓ Stream-friendly (no full file parse)
92✓ Schema per line (first line documents structure)
93✓ Agent-friendly (standard JSON parsing)
94✓ Grep-compatible for quick searches
95 
96✗ Not human-editable (use YAML/MD for configs)
97✗ No transactions (acceptable for personal data)
98```
99 
100### Why Markdown for Narrative?
101 
102```
103✓ Human-readable and editable
104✓ Rich formatting (tables, lists, code)
105✓ Git-friendly diffs
106✓ Universal rendering
107 
108Use for: voice, brand, calendar, todos, templates
109```
110 
111### Why YAML for Config?
112 
113```
114✓ Hierarchical structure
115✓ Human-readable
116✓ Comments supported
117✓ Clean syntax for nested data
118 
119Use for: goals, values, circles, learning
120```
121 
122### Why XML for Prompts?
123 
124```
125✓ Clear structure for agents
126✓ Named sections (instructions, context, output)
127✓ Variable placeholders
128✓ Validation-friendly
129 
130Use for: content-generation templates, complex prompts
131```
132 
133---
134 
135## Workflow Mappings
136 
137### Content Creation → Skills Applied
138 
139```
140User: "Write a post about building in public"
141 
142Skills Chain:
1431. context-fundamentals → Load only identity module
1442. memory-systems → Retrieve voice patterns from voice.md
1453. context-optimization → Don't load network/operations
1464. tool-design → Use content templates as structured scaffolds
147 
148Files Loaded:
149- SKILL.md (50 tokens) - Routing
150- identity/IDENTITY.md (80 tokens) - Module instructions
151- identity/voice.md (200 tokens) - Voice patterns
152- identity/brand.md (scan for pillars) - Topic validation
153 
154Total: ~400 tokens vs loading entire brain (~5000 tokens)
155```
156 
157### Relationship Management → Skills Applied
158 
159```
160User: "Prepare me for my call with Alex"
161 
162Skills Chain:
1631. context-fundamentals → Load only network module
1642. memory-systems → Query contacts, then interactions
1653. context-optimization → Just-in-time loading of specific contact
1664. tool-design → Structured output (brief format)
167 
168Files Loaded:
169- SKILL.md (50 tokens) - Routing
170- network/NETWORK.md (60 tokens) - Module instructions
171- network/contacts.jsonl (scan for Alex) - Contact data
172- network/interactions.jsonl (filter by contact_id) - History
173 
174Total: ~300 tokens for relevant context only
175```
176 
177---
178 
179## Trade-offs and Rationale
180 
181| Decision | Trade-off | Rationale |
182|----------|-----------|-----------|
183| Separate modules | More files to navigate | Prevents context bloat; enables targeted loading |
184| JSONL for data | Less human-friendly | Optimized for agent parsing and append operations |
185| No database | No query language | Simplicity; works offline; no dependencies |
186| Python scripts | Requires Python runtime | Universal; readable; easy to extend |
187| Placeholders not examples | User must fill in | Avoids "AI slop"; forces personalization |
188 
189---
190 
191## Verification Checklist
192 
193When extending Digital Brain, verify:
194 
195- [ ] New files follow format conventions (JSONL/YAML/MD/XML)
196- [ ] Module instruction files stay under 100 lines
197- [ ] JSONL files include schema line as first entry
198- [ ] Cross-module references are minimal
199- [ ] Scripts are self-contained with clear I/O
200- [ ] No duplicate sources of truth
201 
202---
203 
204## Related Skills
205 
206This implementation draws from these skills in the collection:
207 
208| Skill | Primary Application |
209|-------|---------------------|
210| `context-fundamentals` | Overall architecture, progressive disclosure |
211| `context-degradation` | Mitigation strategies, file size limits |
212| `context-optimization` | Module separation, just-in-time loading |
213| `memory-systems` | JSONL design, append-only patterns |
214| `tool-design` | Agent scripts, I/O patterns |
215| `multi-agent-patterns` | Future: delegation to specialized sub-agents |
216 
217---
218 
219*This mapping demonstrates how theoretical context engineering principles translate to practical system design.*
220