1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7Agent Skills for Context Engineering — an open collection of 14 Agent Skills teaching context engineering principles for production AI agent systems. Skills are platform-agnostic (Claude Code, Cursor, GitHub Copilot, any Open Plugins-conformant tool).
8 
9Context engineering is the discipline of curating everything that enters a model's context window (system prompts, tool definitions, retrieved documents, message history, tool outputs) to maximize signal within limited attention budget.
10 
11## Repository Structure
12 
13- `skills/` — 14 skill directories, each containing a `SKILL.md` with YAML frontmatter (`name`, `description`) and optional `references/` and `scripts/` subdirectories
14- `examples/` — 5 complete demonstration projects (digital-brain-skill, llm-as-judge-skills, book-sft-pipeline, x-to-book-system, interleaved-thinking)
15- `docs/` — Research materials and reference documentation
16- `researcher/` — Research output examples
17- `template/SKILL.md` — Canonical skill template (use when creating new skills)
18- `SKILL.md` (root) — Collection-level metadata and skill map
19- `.claude-plugin/marketplace.json` — Claude Code marketplace manifest (5 bundled plugins)
20- `.plugin/plugin.json` — Open Plugins format manifest (v2.0.0)
21 
22## Build & Test Commands
23 
24No top-level build system. Individual example projects have their own tooling:
25 
26### examples/llm-as-judge-skills (TypeScript, Node >= 18)
27```
28cd examples/llm-as-judge-skills
29npm install
30npm run build        # tsc
31npm test             # vitest (19 tests)
32npm run lint         # eslint
33npm run format       # prettier
34npm run typecheck    # tsc --noEmit
35```
36 
37### examples/interleaved-thinking (Python >= 3.10)
38```
39cd examples/interleaved-thinking
40pip install -e ".[dev]"
41pytest               # pytest + pytest-asyncio
42ruff check .         # linting (100 char line length)
43```
44 
45### examples/digital-brain-skill (Node.js)
46```
47cd examples/digital-brain-skill
48npm run setup
49npm run weekly-review
50npm run content-ideas
51npm run stale-contacts
52```
53 
54## Skill Authoring Rules
55 
56When creating or editing skills:
57 
581. **SKILL.md must stay under 500 lines** — move detailed content to `references/` directory
592. **YAML frontmatter is required** — must include `name` and `description` fields
603. **Folder naming**: lowercase with hyphens (e.g., `context-fundamentals`)
614. **Write in third person** — descriptions are injected into system prompts; inconsistent POV causes discovery issues
625. **Platform-agnostic** — no vendor-locked examples or platform-specific tool names without abstraction
636. **Token-conscious** — challenge each paragraph: "Does Claude really need this?" Assume advanced audience
647. **Include a Gotchas section** — experience-derived failure modes are the highest-signal content in any skill
658. **Update root README.md** when adding new skills
669. **Update marketplace/plugin manifests** when adding skills (`.claude-plugin/marketplace.json`, `.plugin/plugin.json`)
67 
68## Plugin Architecture
69 
70All 14 skills are distributed as a single plugin (`context-engineering`) in the marketplace manifest. This avoids cache duplication — Claude Code caches each plugin's `source` directory separately, so multiple plugins pointing to `source: "./"` would each cache a full copy of the repo.
71 
72Progressive disclosure pattern: only skill names/descriptions load at startup; full content loads on activation.
73 
74## Key Design Principles
75 
76- **Context quality over quantity** — attention scarcity and lost-in-middle phenomenon mean more context is not always better
77- **Sub-agents isolate context** — they exist to manage attention budget, not simulate org roles
78- **Skills reference each other** — use plain text skill names (not links) in Integration sections to avoid cross-directory reference issues
79- **Examples use Python pseudocode** — conceptual demonstrations that work across environments, not production-ready implementations
80