Claude Code Harness 3-Layer Architecture: Understanding the Skill/Workflow/Profile System

Claude Code Harness implements a strict separation of concerns through three distinct layers: Profiles define global configuration and command bindings, Workflows orchestrate sequential execution steps, and Skills provide atomic, self-contained operations with rich metadata.

The Chachamaru127/claude-code-harness repository structures its automation logic around a declarative 3-layer Skill/Workflow/Profile architecture documented in docs/ARCHITECTURE.md. This design cleanly separates what the system does (Skills), how actions are coordinated (Workflows), and where behavior is configured (Profiles). Understanding these boundaries is essential for extending the harness or debugging execution flows.

The Three-Layer Stack

The architecture organizes runtime behavior into hierarchical dependencies: Profiles reference Workflows, and Workflows use Skills. Each layer serves a specific purpose in the automation lifecycle.

Profile Layer (Global Configuration)

The Profile layer serves as the system entry point, defining global plugin configuration, safety policies, and the mapping of commands to workflow files. According to the architecture diagram in docs/ARCHITECTURE.md, the Profile node references the Workflow layer directly.

Key artifacts include profiles/claude-worker.yaml and .claude-code-harness.config.yaml. These files specify which workflows bind to which commands, which skill categories are allowed, and safety-related settings like branch protection and sandboxing rules. This layer enforces global constraints before any workflow executes, preventing unauthorized operations at the configuration level rather than runtime.

Workflow Layer (Orchestration)

Workflows encode the ordered execution of development phases, listing the Skills that must run along with conditions for branching, error handling, and guards. The architecture diagram shows the Workflow layer using the Skill layer, establishing a clear dependency chain.

Representative files include plan.yaml, work.yaml, review.yaml, and init.yaml. Each workflow file defines steps that reference specific skills by name, passing arguments and defining failure modes. For example, the planning workflow might invoke harness-setup, then harness-plan, then harness-sync, with conditional branches based on step outcomes. This layer determines the sequencing and error recovery strategy without containing business logic itself.

Skill Layer (Atomic Operations)

Skills are self-contained knowledge units that implement concrete operations such as "create a plan," "run a review," or "sync status." Located in skills/<skill-name>/SKILL.md files (such as skills/harness-plan/SKILL.md and skills/harness-review/SKILL.md), each skill contains both Claude/Codex front-matter fields and Harness-specific design metadata.

The Skill layer acts as the atomic building block of the system. Each SKILL.md file exposes design metadata including kind, purpose, trigger, shape, role, base, and pair fields that satisfy CI gates and enable runtime introspection. Skills declare their allowed tools (e.g., Read, Write, Edit, Bash) and whether the model may invoke them automatically via the disable-model-invocation flag. Core workflow skills must expose the full metadata set defined in the Skill Orchestration Design Contract to pass validation.

Layer Interaction and Data Flow

The three layers interact through explicit reference chains that maintain strict boundaries.

Profile → Workflow: The profile file tells the harness which workflow to invoke for a given command. For instance, the harness-plan command maps to plan.yaml according to the binding definitions in the profile configuration.

Workflow → Skill: The workflow file lists ordered skills to execute, such as harness-plan followed by harness-sync. Conditional branches can select different skills based on previous step outcomes, enabling dynamic execution paths without hardcoding logic in the profile layer.

Skill → Runtime: Each skill's front-matter determines discoverability, allowed tools, and invocation permissions. The Harness runtime loads the skill definition, validates it against the design contract, and executes the contained logic with the specified constraints.

Implementation Examples

Skill Definition with Design Metadata

The following example from skills/harness-plan/SKILL.md demonstrates the required front-matter structure:

---
name: harness-plan
description: "Research-backed, team-validated task planning and Plans.md management."
kind: workflow
purpose: "Maintain co-required planning output for spec.md and Plans.md"
trigger: "create a plan, add tasks, update Plans.md, check progress"
shape: workflow
role: generator
pair: harness-sync
owner: harness-core
since: "2026-05-05"
allowed-tools: ["Read","Write","Edit","Bash","Grep","Glob","WebSearch","Task"]
user-invocable: true
effort: medium
---

This metadata enables the workflow layer to identify the skill's purpose (purpose), activation patterns (trigger), and compatible pairing (pair) with other skills like harness-sync.

Workflow Orchestration YAML

Workflow files define execution sequences through declarative step definitions. A conceptual plan.yaml illustrates the orchestration pattern:

steps:
  - name: initialise
    skill: harness-setup
    on-failure: abort
  - name: generate-plan
    skill: harness-plan
    args: "create"
    on-success: verify-plan
  - name: verify-plan
    skill: harness-sync
    args: "--no-retro"
    on-success: complete
  - name: complete
    action: echo "Planning phase finished."

Each step references a skill by name, defines arguments (args), and specifies transition behaviors (on-success, on-failure).

Profile Configuration

The Profile layer enforces global safety and orchestration settings in .claude-code-harness.config.yaml:

safety:
  protected_branch_push: ask

review:
  codex:
    enabled: true
    timeout_ms: 60000
  mode: codex

orchestration:
  advisor_ttl_seconds: 600

This configuration establishes sandboxing rules (protected_branch_push: ask), review timeouts, and advisor caching policies that apply across all workflows.

Key Design Benefits

This 3-layer architecture delivers specific operational advantages:

• Reusability: Skills can be shared across multiple workflows without modification. The same harness-review skill executes in both the review and breezing workflows, ensuring consistent behavior across different execution contexts.
• Safety: Profiles enforce global safety policies before any workflow runs. Branch protection and sandboxing configurations act as gatekeepers at the entry point, preventing unsafe operations from reaching the execution layer.
• Extensibility: New workflows can be added by composing existing skills or introducing new ones without touching the profile layer. Developers can extend automation capabilities by adding SKILL.md files and referencing them in new workflow YAML files.

Summary

• The Profile Layer (profiles/claude-worker.yaml, .claude-code-harness.config.yaml) defines global configuration, safety policies, and command-to-workflow mappings as the system entry point.
• The Workflow Layer (plan.yaml, work.yaml, init.yaml) orchestrates ordered skill execution with branching logic and error handling, referencing skills by name.
• The Skill Layer (skills/<name>/SKILL.md) provides atomic, self-contained operations with rich metadata (purpose, trigger, shape, role) that satisfy the Skill Orchestration Design Contract.
• Layer interactions follow a strict dependency chain: Profiles reference Workflows, Workflows use Skills, and Skills provide runtime execution logic.
• This separation enables reusability of skills across workflows, safety enforcement at the configuration level, and extensibility without modifying core profile settings.

Frequently Asked Questions

What is the difference between a Workflow and a Skill?

A Skill is an atomic operation defined in a SKILL.md file with specific metadata describing its purpose, triggers, and allowed tools. A Workflow is an orchestration file (like plan.yaml) that sequences multiple skills, handles error states, and manages transitions between steps. Workflows reference skills by name but do not contain implementation logic, while skills contain the actual operational code and metadata.

How does the Profile layer enforce safety?

The Profile layer enforces safety through configuration settings in files like .claude-code-harness.config.yaml before any workflow executes. It specifies policies such as protected_branch_push: ask to require confirmation before pushing to protected branches, defines sandboxing rules, and controls which skill categories are permitted. This ensures global safety constraints apply regardless of which workflow or skill runs.

Can Skills be shared across different Workflows?

Yes, skills are designed for reuse across multiple workflows. For example, the harness-review skill defined in skills/harness-review/SKILL.md can be invoked by both the review.yaml workflow and the breezing workflow without modification. This composability allows developers to build new automation sequences by combining existing atomic operations rather than duplicating code.

Where is the 3-layer architecture documented in the repository?

The architecture diagram and textual explanation reside in docs/ARCHITECTURE.md at the repository root. This document contains the Mermaid diagram illustrating the Profile → Workflow → Skill dependency chain and defines the Skill Orchestration Design Contract that governs metadata requirements for core workflow skills.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}