# Agentskills.io Specification for Skills: The Complete Technical Guide

> Understand the agentskills.io specification for skills. Learn about the markdown-based contract for reusable agent-driven skills, including YAML front-matter, sections, criteria, and response templates.

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

---

**The agentskills.io specification defines a markdown-based contract that every reusable, agent-driven skill must satisfy, consisting of YAML front-matter, structured sections, completion criteria, and a response template.**

The **humanlayer/skills** repository implements this specification through reference templates and example files that every skill definition follows. If you're building AI agents that interact with code repositories, understanding this specification ensures your skills are deterministic, safe, and reviewable.

## Core Elements of the Agentskills.io Specification

A compliant skill in the **humanlayer/skills** repository must include seven mandatory elements. Each element serves a specific purpose in guiding agent behavior and enabling human oversight.

### Front-Matter (YAML Block)

Every [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) file begins with a YAML header containing `name` and `description` keys. The `name` must match the directory slug where the skill resides.

```yaml
---
name: design-control-loop
description: iterate on PR feedback using a structured, checkpointed workflow
---

```

This pattern appears at lines 1–4 of [`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) and is enforced across all skill implementations.

### Title and Purpose Sections

Following the front-matter, the skill requires a human-readable H1 title and two declarative sections:

- **When to Use**: A brief paragraph describing the trigger conditions for the skill
- **Goal**: A one-sentence invariant the agent must preserve throughout execution

These sections appear in [`references/skill-template.md`](https://github.com/humanlayer/skills/blob/main/references/skill-template.md) and establish the contract between human intent and agent behavior.

### Core Requirements

The specification mandates four safety rules that every skill must enforce:

1. **Source-of-truth validation**: The agent must only edit files that are the live source of truth
2. **Input constraints**: The agent must not base changes on Git commit messages or other unreliable signals
3. **Reviewability**: Every change must be a single, inspectable diff
4. **Validation**: The skill must include an observable verification step before completion

These rules appear in the **Core Requirements** section of [`skill-template.md`](https://github.com/humanlayer/skills/blob/main/skill-template.md) and are designed to prevent common agent failure modes like hallucinated edits or untested changes.

### Workflow with Completion Criteria

The agentskills.io specification structures agent execution as a numbered workflow where **every step includes a completion criterion** that must be observable.

The standard five-step pattern from [`skill-template.md`](https://github.com/humanlayer/skills/blob/main/skill-template.md):

| Step | Action | Completion Criterion |
|:---|:---|:---|
| 1 | Find the target | The specific file/location is identified |
| 2 | Inspect the source of truth | The relevant content is captured |
| 3 | Make the smallest safe change | A single, reviewable edit is staged |
| 4 | Validate | The verification command passes |
| 5 | Format the response | Output matches [`response-template.md`](https://github.com/humanlayer/skills/blob/main/response-template.md) |

This structure ensures that agents cannot proceed blindly—each step must produce observable evidence of progress.

### Review Checklist and Response Template

Every skill concludes with two final components:

- **Review Checklist**: A markdown checkbox list confirming all rules were followed before PR submission
- **Response Template**: A separate file ([`references/response-template.md`](https://github.com/humanlayer/skills/blob/main/references/response-template.md)) defining the exact format for agent output

The response template in `humanlayer/skills` specifies PR body structure, status messages, and log formatting, ensuring consistent communication between agents and human reviewers.

## Directory Structure and File Locations

The agentskills.io specification enforces a predictable file system layout. In **humanlayer/skills**, skills are organized as follows:

```

.claude/skills/<skill-name>/
├── SKILL.md                    # Skill definition (implements the spec)

└── references/
    ├── skill-template.md       # Canonical skeleton for new skills

    ├── example-skill.md        # Production-ready reference implementation

    ├── response-template.md    # Output format specification

    └── agent-iteration.ts      # Optional helper for /iterate workflows

```

Individual plugin skills like [`plugins/improve-claude-md/skills/improve-claude-md/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/skills/improve-claude-md/SKILL.md) import and adapt this structure while maintaining compliance with the core contract.

## Practical Implementation: Minimal Skill Skeleton

Below is a complete, runnable skill that satisfies the agentskills.io specification:

```markdown
---
name: update-readme-scripts
description: synchronize README documentation with package.json scripts
---

# Update README for New npm Script

Use this skill when a developer adds a new script to `package.json` and wants the README to reflect it.

The goal is to keep the documentation in sync with the repository's executable scripts.

## Core Requirements

- The source of truth is `package.json` → `scripts`.
- Do not base the change on Git commit messages.
- The edit must be a single, reviewable diff.
- The change must pass `npm run lint`.

## Workflow

### 1. Find the target

Search `package.json` for a script that does not appear in `README.md`.

**Completion criterion**: the missing script name is identified.

### 2. Inspect the source of truth

Open the `scripts` section of `package.json` and read the command string.

**Completion criterion**: the command string is captured.

### 3. Make the smallest safe change

Insert a bullet line under the "Scripts" section of the README that mirrors the script name and description.

**Completion criterion**: the new line appears in the correct location.

### 4. Validate

Run `npm run lint`. If it fails, abort and report the blocker.

**Completion criterion**: lint passes.

### 5. Format the response

Follow the structure in `response-template.md`.

**Completion criterion**: response matches the template.

## Review Checklist

- [ ] Source of truth (`package.json`) inspected.
- [ ] Change is a single line addition.
- [ ] Lint succeeded.
- [ ] Response follows the template.

```

This skeleton demonstrates how the **agentskills.io specification** transforms vague intent into executable, verifiable agent behavior.

## Production Reference Implementation

For a fully-fleshed example, the repository provides [`references/example-skill.md`](https://github.com/humanlayer/skills/blob/main/references/example-skill.md) in the `design-control-loop` plugin. This file illustrates:

- Richer prose with domain-specific context
- Multiple completion criteria per step for complex workflows
- Concrete shell commands and file paths
- Integration with the optional `/iterate` PR comment flow via [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts)

The example skill serves as the authoritative reference when the minimal skeleton proves insufficient for your use case.

## Key Files in the Humanlayer/Skills Repository

| File | Path | Purpose |
|:---|:---|:---|
| [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) (per skill) | `plugins/<plugin>/skills/<name>/SKILL.md` | Concrete skill definition the agent reads |
| [`skill-template.md`](https://github.com/humanlayer/skills/blob/main/skill-template.md) | [`plugins/design-control-loop/skills/design-control-loop/references/skill-template.md`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/skill-template.md) | Canonical markdown skeleton |
| [`example-skill.md`](https://github.com/humanlayer/skills/blob/main/example-skill.md) | [`plugins/design-control-loop/skills/design-control-loop/references/example-skill.md`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/example-skill.md) | Production-ready reference |
| [`response-template.md`](https://github.com/humanlayer/skills/blob/main/response-template.md) | [`plugins/design-control-loop/skills/design-control-loop/references/response-template.md`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/skills/design-control-loop/references/response-template.md) | Output format specification |
| [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts) | [`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) | Helper for memory file loading in `/iterate` flows |

## Why the Agentskills.io Specification Matters

The specification delivers four critical capabilities for AI agent development:

- **Consistency**: Every skill follows the same markdown schema, enabling agents like Claude Code and OpenCode to parse and execute without custom parsing logic
- **Safety**: Core Requirements enforce that agents only modify live source-of-truth files and validate changes before submission
- **Extensibility**: New skills copy the template and adjust domain wording; the underlying contract remains stable
- **Human-in-the-Loop**: Checklists and response templates create clear hand-off points for reviewers, supporting iterative improvement without breaking execution guarantees

## Summary

- The **agentskills.io specification** is a markdown-based contract for reusable, agent-driven skills
- Seven mandatory elements: YAML front-matter, title, purpose, goal, core requirements, workflow with completion criteria, and review checklist
- The `name` in front-matter must match the directory slug for deterministic skill discovery
- Every workflow step requires an **observable completion criterion** that prevents blind execution
- Output formatting is governed by [`response-template.md`](https://github.com/humanlayer/skills/blob/main/response-template.md), ensuring consistent agent communication
- The **humanlayer/skills** repository provides reference implementations at [`references/skill-template.md`](https://github.com/humanlayer/skills/blob/main/references/skill-template.md), [`references/example-skill.md`](https://github.com/humanlayer/skills/blob/main/references/example-skill.md), and [`references/response-template.md`](https://github.com/humanlayer/skills/blob/main/references/response-template.md)

## Frequently Asked Questions

### What happens if my skill doesn't include completion criteria for each step?

The agent may proceed without verifying success, leading to cascading failures. The agentskills.io specification treats completion criteria as mandatory because they provide the only observable signal that a step succeeded. Without them, agents cannot recover from partial failures or report meaningful status to human reviewers.

### Can I extend the specification with custom sections?

Yes, but only after the mandatory elements. The specification is designed for extensibility—add domain-specific guidance, additional validation commands, or tool integrations after the **Core Requirements** and **Workflow** sections. The underlying contract (front-matter structure, completion criteria pattern, and response template) must remain intact for agent compatibility.

### How does the response template interact with the skill definition?

The [`response-template.md`](https://github.com/humanlayer/skills/blob/main/response-template.md) file is referenced from [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) but stored separately to enable reuse across skills. During execution, the agent loads both files: [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) for behavior and [`response-template.md`](https://github.com/humanlayer/skills/blob/main/response-template.md) for output formatting. This separation allows multiple skills to share the same response format or for a single skill to support multiple output contexts by referencing different templates.