Documentation
Plugin
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.
Plugin Signal40/100Fair
maintained28
capable23
documented75
adopted53
Install
$ npx -y skills add keli-wen/agentic-harness-patterns-skill --agent claude-code
Stats
304
Stars
50
Forks
Maintained
Maintenance
MIT
License
5mo ago
Last commit
5mo ago
Created
Repo: keli-wen/agentic-harness-patterns-skill
What's inside
Badges
README
[!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.
What This Is
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.
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.
- Deep exploration — 4 parallel agents mapped the full source tree (~1,900 files)
- Source-grounded drafting — 7 parallel agents each drafted one reference, tracing claims to source files
- Factual review — 3 independent review rounds verified each claim against source code
- Abstraction uplift — Implementation details pushed into "Evidence" sections; principles generalized to be runtime-portable
- 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) 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
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
├── SKILL.md # Chinese translation
├── metadata.json
└── references/ # Chinese references
└── ...
Roadmap
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:
| Runtime | Status | Notes |
|---|---|---|
| Claude Code | Done | Current release — 6 chapters, 11 references |
| Codex CLI | Planned | OpenAI's agent CLI; distinct context and delegation model |
| Gemini CLI | Planned | Google's approach to tool orchestration and memory |
| Unified synthesis | Future | Cross-runtime patterns that survive all three implementations |
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.
Further Reading
For a deeper exploration of context engineering, see the author's blog One Poem Suffices:
- Context Engineering — conceptual framework and design space
- Just-in-Time Context — principles and practices of on-demand context loading
- Context Engineering from Codex — context engineering through the Codex lens
A deep dive into context engineering in Claude Code is currently in progress.
Related Work
- Anthropic: Effective harnesses for long-running agents — Anthropic's own blog post on the harness concept
File tree
FAQ
agentic-harness-patterns-skill is a Claude Code plugin with 2 hand-picked skills for documentation work, indexed on Flowy. Install it with the command on its page. It includes agentic-harness-patterns-zh, agentic-harness-patterns. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is 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.
- How do I install agentic-harness-patterns-skill?
- Run these in Claude Code: npx -y skills add keli-wen/agentic-harness-patterns-skill --agent claude-code. Then prompt normally.
- Does agentic-harness-patterns-skill auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is agentic-harness-patterns-skill free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it