agentic-harness-patterns-skill

Who Should Read This

Engineers building or extending:

• Coding-agent runtimes (like Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf)
• Custom agents and agent plugins
• Multi-agent orchestration systems
• Any production system where an LLM calls tools in a loop and needs to be reliable

The Six Harness Layers

| # | 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.

Deep-Dive References

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 |

How This Was Built

[!NOTE] Not by reading docs or guessing from external behavior.

1. Deep exploration — 4 parallel agents mapped the full source tree (~1,900 files)
2. Source-grounded drafting — 7 parallel agents each drafted one reference, tracing claims to source files
3. Factual review — 3 independent review rounds verified each claim against source code
4. Abstraction uplift — Implementation details pushed into "Evidence" sections; principles generalized to be runtime-portable
5. UX audit — Discoverability, audience fit, and principle-to-action gap reviewed from user perspective

For the full story — how Codex and Claude Code collaborated, the handoff protocol, what worked and what didn't — see Distillation Process.

Installation

[!TIP] Two skills available: agentic-harness-patterns (English) and agentic-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

Just reading: Open SKILL.md (EN) or SKILL.md (ZH).

Project Structure

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