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

The design-control-loop skill uses ten reference files in its references/ folder: control-loop-taxonomy.md, example-control-loop.md, agent-runner-templates.md, workflow-template.yml, prompt-template.md, memory-template.md, skill-template.md, response-template.md, example-skill.md, and 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 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 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 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 file specifies the boilerplate for 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 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 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 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 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 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 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.

// 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, example-control-loop.md
C–D	Component generation	skill-template.md, response-template.md, example-skill.md, agent-runner-templates.md
E	Workflow orchestration	workflow-template.yml, prompt-template.md
F–G	Feedback loop	memory-template.md, 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 specification directs the agent to read specific references:

## 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 with environment-specific values:

# 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 establishes core concepts: set point, sensor, controller, actuator, and disturbances.
• Template files (skill-template.md, prompt-template.md, workflow-template.yml, memory-template.md, response-template.md) provide reusable boilerplate for generating loop components.
• Example files (example-control-loop.md, example-skill.md) demonstrate proper implementation without serving as copy-paste templates.
• agent-runner-templates.md documents CLI invocations for multiple coding agents with secret handling.
• 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 illustrates control loop mechanics as a teaching aid—it shows how components interact but isn't meant for direct reuse. 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 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 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. This allows ongoing tuning without requiring a complete loop redesign.

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