The Three Main File Types in the humanlayer/skills Repository

The humanlayer/skills repository organizes its automation framework around three core file formats: Markdown (*.md) for documentation and skill specifications, YAML (*.yml/*.yaml) for GitHub Actions workflow definitions, and TypeScript (*.ts) for helper scripts that execute the procedural logic.

The humanlayer/skills repository provides a structured collection of reusable automation skills designed to integrate with CI/CD pipelines. Understanding how these three file types interact is essential for implementing or extending the repository's agentic capabilities.

Markdown Files: Skill Specifications and Documentation

Markdown (*.md) files form the declarative backbone of the repository, containing all human-readable documentation and skill specifications. Each skill exposes a SKILL.md file that describes the command, its parameters, and usage examples, making the skill discoverable and usable without inspecting implementation details.

In the design-control-loop skill, the specification resides at plugins/design-control-loop/skills/design-control-loop/SKILL.md. This file defines the skill's interface and expected inputs. The top-level README.md provides a comprehensive overview of available skills and general usage guidelines for the repository.

YAML Files: GitHub Actions Workflow Definitions

YAML (*.yml and *.yaml) files define the GitHub Actions workflows that execute skills within CI/CD contexts. Each skill includes a workflow template that users can copy into their own repositories to trigger automated runs.

The design-control-loop skill includes a reference template at plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml. This configuration specifies job runners, environment variables, and the exact steps required to invoke the skill. These YAML definitions enable fully automated, repeatable execution of complex agentic tasks across different repositories.

TypeScript Files: Automation Logic and Helper Scripts

TypeScript (*.ts) implements the procedural logic required by workflows, handling prompt generation, response parsing, and pull request manipulation. These scripts are executed directly by the CI runner using Bun, rather than being pre-compiled to JavaScript.

The core agent-iteration.ts script, located at plugins/design-control-loop/skills/design-control-loop/references/agent-iteration.ts, builds prompts, parses agent output, and updates PR bodies programmatically. When the GitHub Actions workflow runs, it invokes these TypeScript files to drive the agentic iteration loop.

How the Three File Types Work Together

The three formats create a complete automation pipeline: Markdown provides the interface specification, YAML provides the orchestration layer, and TypeScript provides the executable logic.

When a workflow triggers, the runner defined in the YAML configuration reads the skill specification from the Markdown file and executes the TypeScript helper scripts. For example, a workflow step invokes the agent logic using Bun:

bun .github/scripts/agent-iteration.ts \
    --command prompt \
    --workflow design-control-loop \
    --memory .github/agent-memory/design-control-loop.md \
    --repo ${{ github.repository }} \
    --pr-number ${{ github.event.pull_request.number }} \
    --comment-body "$COMMENT_BODY"

The TypeScript script can reference the SKILL.md file to understand the command structure:

import { readFile } from 'fs/promises';

async function showSkillDoc(skill) {
  const path = `plugins/${skill}/skills/${skill}/SKILL.md`;
  const doc = await readFile(path, 'utf8');
  console.log(doc);
}
showSkillDoc('design-control-loop');

A typical GitHub Actions workflow that ties these components together looks like this:

# .github/workflows/design-control-loop.yml

name: Run Design Control Loop
on:
  workflow_dispatch:
jobs:
  run-skill:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Invoke skill via npx
        run: npx skills add humanlayer/skills --skill design-control-loop

Summary

• Markdown (*.md) files store skill specifications and documentation, with each skill exposing a SKILL.md that defines its command syntax and parameters.
• YAML (*.yml/*.yaml) files provide GitHub Actions workflow templates that orchestrate skill execution within CI/CD pipelines.
• TypeScript (*.ts) files contain the automation logic, including prompt building and PR manipulation, executed via Bun in the CI environment.
• The three file types work sequentially: YAML triggers the workflow, TypeScript executes the logic, and Markdown provides the specification.

Frequently Asked Questions

What is the purpose of the SKILL.md file in the humanlayer/skills repository?

The SKILL.md file serves as the canonical documentation and specification for a particular skill. Located within each skill's directory (such as plugins/design-control-loop/skills/design-control-loop/SKILL.md), it describes the command syntax, expected parameters, and usage examples. This allows both humans and automated systems to understand how to invoke the skill correctly without reading the implementation code.

How are TypeScript scripts executed in the humanlayer/skills workflows?

TypeScript scripts are executed directly by the Bun runtime within the GitHub Actions CI environment. The workflow YAML files invoke commands like bun .github/scripts/agent-iteration.ts with specific arguments for the workflow context, repository name, and PR number. This approach allows for rapid execution of helper scripts that manage prompt generation and PR updates.

Can I run a skill without using the provided YAML workflow template?

While the YAML workflow templates provide the standard method for GitHub Actions integration, you could theoretically invoke the underlying logic manually. However, you would need to replicate the environment setup and execute the TypeScript scripts with the correct parameters yourself, as the YAML files define the specific orchestration and context required to run the skills properly.

Where does the agent-iteration.ts script fit into the skill execution flow?

The agent-iteration.ts script, located at paths like plugins/design-control-loop/skills/design-control-loop/references/agent-iteration.ts, acts as the engine that drives the agentic loop. It is called by the GitHub Actions workflow to build prompts from the skill specification, parse the agent's output, and update pull request bodies or comments based on the results. This TypeScript file bridges the gap between the declarative YAML workflow and the actual automation behavior.

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