Claude Code Harness Builder

A skill tells Claude what to do. A harness tells Claude how to do it safely.

This distinction matters more than it seems. You can have brilliant skills - elegant prompts, perfect examples, carefully tuned instructions - and still end up with an AI system that can't be trusted in production. Not because the AI makes mistakes (it will), but because there's no scaffolding to catch those mistakes, no structure to ensure predictable execution, no governance layer between "Claude can do this" and "this organization trusts Claude to do this."

That scaffolding is the harness. And building it well is what separates demo-quality skills from production-ready capabilities.

What Is a Harness?

A harness wraps a skill (or set of skills) with execution infrastructure. Think of it like the difference between a bare function and a production service:

• The function does the work
• The service handles authentication, logging, error recovery, rate limiting, monitoring

Skills are functions. Harnesses turn them into services.

Concretely, a harness provides:

Execution context. What environment does this skill run in? What tools does it have access to? What prior context should be loaded?

Governance gates. Who approves this skill's execution? At what points should humans review output? What decisions can the skill make autonomously?

State management. How is progress tracked? What happens if execution fails midway? How do we resume from known-good checkpoints?

Boundaries. What can this skill NOT do? What files can't it touch? What actions require escalation?

Integration. How does this skill connect to workflows? What triggers it? What does it produce that other systems consume?

Without a harness, skills execute in isolation. With a harness, skills become part of a governed system.

The GSD Integration

The most powerful harness pattern I developed was the GSD (Get Shit Done) integration. GSD - retired mid-2026, but the pattern outlives it - was a workflow methodology: a way of organizing complex projects into phases, plans, and tasks with explicit verification and approval gates.

When skills integrated with GSD, they inherited that structure automatically.

How It Worked

GSD decomposed work into a hierarchy:

Each level has specific governance:

• Project - Has a ROADMAP.md defining all phases
• Phase - Has RESEARCH.md (discovery), CONTEXT.md (decisions), PLAN.md files (execution)
• Plan - Has tasks with explicit types: auto, checkpoint, decision
• Task - Has verification criteria and done conditions

A skill wrapped in a GSD harness executes as a task within a plan. The harness ensures:

1. The skill only runs when the task context is appropriate
2. Progress is committed atomically after each task
3. Checkpoints pause execution for human review
4. State is recoverable if execution fails

Example Harness Configuration

yaml

# .claude/harness/content-writer.yaml name: content-writer skill: personal-writing-style integration: gsd execution: type: phase-executor context_requirements: - RESEARCH.md (must exist) - CONTEXT.md (must exist) - PLAN.md (current plan file) governance: approval_gates: - type: checkpoint:human-verify trigger: after_each_artifact description: "Review artifact quality before proceeding" - type: checkpoint:decision trigger: on_ambiguity description: "Escalate unclear requirements" state: tracking: per-task-commit resume: from-last-commit artifacts: - path: ".planning/phases/{phase}/SUMMARY.md" created_at: plan-completion boundaries: file_scope: allowed: ["content/**", ".planning/**"] denied: ["src/**", "*.config.*"] actions: allowed: ["create", "modify", "read"] denied: ["delete", "git-push"]

This configuration creates a harness for a content-writing skill. The skill itself might be excellent at generating prose, but the harness ensures:

• It only runs with proper planning context loaded
• Humans review each artifact before the system proceeds
• Changes are committed atomically and can be resumed
• The skill can't touch source code or push to git

The skill does the creative work. The harness makes it safe.

PM-Approval Gates

Most organizations have approval workflows. Before a feature ships, someone reviews it. Before a document publishes, someone approves it. Before money moves, someone authorizes it.

AI skills need the same governance, but the implementation is different because AI execution is non-interactive. You can't have Claude stop mid-task and wait for a Slack message.

The Checkpoint Pattern

The solution is checkpoints - explicit pause points where execution stops and waits for human input.

markdown

<!-- In a PLAN.md file --> <task type="auto"> <name>Generate quarterly report</name> <action>Use analytics-reporter skill to compile Q3 metrics</action> <verify>Report covers all KPIs, calculations are accurate</verify> </task> <task type="checkpoint:human-verify"> <name>Review report before publishing</name> <action>Present report to stakeholder for approval</action> <await>Approval or revision requests</await> </task> <task type="auto"> <name>Publish approved report</name> <action>Deploy to dashboard, notify stakeholders</action> </task>

When execution reaches the checkpoint, the harness:

1. Commits all work completed so far
2. Returns a structured checkpoint message with what was done
3. Waits for continuation signal (approval, revision, or rejection)
4. Resumes from checkpoint with user's decision incorporated

This pattern works because state is explicit. The harness doesn't need to "remember" where it was - the git history and plan file tell it exactly what's complete and what's pending.

Types of Checkpoints

human-verify (most common): "I built this, please confirm it meets requirements before I continue."

decision: "I need to make a choice and want your input on which direction."

human-action: "There's something only a human can do (like entering credentials or clicking a external link)."

Each type has different presentation and expected responses. The harness formats the pause appropriately.

Phase Determinism

A common failure mode in AI systems is non-deterministic execution. Run the same prompt twice, get different results. This is fine for creative tasks but terrible for systematic work.

The harness enforces determinism through phase structure:

Explicit Dependencies

yaml

phase: 15-claude-skills-factory plan: 05 depends_on: [15-02]

A plan can only execute if its dependencies are satisfied. The harness checks:

• Do the required SUMMARY.md files exist?
• Did the dependency plans complete successfully?
• Is the state file showing the right position?

Atomic Commits

Each task in a plan produces exactly one commit. The commit message follows a convention:

This means:

• Every task is traceable to a commit
• You can bisect to find exactly which task introduced an issue
• Rollback is granular - revert one task, not an entire phase

Resumable Execution

If execution fails mid-plan, the harness can resume:

1. Read git log to find completed task commits
2. Read PLAN.md to find all tasks
3. Compare to determine resume point
4. Continue from first incomplete task

This works because the harness never relies on in-memory state. Everything is serialized to files that survive process restarts.

Guardrails and Boundaries

Skills can be dangerously capable. A code-modification skill can corrupt your codebase. A deployment skill can break production. An email skill can send messages you didn't intend.

Guardrails are the constraints that prevent skills from exceeding their intended scope.

File Boundaries

yaml

boundaries: file_scope: allowed: - "content/artifacts/**/*.mdx" - ".planning/**/*.md" denied: - "**/*.ts" - "**/*.tsx" - "**/node_modules/**"

The harness intercepts file operations and checks them against boundaries. A content skill that tries to modify TypeScript files gets blocked, not because it can't (Claude can write TypeScript), but because it shouldn't in this context.

Action Constraints

yaml

actions: allowed: - file:create - file:modify - file:read - git:commit - git:status denied: - file:delete - git:push - git:reset - shell:* # No arbitrary shell commands

Some actions are too dangerous for automated execution. The harness blocks them outright or escalates to a checkpoint.

Scope Escalation

When a skill needs to exceed its boundaries, the harness can escalate rather than fail:

python

class HarnessGuardrail: def check_action(self, action: Action) -> GuardrailResult: if action in self.denied_actions: return GuardrailResult( allowed=False, escalation="checkpoint:human-action", message=f"Action {action} requires human approval" ) if action in self.allowed_actions: return GuardrailResult(allowed=True) # Unknown action - escalate to be safe return GuardrailResult( allowed=False, escalation="checkpoint:decision", message=f"Action {action} not in allowed list - please confirm" )

This creates a fail-safe default: unknown actions require human approval rather than either blocking silently or executing unsafely.

Artifact Syncing

Skills often produce artifacts that other systems need. A documentation skill produces MDX files. An analysis skill produces reports. A code-generation skill produces source files.

The harness manages artifact lifecycle:

Creation Tracking

yaml

artifacts: - path: "content/artifacts/{slug}/content.mdx" created_by: task tracked_in: SUMMARY.md - path: ".planning/phases/{phase}/{plan}-SUMMARY.md" created_by: plan-completion tracked_in: STATE.md

Each artifact has a defined creation trigger and tracking location. The harness ensures:

• Artifacts are created at the right time
• Their existence is recorded in the appropriate tracking files
• Dependencies can verify artifact availability

State Propagation

When a plan completes, the harness updates multiple state files:

python

class ArtifactSync: def on_plan_complete(self, phase: str, plan: str, summary: PlanSummary): # Create SUMMARY.md for the completed plan self.write_summary(phase, plan, summary) # Update STATE.md with new position self.update_state( current_phase=phase, current_plan=plan, status="complete", last_activity=datetime.now() ) # Update any aggregate tracking self.update_roadmap_progress(phase)

This ensures that downstream processes always have accurate state information. A continuation agent reading STATE.md knows exactly where execution stopped and what's been accomplished.

Conflict Resolution

What if a skill tries to modify an artifact that another skill is also modifying? The harness provides locking:

yaml

locking: strategy: optimistic conflict_resolution: checkpoint # When conflict detected: # 1. Pause execution # 2. Present both versions to human # 3. Human chooses resolution # 4. Winning version committed, loser discarded

This is rare in practice (well-designed phases have clear ownership), but the safety mechanism exists.

Building Your Own Harness

You don't need the full GSD system to benefit from harness patterns. Start with the pieces that address your biggest risks.

Minimal Viable Harness

At minimum, a harness should provide:

1. Context loading - What files should Claude read before executing the skill?
2. Output validation - Does the output match expected format?
3. Commit discipline - Are changes atomic and labeled?

yaml

# Simple harness configuration name: my-skill-harness skill: my-skill context: always_load: - CLAUDE.md - .cursorrules validation: output_format: markdown required_sections: ["Summary", "Details"] commit: on: task-complete message_format: "{skill}: {task}"

This is enough to get basic governance. Skills execute with consistent context, produce validated output, and leave traceable commits.

Adding Governance Incrementally

As trust develops, add governance layers:

Week 1: Basic context and validation Week 2: Add file boundaries Week 3: Add checkpoints for sensitive operations Week 4: Add state tracking and resumability Week 5: Add artifact syncing

Each layer makes the harness more robust without requiring a complete redesign.

Testing the Harness

Harnesses need testing too:

markdown

## Harness Test Cases ### Boundary Enforcement - [ ] Skill attempts file outside allowed scope -> blocked - [ ] Skill attempts denied action -> escalated - [ ] Unknown action -> escalated (not silently allowed) ### Checkpoint Behavior - [ ] Checkpoint reached -> execution pauses - [ ] Checkpoint resumed -> execution continues from right point - [ ] Checkpoint rejected -> execution stops cleanly ### State Recovery - [ ] Process killed mid-task -> can resume - [ ] Git shows partial commit -> resume handles correctly - [ ] SUMMARY.md missing -> appropriate error ### Artifact Sync - [ ] Task creates artifact -> tracked in SUMMARY.md - [ ] Plan completes -> STATE.md updated - [ ] Concurrent modification -> conflict detected

Run these tests before trusting the harness with important work.

Why This Matters

Skills without harnesses are toys. They work in demos, fail in production.

The harness provides the boring infrastructure that makes skills trustworthy:

• Predictability: Same inputs, same process, traceable outputs
• Governance: Humans approve before irreversible actions
• Recovery: Failures don't lose work or corrupt state
• Boundaries: Skills can't exceed their intended scope
• Integration: Skills connect to organizational workflows

Building skills is creative work. Building harnesses is engineering work. You need both.

Start with the simplest harness that addresses your risks. Add layers as you learn what your specific skills need. Don't try to build the perfect governance system upfront - iterate toward it.

The goal isn't to constrain AI capabilities. It's to make those capabilities safe enough to actually use.

---

Quick Reference

Harness Checklist

Before deploying a skill, verify the harness provides:

• Context loading (what files to read)
• Output validation (format checks)
• File boundaries (scope limits)
• Action constraints (what it can/can't do)
• Checkpoint integration (approval gates)
• State tracking (resumability)
• Artifact syncing (output tracking)
• Commit discipline (atomic, labeled)

Common Configurations

Content Skills

yaml

boundaries: files: ["content/**", ".planning/**"] actions: [create, modify, read, commit] checkpoints: after-each-artifact

Code Skills

yaml

boundaries: files: ["src/**", "tests/**"] actions: [create, modify, read, commit] checkpoints: before-merge

Analysis Skills

yaml

boundaries: files: ["reports/**", "data/**"] actions: [read, create] # no modify - append-only checkpoints: before-publish

Deployment Skills

yaml

boundaries: files: ["config/**", "scripts/**"] actions: [read] # very restricted checkpoints: before-every-action

Key Integration Points

Component	Connects To	Via
Skill	Context	CLAUDE.md, SKILL.md
Harness	Workflow	PLAN.md tasks
Checkpoints	Users	Orchestrator layer
State	Recovery	STATE.md, git
Artifacts	Downstream	SUMMARY.md, file system

GSD Harness Quick Start

1. Create .claude/harness/{skill-name}.yaml
2. Define context requirements
3. Set file and action boundaries
4. Configure checkpoint triggers
5. Test with a small plan
6. Monitor and iterate

---

Related

For patterns on building the agents that harnesses wrap, see KB Agent Code Patterns.

For the full skill development process, see Building Production-Ready AI Tools with Claude Skills.