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.

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

[!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).

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
        ├── 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:

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
• Claude Code source repository — the source this analysis is based on
• Vercel Skills CLI — the npx skills add package manager

[!WARNING] Disclaimer: These patterns were distilled by studying the Claude Code source 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.

License

MIT — see LICENSE.