Agentskills.io Specification for Skills: The Complete Technical Guide

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 file begins with a YAML header containing name and description keys. The name must match the directory slug where the skill resides.

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

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

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) 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 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:

---
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 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

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 (per skill)	plugins/<plugin>/skills/<name>/SKILL.md	Concrete skill definition the agent reads
skill-template.md	plugins/design-control-loop/skills/design-control-loop/references/skill-template.md	Canonical markdown skeleton
example-skill.md	plugins/design-control-loop/skills/design-control-loop/references/example-skill.md	Production-ready reference
response-template.md	plugins/design-control-loop/skills/design-control-loop/references/response-template.md	Output format specification
agent-iteration.ts	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, ensuring consistent agent communication
• The humanlayer/skills repository provides reference implementations at references/skill-template.md, references/example-skill.md, and 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 file is referenced from SKILL.md but stored separately to enable reuse across skills. During execution, the agent loads both files: SKILL.md for behavior and 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.

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