Skills

Skills are reusable bundles of tools and prompt instructions that can be shared across agents. Instead of duplicating tool configs and system prompt fragments in every role, you define them once in a SKILL.md file and reference them from any role YAML.

SKILL.md Format

A skill is a single Markdown file with YAML frontmatter:

---
name: web-research
description: Web research and summarization capability
tools:
  - type: http
    base_url: https://api.example.com
    allowed_methods: ["GET"]
  - type: web_reader
requires:
  env:
    - SEARCH_API_KEY
  bins:
    - curl
---

## Web Research Skill

You have web research capabilities. When the user asks you to research a topic:

1. Search for relevant sources using HTTP GET requests
2. Read and extract content from web pages
3. Synthesize findings into a concise summary with citations

Always cite your sources with URLs. Prefer recent, authoritative sources.

Frontmatter Fields

Field	Type	Default	Description
`name`	`str`	(required)	Unique skill identifier
`description`	`str`	`""`	Human-readable description
`tools`	`list`	`[]`	Tool configurations (same format as `spec.tools`)
`requires.env`	`list[str]`	`[]`	Environment variables that must be set
`requires.bins`	`list[str]`	`[]`	Binaries that must be on `$PATH`

Body

The Markdown body (everything below the frontmatter) contains prompt instructions. This text is appended to the agent's spec.role prompt when the skill is loaded.

Referencing Skills

Add skill paths to spec.skills in your role YAML:

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: research-assistant
spec:
  role: |
    You are a research assistant. Use your skills to help
    the user find and summarize information.
  model:
    provider: openai
    name: gpt-4o-mini
  skills:
    - ./skills/web-research/SKILL.md
    - ./skills/summarizer/SKILL.md
    - data-analysis

Resolution Order

When a skill path does not start with ./ or /, InitRunner resolves it by searching these directories in order:

Current working directory — ./SKILL.md or ./<name>/SKILL.md
Role file directory — relative to the role YAML file
User skills directory — ~/.initrunner/skills/<name>/SKILL.md

Absolute and relative paths (starting with ./ or /) are used as-is.

How Merging Works

When an agent loads skills, two things happen:

Prompt merging — the skill's Markdown body is appended to spec.role as an additional section, separated by a header
Tool merging — the skill's tools list is added to the agent's tool set, deduplicated by type and configuration

If multiple skills define the same tool type with identical config, only one instance is registered. Skills are merged in the order they appear in spec.skills.

Requirement Checking

Before loading, InitRunner validates requirements:

requires.env — each environment variable must be set (non-empty). Missing variables raise an error with the variable name and skill name.
requires.bins — each binary must exist on $PATH. Missing binaries raise an error listing the binary and skill name.

CLI Commands

Validate a Skill

initrunner skill validate ./skills/web-research/SKILL.md

Checks frontmatter schema, tool configs, and requirement availability. Reports errors without loading the skill into an agent.

List Available Skills

initrunner skill list

Lists all skills found in the resolution paths (current directory, ~/.initrunner/skills/).

Scaffold a Skill

initrunner init --template skill --name web-research

Creates a SKILL.md template with example frontmatter and body.

Full Example

skills/code-review/SKILL.md:

---
name: code-review
description: Code review and static analysis capability
tools:
  - type: filesystem
    root_path: .
    read_only: true
  - type: git
    repo_path: .
    read_only: true
  - type: shell
    allowed_commands: [ruff, mypy]
    require_confirmation: false
    timeout_seconds: 30
requires:
  bins:
    - ruff
    - mypy
---

## Code Review Skill

You can review code changes and provide feedback. Follow this workflow:

1. Use `git_diff` or `git_changed_files` to identify what changed
2. Read the modified files to understand the context
3. Run `ruff check .` for linting issues
4. Run `mypy .` for type errors
5. Provide a structured review with:
   - Summary of changes
   - Issues found (bugs, style, types)
   - Suggestions for improvement

Be specific — reference file names and line numbers in your feedback.

reviewer.yaml — a role that uses this skill:

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: code-reviewer
  description: Reviews code changes using static analysis tools
spec:
  role: |
    You are a senior code reviewer. When given a branch or commit range,
    review the changes and produce a structured report.
  model:
    provider: openai
    name: gpt-4o-mini
    temperature: 0.0
  skills:
    - ./skills/code-review/SKILL.md
  guardrails:
    max_tokens_per_run: 30000
    max_tool_calls: 25
    timeout_seconds: 120

initrunner run reviewer.yaml -p "Review the changes in the last 3 commits"

On this page