by keli-wen
Agent skill for harness engineering — memory, permissions, context engineering, multi-agent coordination. Distilled from Claude Code, with Codex CLI and Gemini CLI on the roadmap. EN/ZH. Install via npx skills add.
# Add to your Claude Code skills
git clone https://github.com/keli-wen/agentic-harness-patterns-skill[!TIP] How this was built: Read the Distilling Claude Code Source — A Harness Engineering Practice Log for the full story of how Codex and Claude Code collaborated, the PCA-inspired taste injection, and what worked (and didn't).
The model loop is easy. User -> LLM -> tool_use -> execute -> loop fits on a napkin. What makes a production agent actually work — reliably, safely, at scale — is everything around the loop: memory that persists across sessions, permissions that fail closed, context budgets that don't explode, multi-agent coordination that doesn't collapse into chaos, and extensibility that doesn't become a security hole.
Anthropic calls this the harness. This repo teaches you how to build one.
[!NOTE] This skill is compatible with the open agent skills ecosystem. Install with
npx skills add— works with Claude Code, Codex, and 40+ other agents.
6 design-pattern chapters and 11 deep-dive references, extracted from systematic source-level analysis of the Claude Code runtime — the production AI coding agent behind Claude's 512,000-line TypeScript codebase.
[!IMPORTANT] This is not a code dump or a source mirror. Every pattern is expressed as a portable, runtime-agnostic design principle. Claude Code is used as grounding evidence, not as the only possible implementation. If you're building an agent on a different stack, these patterns still apply.
Also not: A Claude Code user guide / prompt engineering tutorial / "agents 101" / model selection guide.
No comments yet. Be the first to share your thoughts!
Engineers building or extending:
| # | Pattern | The Problem It Solves | Key Insight | |---|---|---|---| | 1 | Memory | "My agent forgets everything between sessions" | Separate instruction memory (human-curated) from auto-memory (agent-written) from session extraction (background-derived). Each has different trust, persistence, and review needs. | | 2 | Skills | "I re-explain workflows every conversation" | Skills are lazy-loaded instruction sets. Discovery must be cheap (~1% of context window); full body loads only on activation. Front-load trigger language — tails get truncated. | | 3 | Tools & Safety | "I want tools powerful but not dangerous" | Default to fail-closed. Concurrency is per-call, not per-tool. The permission pipeline has side effects — it tracks denials, transforms modes, and updates state. | | 4 | Context Engineering | "My agent sees too much, too little, or the wrong thing" | Four operations: select (just-in-time loading), write (the learning loop), compress (reactive compaction), isolate (delegation boundaries). | | 5 | Multi-agent | "I need parallelism without chaos" | Three patterns: Coordinator (zero-inheritance), Fork (full-inheritance, single-level), Swarm (flat peer roster). The coordinator must synthesize, not delegate understanding. | | 6 | Lifecycle | "I need hooks, background tasks, startup sequence" | Hook trust is all-or-nothing. Task eviction is two-phase. Bootstrap is dependency-ordered with trust as the critical inflection point. |
[!TIP] Each pattern includes: Problem -> Golden Rules -> Start Here (actionable first step) -> Tradeoffs -> Gotchas -> Claude Code Evidence. Start with the "Choose Your Problem" table in SKILL.md.
11 reference documents, each following the same structure: Problem (universal) -> Golden Rules (portable) -> Implementation Patterns (no code) -> Gotchas -> Claude Code Evidence (natural language).
| Reference | Covers | |---|---| | memory-persistence-pattern | Four-level instruction hierarchy, four-type auto-memory, background extraction with mutual exclusion | | skill-runtime-pattern | Four-source discovery, YAML frontmatter contract, budget-constrained listing, graceful degradation | | tool-registry-pattern | Fail-closed builder, per-call concurrency, partition-sort-concatenate for cache stability | | permission-gate-pattern | Single gate, three behaviors, strict layered evaluation, atomic claim for race-safe resolution | | agent-orchestration-pattern | Mutual exclusion of modes, fork cache optimization, flat swarm topology, tool filtering layers | | context-engineering | Index: select / compress / isolate sub-pattern routing | | select-pattern | Promise memoization, three-tier progressive disclosure, manual cache invalidation | | compress-pattern | Truncation with recovery pointers, reactive compaction, snapshot labeling | | isolate-pattern | Zero-inheritance default, single-level fork boundary, worktree-based filesystem isolation | | hook-lifecycle-pattern | Single dispatch, all-or-nothing trust, six hook types, exit-code discipline | | task-decomposition-pattern | Typed prefixed IDs, strict state machine, disk-backed output, two-phase eviction | | bootstrap-sequence-pattern | Dependency-ordered init, trust-split env vars, memoized concurrent callers, fast-path dispatch |
[!NOTE] Not by reading docs or guessing from external behavior.
For the full story — how Codex and Claude Code collaborated, the handoff protocol, what worked and what didn't — see Distillation Process.
[!TIP] Two skills available:
agentic-harness-patterns(English) andagentic-harness-patterns-zh(Chinese). Install via the Vercel Skills CLI — works with Claude Code, Codex, and 40+ other agents.
npx skills add github:keli-wen/agentic-harness-patterns-skill
agentic-harness-patterns/
├── README.md # This file (EN)
├── README_ZH.md # 中文版
├── LICENSE
└── skills/
├── agentic-harness-patterns/ # English skill
│ ├── SKILL.md
│ ├── metadata.json
│ └── references/ # 11 deep-dive documents
│ ├── memory-persistence-pattern.md
│ ├── skill-runtime-pattern.md
│ ├── permission-gate-pattern.md
│ ├── agent-orchestration-pattern.md
│ ├── tool-registry-pattern.md
│ ├── hook-lifecycle-pattern.md
│ ├── task-decomposition-pattern.md
│ ├── bootstrap-sequence-pattern.md
│ ├── context-engineering-pattern.md # Index → 3 sub-files
│ └── context-engineering/
│ ├── select-pattern.md
│ ├── compress-pattern.md
│ └── isolate-pattern.md
└── agentic-harness-patterns-zh/ # 中文 skill
├── S