Skip to content

SKILL.md

Latest commit

 

History

History
104 lines (78 loc) · 4.81 KB

SKILL.md

File metadata and controls

104 lines (78 loc) · 4.81 KB
Raw
name claude-code-harness-engineering
description Systematically learn and teach Claude Code-style coding agent harness engineering through public documentation, open-source projects, papers, and clean-room analysis. This skill should be invoked when the user wants to: learn how a Claude Code-style agent is built, implement a coding CLI, design a tool loop, analyze harness engineering, design memory/MCP/skills/permission systems, or prepare for engineering interviews about agent harness design. The skill provides a structured methodology from minimal agent loop to complete harness, covering agent loop, tool use, permission guard, context management, memory system, MCP protocol, skill loading, hooks, subagent, trace/observability, and CLI UX.

Claude Code Harness Engineering Skill

What This Skill Does

This skill teaches the engineering of coding agent harnesses — the operational environment that gives a model the ability to read, write, execute, and remember. It covers the full design space of Claude Code-style agents through public documentation, peer-reviewed papers, open-source teaching projects, and clean-room reimplementation reasoning.

This skill is not a reimplementation of Claude Code. It is a learning and teaching resource built on public information.

When to Use This Skill

Invoke this skill when the user asks to:

  • Learn how Claude Code / Codex / OpenCode-style coding agents are engineered
  • Implement a coding CLI or agent harness from scratch
  • Design an agent loop, tool registry, or tool executor
  • Analyze harness engineering patterns (permission, context, memory, MCP, skills, hooks)
  • Compare design decisions across coding agent implementations
  • Prepare for engineering interviews about agent harness design
  • Evaluate safety and security considerations in coding agent architectures
  • Map Claude Code-style designs to their own CLI projects

Methodology

This skill follows a progressive learning path from minimal agent loop to complete harness, organized into 12 modules:

Level 1: The Core Loop

  1. Agent Loop — The minimal while-loop: call model → check stop_reason → execute tools → repeat
  2. Tool Use — Tool registry, tool schema, tool executor, dispatch map

Level 2: Safety Boundaries

  1. Permission & Sandbox — Permission modes, path guard, command guard, approval pipeline
  2. Context Management — Token budget, compaction strategies, progressive disclosure

Level 3: Persistent State

  1. Memory System — JSONL/memory backend, selection/extraction/consolidation, sensitive info filtering
  2. MCP Protocol — Client/server tool protocol, stdio/HTTP transport, tool/resource/prompt

Level 4: Extensibility

  1. Skill Loading — SKILL.md metadata, on-demand injection, progressive disclosure
  2. Hooks & Lifecycle — PreToolUse/PostToolUse, SessionStart/End, extension points

Level 5: Advanced Capabilities

  1. Subagents & Worktree — Context isolation, git worktree, parallel execution
  2. Trace & Observability — Step logging, audit trail, debugging, evaluation

Level 6: Practice

  1. cty-cli Case Study — Mapping harness engineering to a real implementation
  2. Interview Preparation — Talking points, design checklist, common pitfalls

Key Design Principles

  1. The loop never changes. The while-loop (model → tools → repeat) is constant. All mechanisms (permission, memory, skills, hooks) are layers around it.

  2. Agency comes from the model, not the harness. The harness provides tools, knowledge, and boundaries. The model supplies intelligence.

  3. Progressive disclosure. Load knowledge on demand, not upfront. Skills list first (~80 tokens), expand only when needed.

  4. Boundaries before freedom. Set permission gates, path guards, and command filters before granting tool access.

  5. Context is the scarcest resource. Every token spent on system prompts, memory, and conversation history is a token not available for reasoning.

How to Read This Project

Start with docs/00-overview.md for the big picture, then work through docs/01-agent-loop.md through docs/11-cty-cli-case-study.md in order.

Each doc chapter follows a consistent structure:

  • Core Concepts — What problem this module solves
  • Engineering Structure — How it's built
  • Minimal Implementation — The simplest working version
  • Common Pitfalls — What goes wrong and how to avoid it
  • Mapping to cty-cli — How these ideas appear in a real project
  • Interview Talking Points — How to explain this in engineering interviews

Code examples live in examples/. Each is a self-contained, clean-room implementation demonstrating one harness module.

Checklists in checklists/ support design review, security audit, and interview preparation.