# The Three Main File Types in the humanlayer/skills Repository

> Discover the three primary file types in the humanlayer/skills repository: Markdown for documentation, YAML for workflows, and TypeScript for logic. Understand the core components of the automation framework.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: getting-started
- Published: 2026-09-12

---

**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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts) script, located at [`plugins/design-control-loop/skills/design-control-loop/references/agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/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:

```bash
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`](https://github.com/humanlayer/skills/blob/main/SKILL.md) file to understand the command structure:

```javascript
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:

```yaml

# .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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts) script, located at paths like [`plugins/design-control-loop/skills/design-control-loop/references/agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/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.