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 15 Agent Skills teaching context engineering and harness engineering principles for production AI agent systems. Skills are platform-agnostic (Claude Code, Cursor, GitHub Copilot, any Open Plugins-conformant tool). v2.2.0 ships a file-based researcher operating system with deterministic gates and a continuous loop.
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/` - 15 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/` - File-based research-to-skill operating system: rubrics, mechanism registry, claim provenance, corpus index, run state machine, adversarial benchmarks, continuous loop, launchd service definitions
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 (single bundled plugin, v2.2.0)
20- `.plugin/plugin.json` - Open Plugins format manifest (v2.2.0)
21 
22## Build & Test Commands
23 
24No top-level build system. Repo-level gates and per-project tooling below.
25 
26### Top-level deterministic gates (run on every PR via CI)
27 
28```
29python3 researcher/scripts/validate_repo.py --strict       # corpus structure, manifests, rubric math, mechanism registry, claims, corpus index, activation cases, benchmark scenarios, run artifacts
30python3 researcher/scripts/skill_health.py --strict --no-history  # deterministic skill-body quality gate
31python3 researcher/scripts/run_benchmarks.py               # adversarial benchmark harness + repo + activation gates
32python3 researcher/scripts/check_activation_cases.py       # skill-boundary regression fixtures
33```
34 
35### Per-run readiness (active runs only)
36 
37```
38python3 researcher/scripts/validate_run.py --run-dir researcher/runs/<run-id>
39```
40 
41### Continuous loop (manual or launchd)
42 
43```
44python3 researcher/scripts/loop_discover.py
45python3 researcher/scripts/loop_step.py --allow-fetch
46python3 researcher/scripts/loop_daily.py
47python3 researcher/scripts/loop_status.py
48 
49researcher/orchestration/launchd/install.sh    # macOS daemon
50researcher/orchestration/launchd/uninstall.sh
51```
52 
53### Example projects
54 
55#### examples/llm-as-judge-skills (TypeScript, Node >= 18)
56```
57cd examples/llm-as-judge-skills
58npm install
59npm run build        # tsc
60npm test             # vitest (19 tests)
61npm run lint         # eslint
62npm run format       # prettier
63npm run typecheck    # tsc --noEmit
64```
65 
66#### examples/interleaved-thinking (Python >= 3.10)
67```
68cd examples/interleaved-thinking
69pip install -e ".[dev]"
70pytest               # pytest + pytest-asyncio
71ruff check .         # linting (100 char line length)
72```
73 
74#### examples/digital-brain-skill (Node.js)
75```
76cd examples/digital-brain-skill
77npm run setup
78npm run weekly-review
79npm run content-ideas
80npm run stale-contacts
81```
82 
83## Skill Authoring Rules
84 
85When creating or editing skills:
86 
871. **SKILL.md must stay under 500 lines**: move detailed content to `references/` directory
882. **YAML frontmatter is required**: must include `name` and `description` fields
893. **Folder naming**: lowercase with hyphens (e.g., `context-fundamentals`)
904. **Write in third person**: descriptions are injected into system prompts; inconsistent POV causes discovery issues
915. **Platform-agnostic**: no vendor-locked examples or platform-specific tool names without abstraction
926. **Token-conscious**: challenge each paragraph and assume an advanced audience
937. **Body standard**: include `When to Activate`, `Core Concepts`, `Practical Guidance`, `Examples`, `Guidelines`, `Gotchas`, `Integration`, and `References`
948. **Explicit boundaries**: every `When to Activate` section needs positive triggers plus a `Do not activate` block routing adjacent work to the right skill
959. **Include a Gotchas section**: experience-derived failure modes are the highest-signal content in any skill
9610. **Update root README.md** when adding new skills
9711. **Update marketplace/plugin manifests** when adding skills (`.claude-plugin/marketplace.json`, `.plugin/plugin.json`)
9812. **Update the corpus index** (`researcher/corpus/index.json`) to map the new skill to activation scenarios, mechanism IDs, and claim IDs
9913. **Update mechanisms and claims**: add registry entries for reusable behavior changes and `claim-*` provenance for numeric, benchmark, volatile, or vendor-performance claims
10014. **Run `validate_repo.py --strict`, `skill_health.py --strict --no-history`, `check_activation_cases.py`, and `run_benchmarks.py`** before committing skill changes
101 
102## Researcher OS Rules
103 
104When working through the researcher operating system:
105 
1061. **Initialize runs via `research_loop.py init`**: it creates `run-state.json`, queue entry, thread log, source evaluation scaffold, and mechanism proposal template
1072. **Advance state explicitly**: use `retrieve`, `evaluate`, `propose`, `novelty`, `validate-run`, `pr-ready`, `close` subcommands; do not edit `run-state.json` by hand
1083. **Promote mechanisms only after run readiness**: `research_loop.py promote-mechanisms` requires `--reviewed-by` and a passing run-readiness check
1094. **Add claim provenance** to `researcher/claims/index.jsonl` for any numeric, benchmark, or volatile claim added to a skill
1105. **Never invoke paid LLMs from the continuous loop**: HTTP retrieval is stdlib-only, judge adapters are explicitly out of scope until budget-gated
1116. **Never commit runtime queue/report files**: `.gitignore` covers `researcher/queue/*.jsonl`, `researcher/reports/{logs,snapshots,loop-events.jsonl,loop-failures.jsonl,status.md,parked-review.md}`, and `researcher/runs/*/` except the seed run
112 
113## Plugin Architecture
114 
115All 15 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.
116 
117Progressive disclosure pattern: only skill names/descriptions load at startup; full content loads on activation.
118 
119## Key Design Principles
120 
121- **Context quality over quantity**: attention scarcity and lost-in-middle behavior mean more context is not always better
122- **Sub-agents isolate context**: they exist to manage attention budget, not simulate org roles
123- **Skills reference each other**: use plain text skill names (not links) in Integration sections to avoid cross-directory reference issues
124- **Examples use Python pseudocode**: conceptual demonstrations that work across environments, not production-ready implementations
125- **Deterministic first, model-judged second**: structure, schema, rubric math, manifest sync, retrieval status, and registry shape must pass before any LLM judge is invoked
126- **Human-controlled merge**: agents may prepare PRs and pass gates, but push and merge always require explicit human approval
127