Skip to content
Back to search

agentic-harness-patterns-skill

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/keli-wen--agentic-harness-patterns-skill/badge.svg)](/listings/keli-wen--agentic-harness-patterns-skill)

HTML

<a href="/listings/keli-wen--agentic-harness-patterns-skill"><img src="/api/listings/keli-wen--agentic-harness-patterns-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> [!TIP] > Two skills available: `agentic-harness-patterns` (English) and `agentic-harness-patterns-zh` (Chinese). Install via the [Vercel Skills CLI](https://github.com/vercel-labs/skills) — works with Claude Code, Codex, and 40+ other agents.

npx skills add github:keli-wen/agentic-harness-patterns-skill

<p align="center"> </p>

**Just reading:** Open [SKILL.md](skills/agentic-harness-patterns/SKILL.md) (EN) or [SKILL.md](skills/agentic-harness-patterns-zh/SKILL.md) (ZH).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 175 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="images/agent-harness-patterns-header.png" alt="Agentic Harness Patterns" width="680">
  3. </p>
  4. <p align="center">
  5. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  6. <a href="https://github.com/vercel-labs/skills"><img src="https://img.shields.io/badge/npx_skills_add-compatible-brightgreen.svg" alt="Skills Compatible"></a>
  7. <a href="https://github.com/anthropics/claude-code"><img src="https://img.shields.io/badge/Claude_Code-source_analysis-d4a574.svg" alt="Claude Code"></a>
  8. </p>
  9. <p align="center"><strong>Production design patterns for AI coding agents, distilled from 512,000 lines of Claude Code.</strong></p>
  10. <p align="center">
  11. <a href="README.md"><strong>English</strong></a> · <a href="README_ZH.md"><strong>中文</strong></a>
  12. </p>
  13. ---
  14. > [!TIP]
  15. > **How this was built:** Read the [Distilling Claude Code Source — A Harness Engineering Practice Log](docs/distillation-harness-practice.md) for the full story of how Codex and Claude Code collaborated, the PCA-inspired taste injection, and what worked (and didn't).
  16. 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.
  17. Anthropic calls this the **harness**. This repo teaches you how to build one.
  18. > [!NOTE]
  19. > This skill is compatible with the [open agent skills ecosystem](https://github.com/vercel-labs/skills). Install with `npx skills add` — works with Claude Code, Codex, and 40+ other agents.
  20. ## What This Is
  21. 6 design-pattern chapters and 11 deep-dive references, extracted from systematic source-level analysis of the [Claude Code runtime](https://github.com/anthropics/claude-code) — the production AI coding agent behind Claude's 512,000-line TypeScript codebase.
  22. > [!IMPORTANT]
  23. > **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.
  24. **Also not:** A Claude Code user guide / prompt engineering tutorial / "agents 101" / model selection guide.
  25. ## Who Should Read This
  26. Engineers building or extending:
  27. - Coding-agent runtimes (like Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf)
  28. - Custom agents and agent plugins
  29. - Multi-agent orchestration systems
  30. - Any production system where an LLM calls tools in a loop and needs to be reliable
  31. ## The Six Harness Layers
  32. | # | Pattern | The Problem It Solves | Key Insight |
  33. |---|---|---|---|
  34. | 1 | [**Memory**](skills/agentic-harness-patterns/SKILL.md#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. |
  35. | 2 | [**Skills**](skills/agentic-harness-patterns/SKILL.md#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. |
  36. | 3 | [**Tools & Safety**](skills/agentic-harness-patterns/SKILL.md#3-tools-and-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. |
  37. | 4 | [**Context Engineering**](skills/agentic-harness-patterns/SKILL.md#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). |
  38. | 5 | [**Multi-agent**](skills/agentic-harness-patterns/SKILL.md#5-multi-agent-coordination) | "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. |
  39. | 6 | [**Lifecycle**](skills/agentic-harness-patterns/SKILL.md#6-lifecycle-and-extensibility) | "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. |
  40. > [!TIP]
  41. > 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](skills/agentic-harness-patterns/SKILL.md).
  42. ## Deep-Dive References
  43. 11 reference documents, each following the same structure: Problem (universal) -> Golden Rules (portable) -> Implementation Patterns (no code) -> Gotchas -> Claude Code Evidence (natural language).
  44. | Reference | Covers |
  45. |---|---|
  46. | [memory-persistence-pattern](skills/agentic-harness-patterns/references/memory-persistence-pattern.md) | Four-level instruction hierarchy, four-type auto-memory, background extraction with mutual exclusion |
  47. | [skill-runtime-pattern](skills/agentic-harness-patterns/references/skill-runtime-pattern.md) | Four-source discovery, YAML frontmatter contract, budget-constrained listing, graceful degradation |
  48. | [tool-registry-pattern](skills/agentic-harness-patterns/references/tool-registry-pattern.md) | Fail-closed builder, per-call concurrency, partition-sort-concatenate for cache stability |
  49. | [permission-gate-pattern](skills/agentic-harness-patterns/references/permission-gate-pattern.md) | Single gate, three behaviors, strict layered evaluation, atomic claim for race-safe resolution |
  50. | [agent-orchestration-pattern](skills/agentic-harness-patterns/references/agent-orchestration-pattern.md) | Mutual exclusion of modes, fork cache optimization, flat swarm topology, tool filtering layers |
  51. | [context-engineering](skills/agentic-harness-patterns/references/context-engineering-pattern.md) | Index: select / compress / isolate sub-pattern routing |
  52. | [select-pattern](skills/agentic-harness-patterns/references/context-engineering/select-pattern.md) | Promise memoization, three-tier progressive disclosure, manual cache invalidation |
  53. | [compress-pattern](skills/agentic-harness-patterns/references/context-engineering/compress-pattern.md) | Truncation with recovery pointers, reactive compaction, snapshot labeling |
  54. | [isolate-pattern](skills/agentic-harness-patterns/references/context-engineering/isolate-pattern.md) | Zero-inheritance default, single-level fork boundary, worktree-based filesystem isolation |
  55. | [hook-lifecycle-pattern](skills/agentic-harness-patterns/references/hook-lifecycle-pattern.md) | Single dispatch, all-or-nothing trust, six hook types, exit-code discipline |
  56. | [task-decomposition-pattern](skills/agentic-harness-patterns/references/task-decomposition-pattern.md) | Typed prefixed IDs, strict state machine, disk-backed output, two-phase eviction |
  57. | [bootstrap-sequence-pattern](skills/agentic-harness-patterns/references/bootstrap-sequence-pattern.md) | Dependency-ordered init, trust-split env vars, memoized concurrent callers, fast-path dispatch |
  58. ## How This Was Built
  59. > [!NOTE]
  60. > Not by reading docs or guessing from external behavior.
  61. 1. **Deep exploration** — 4 parallel agents mapped the full source tree (~1,900 files)
  62. 2. **Source-grounded drafting** — 7 parallel agents each drafted one reference, tracing claims to source files
  63. 3. **Factual review** — 3 independent review rounds verified each claim against source code
  64. 4. **Abstraction uplift** — Implementation details pushed into "Evidence" sections; principles generalized to be runtime-portable
  65. 5. **UX audit** — Discoverability, audience fit, and principle-to-action gap reviewed from user perspective
  66. For the full story — how Codex and Claude Code collaborated, the handoff protocol, what worked and what didn't — see **[Distillation Process](docs/distillation-harness-practice.md)**.
  67. ## Installation
  68. > [!TIP]
  69. > Two skills available: `agentic-harness-patterns` (English) and `agentic-harness-patterns-zh` (Chinese). Install via the [Vercel Skills CLI](https://github.com/vercel-labs/skills) — works with Claude Code, Codex, and 40+ other agents.
  70. ```bash
  71. npx skills add github:keli-wen/agentic-harness-patterns-skill
  72. ```
  73. <p align="center">
  74. <img src="images/skill-install-screenshot.png" alt="npx skills add screenshot" width="720">
  75. </p>
  76. **Just reading:** Open [SKILL.md](skills/agentic-harness-patterns/SKILL.md) (EN) or [SKILL.md](skills/agentic-harness-patterns-zh/SKILL.md) (ZH).
  77. ## Project Structure
  78. ```
  79. agentic-harness-patterns/
  80. ├── README.md # This file (EN)
  81. ├── README_ZH.md # 中文版
  82. ├── LICENSE
  83. └── skills/
  84. ├── agentic-harness-patterns/ # English skill
  85. │ ├── SKILL.md
  86. │ ├── metadata.json
  87. │ └── references/ # 11 deep-dive documents
  88. │ ├── memory-persistence-pattern.md
  89. │ ├── skill-runtime-pattern.md
  90. │ ├── permission-gate-pattern.md
  91. │ ├── agent-orchestration-pattern.md
  92. │ ├── tool-registry-pattern.md
  93. │ ├── hook-lifecycle-pattern.md
  94. │ ├── task-decomposition-pattern.md
  95. │ ├── bootstrap-sequence-pattern.md
  96. │ ├── context-engineering-pattern.md # Index → 3 sub-files
  97. │ └── context-engineering/
  98. │ ├── select-pattern.md
  99. │ ├── compress-pattern.md
  100. │ └── isolate-pattern.md
  101. └── agentic-harness-patterns-zh/ # 中文 skill
  102. ├── SKILL.md # Chinese translation
  103. ├── metadata.json
  104. └── references/ # Chinese references
  105. └── ...
  106. ```
  107. ## Roadmap
  108. This skill currently covers patterns distilled from **Claude Code** — arguably the most mature open-source-available agent harness. The long-term goal is to build a unified, cross-runtime pattern library by analyzing additional production agent systems:
  109. | Runtime | Status | Notes |
  110. |---|---|---|
  111. | **Claude Code** | Done | Current release — 6 chapters, 11 references |
  112. | **Codex CLI** | Planned | OpenAI's agent CLI; distinct context and delegation model |
  113. | **Gemini CLI** | Planned | Google's approach to tool orchestration and memory |
  114. | **Unified synthesis** | Future | Cross-runtime patterns that survive all three implementations |
  115. The hypothesis: patterns that independently emerge across Claude Code, Codex, and Gemini CLI are likely fundamental to the problem domain, not artifacts of any single team's design taste.
  116. ## Further Reading
  117. For a deeper exploration of context engineering, see the author's blog [One Poem Suffices](https://keli-wen.github.io/One-Poem-Suffices/):
  118. - [Context Engineering](https://keli-wen.github.io/One-Poem-Suffices/one-poem-suffices/context-engineering/) — conceptual framework and design space
  119. - [Just-in-Time Context](https://keli-wen.github.io/One-Poem-Suffices/one-poem-suffices/just-in-time-context/) — principles and practices of on-demand context loading
  120. - [Context Engineering from Codex](https://keli-wen.github.io/One-Poem-Suffices/thinking-in-context/context-engineering-from-codex/) — context engineering through the Codex lens
  121. > A deep dive into context engineering in Claude Code is currently in progress.
  122. ## Related Work
  123. - [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Anthropic's own blog post on the harness concept
  124. - [Claude Code source repository](https://github.com/anthropics/claude-code) — the source this analysis is based on
  125. - [Vercel Skills CLI](https://github.com/vercel-labs/skills) — the `npx skills add` package manager
  126. ---
  127. > [!WARNING]
  128. > **Disclaimer:** These patterns were distilled by studying the [Claude Code source code](https://github.com/anthropics/claude-code) that was made publicly available. This project is **for educational and learning purposes only**. No proprietary source code is reproduced. All content represents independently extracted design principles expressed in the author's own words. Claude Code is a trademark of Anthropic, PBC.
  129. ## License
  130. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.