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

> Explore the Claude Code Harness 3-Layer Architecture: Profiles, Workflows, and Skills. Understand how this system separates concerns for efficient AI code execution and organization.

- Repository: [Chachamaru/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness)
- Tags: architecture
- Published: 2026-05-28

---

**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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/docs/ARCHITECTURE.md), the Profile node references the Workflow layer directly.

Key artifacts include [`profiles/claude-worker.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/profiles/claude-worker.yaml) and [`.claude-code-harness.config.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/plan.yaml), [`work.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/work.yaml), [`review.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/review.yaml), and [`init.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills/harness-plan/SKILL.md) and [`skills/harness-review/SKILL.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills/harness-plan/SKILL.md) demonstrates the required front-matter structure:

```yaml
---
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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/plan.yaml) illustrates the orchestration pattern:

```yaml
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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.claude-code-harness.config.yaml):

```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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/SKILL.md) files and referencing them in new workflow YAML files.

## Summary

- The **Profile Layer** ([`profiles/claude-worker.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/profiles/claude-worker.yaml), [`.claude-code-harness.config.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/plan.yaml), [`work.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/work.yaml), [`init.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/SKILL.md) file with specific metadata describing its purpose, triggers, and allowed tools. A **Workflow** is an orchestration file (like [`plan.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/skills/harness-review/SKILL.md) can be invoked by both the [`review.yaml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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.