# reference files for the design-control-loop skill: Complete Guide to Architecture and Implementation

> Explore the reference files for the design-control-loop skill. This guide details the architecture and implementation of ten essential files within the `references/` folder for seamless integration.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: architecture
- Published: 2026-09-07

---

**The design-control-loop skill uses ten reference files in its `references/` folder: [`control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/control-loop-taxonomy.md), [`example-control-loop.md`](https://github.com/humanlayer/skills/blob/main/example-control-loop.md), [`agent-runner-templates.md`](https://github.com/humanlayer/skills/blob/main/agent-runner-templates.md), [`workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/workflow-template.yml), [`prompt-template.md`](https://github.com/humanlayer/skills/blob/main/prompt-template.md), [`memory-template.md`](https://github.com/humanlayer/skills/blob/main/memory-template.md), [`skill-template.md`](https://github.com/humanlayer/skills/blob/main/skill-template.md), [`response-template.md`](https://github.com/humanlayer/skills/blob/main/response-template.md), [`example-skill.md`](https://github.com/humanlayer/skills/blob/main/example-skill.md), and [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts).**

The **design-control-loop skill** in the `humanlayer/skills` repository provides a structured framework for building **agentic control loops**—self-managing automation pipelines where sensors detect conditions, controllers make decisions, and actuators execute changes. These reference files serve as the architectural foundation, implementation templates, and workflow orchestration scripts that guide users through an eight-phase design interview and build process.

## Control Loop Taxonomy: Core Architecture Reference

The **[`control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/control-loop-taxonomy.md)** file defines the fundamental components every control loop requires. This reference establishes the shared vocabulary used throughout the design interview.

According to the source code, it describes:

- **Set point**: The desired state or target condition
- **Sensor**: The mechanism that observes current state
- **Controller**: The decision-making logic that compares sensor output against the set point
- **Actuator**: The agent that executes corrective actions
- **Disturbances**: External factors that perturb the system

This taxonomy also includes **key questions to ask the user** during Phases A–B of the design interview, ensuring all architectural decisions are grounded in control theory principles.

## Example References: Learning from Completed Loops

Two files provide concrete illustrations of how control loops operate in practice.

### example-control-loop.md

The **[`example-control-loop.md`](https://github.com/humanlayer/skills/blob/main/example-control-loop.md)** file presents a **fully-worked example** showing how the five core components interact. Unlike template files, this serves strictly as a **teaching aid**—it demonstrates a complete loop without being copy-pasted into new implementations.

### example-skill.md

The **[`example-skill.md`](https://github.com/humanlayer/skills/blob/main/example-skill.md)** file shows an **end-to-end actuator skill** that combines all templates into production-ready form. This is the quality bar that generated skills should meet.

## Template Files: Building the Loop Components

Five template files provide boilerplate for generating the actual loop infrastructure:

### skill-template.md

The **[`skill-template.md`](https://github.com/humanlayer/skills/blob/main/skill-template.md)** file specifies the **boilerplate for [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md)**—the actuator skill that will be executed. It enforces correct front-matter structure, step sequencing, and completion criteria.

### response-template.md

The **[`response-template.md`](https://github.com/humanlayer/skills/blob/main/response-template.md)** file defines **output formatting conventions** so that agent responses can be directly used as PR bodies. This ensures consistent communication between the actuator and the code review workflow.

### prompt-template.md

The **[`prompt-template.md`](https://github.com/humanlayer/skills/blob/main/prompt-template.md)** file contains the **embedded prompt fed to the coding agent** during the actuator step. It includes required placeholders—such as `{{CONTROLLER_OUTPUT}}` and `{{MEMORY_STATE}}`—that the workflow engine populates at runtime.

### workflow-template.yml

The **[`workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/workflow-template.yml)** file provides the **skeleton GitHub Actions workflow** that wires sensor → controller → actuator together. Key features include:

- **Cadence configuration** (cron schedule or manual dispatch)
- **PR creation logic** using `peter-evans/create-pull-request`
- **Flow-control safeguards** to prevent runaway iterations

### memory-template.md

The **[`memory-template.md`](https://github.com/humanlayer/skills/blob/main/memory-template.md)** file specifies the **persistent markdown file** that carries feedback between loop runs. This enables the loop to learn from exclusions, false positives, and reviewer notes across executions.

## Agent Runner Infrastructure

### agent-runner-templates.md

The **[`agent-runner-templates.md`](https://github.com/humanlayer/skills/blob/main/agent-runner-templates.md)** file catalogs **headless command-line invocations** for various coding agents:

- **Claude Code**
- **Codex**
- **OpenCode**
- **CodeLayer**

It also documents **secret handling patterns** and techniques for **extracting the agent's response** from stdout or designated output files.

## Iteration and Feedback: Runtime Enhancements

### agent-iteration.ts

The **[`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts)** file implements the **optional `/iterate` command** on PRs. This TypeScript helper enables human reviewers to provide feedback that updates the loop's memory without requiring a full redesign.

```typescript
// From references/agent-iteration.ts
import { updateMemory } from './memory-utils';

export async function handleIterate(event) {
  const feedback = extractFeedback(event.comment);
  await updateMemory(feedback);
}

```

This closes the feedback loop between human judgment and automated execution.

## How Reference Files Map to Design Phases

The design-control-loop skill organizes work into eight phases. Here's how the reference files align:

| Phase | Activity | Primary Reference Files |
|-------|----------|------------------------|
| A–B | Design interview | [`control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/control-loop-taxonomy.md), [`example-control-loop.md`](https://github.com/humanlayer/skills/blob/main/example-control-loop.md) |
| C–D | Component generation | [`skill-template.md`](https://github.com/humanlayer/skills/blob/main/skill-template.md), [`response-template.md`](https://github.com/humanlayer/skills/blob/main/response-template.md), [`example-skill.md`](https://github.com/humanlayer/skills/blob/main/example-skill.md), [`agent-runner-templates.md`](https://github.com/humanlayer/skills/blob/main/agent-runner-templates.md) |
| E | Workflow orchestration | [`workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/workflow-template.yml), [`prompt-template.md`](https://github.com/humanlayer/skills/blob/main/prompt-template.md) |
| F–G | Feedback loop | [`memory-template.md`](https://github.com/humanlayer/skills/blob/main/memory-template.md), [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts) |
| H | Validation & testing | All files (syntax validation) |

## Practical Usage: Referencing Files in SKILL.md

When authoring a new control loop, the primary [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) specification directs the agent to read specific references:

```markdown

## Phase C – Build the actuator skill

Read the templates:
- `references/skill-template.md`
- `references/example-skill.md`
- `references/response-template.md`

Use them to create `.claude/skills/design-control-loop/SKILL.md`.

```

The generated workflow incorporates [`workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/workflow-template.yml) with environment-specific values:

```yaml

# Generated from workflow-template.yml

steps:
  - name: Run sensor
    run: ./scripts/sensor.sh
  - name: Run controller
    run: node ./controller.js
  - name: Run actuator
    env:
      CLAUDE_API_KEY: ${{ secrets.CLAUDE_API_KEY }}
    run: |
      claudecode run \
        --prompt-file references/prompt-template.md \
        --input /tmp/controller-output.json \
        --output /tmp/pr-body.md
  - name: Open PR
    uses: peter-evans/create-pull-request@v5
    with:
      title: "[Design Loop] Automated change"
      body-path: /tmp/pr-body.md

```

## Summary

- The **design-control-loop skill** contains **ten reference files** in `references/` that define control loop architecture and implementation patterns.
- **[`control-loop-taxonomy.md`](https://github.com/humanlayer/skills/blob/main/control-loop-taxonomy.md)** establishes core concepts: set point, sensor, controller, actuator, and disturbances.
- **Template files** ([`skill-template.md`](https://github.com/humanlayer/skills/blob/main/skill-template.md), [`prompt-template.md`](https://github.com/humanlayer/skills/blob/main/prompt-template.md), [`workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/workflow-template.yml), [`memory-template.md`](https://github.com/humanlayer/skills/blob/main/memory-template.md), [`response-template.md`](https://github.com/humanlayer/skills/blob/main/response-template.md)) provide reusable boilerplate for generating loop components.
- **Example files** ([`example-control-loop.md`](https://github.com/humanlayer/skills/blob/main/example-control-loop.md), [`example-skill.md`](https://github.com/humanlayer/skills/blob/main/example-skill.md)) demonstrate proper implementation without serving as copy-paste templates.
- **[`agent-runner-templates.md`](https://github.com/humanlayer/skills/blob/main/agent-runner-templates.md)** documents CLI invocations for multiple coding agents with secret handling.
- **[`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts)** implements the `/iterate` PR command for human-in-the-loop feedback.
- These references are consumed across **eight design phases** (A–H), from initial interview through validation.

## Frequently Asked Questions

### Where are the reference files for the design-control-loop skill located?

All reference files reside in `plugins/design-control-loop/skills/design-control-loop/references/` within the `humanlayer/skills` repository. This directory contains ten files covering architecture, templates, examples, and runtime helpers.

### What is the difference between example-control-loop.md and example-skill.md?

[`example-control-loop.md`](https://github.com/humanlayer/skills/blob/main/example-control-loop.md) illustrates **control loop mechanics** as a teaching aid—it shows how components interact but isn't meant for direct reuse. [`example-skill.md`](https://github.com/humanlayer/skills/blob/main/example-skill.md) provides a **production-ready actuator skill** demonstrating how templates combine into deployable form.

### How does the workflow-template.yml file get used in practice?

The skill reads [`workflow-template.yml`](https://github.com/humanlayer/skills/blob/main/workflow-template.yml) during Phase E and generates a repository-specific GitHub Actions workflow. The template includes placeholders for sensor scripts, controller logic, and actuator prompts that get populated based on the design interview results.

### What purpose does agent-iteration.ts serve in the control loop?

[`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts) implements an **optional feedback mechanism**: when a reviewer comments `/iterate` on a generated PR, this TypeScript helper extracts the feedback and updates [`memory-template.md`](https://github.com/humanlayer/skills/blob/main/memory-template.md). This allows ongoing tuning without requiring a complete loop redesign.