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. As of v1.26, skills placed in well-known directories are auto-discovered and made available to agents via progressive disclosure — no explicit skills entry required.

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

Standard agentskills.io fields:

InitRunner extensions:

Unknown frontmatter fields are silently ignored (extra="ignore") to maintain compatibility with community SKILL.md files that may include additional fields.

Body

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

Referencing Skills

Add skill paths to skills in your role YAML:

name: research-assistant
model:
  provider: openai
  name: gpt-4o-mini
prompt: |
  You are a research assistant. Use your skills to help
  the user find and summarize information.
skills:
- ./skills/web-research/SKILL.md
- ./skills/summarizer/SKILL.md
- data-analysis

Resolution Order

When a skill reference is a bare name (no / or .md suffix), InitRunner searches these directories in priority order:

Where both apply, the --skill-dir option takes precedence over INITRUNNER_SKILL_DIR, and the env directory is still searched. Both are checked before the global ~/.initrunner/skills/ directory. initrunner run reads only the environment variable.

Absolute and explicit relative paths (starting with ./ or /, or ending with .md) are resolved directly relative to the role file's directory.

How Merging Works

When an agent loads skills, two things happen:

1. Prompt merging — the skill's Markdown body is appended to prompt as an additional section, separated by a header
2. 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 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.

Auto-Discovered Skills (Progressive Disclosure)

InitRunner supports automatic skill discovery following the agentskills.io progressive disclosure model. Skills placed in well-known directories are automatically found and made available to agents without explicit skills configuration.

How It Works

Auto-discovery uses a three-tier model:

The model decides when to activate a skill based on catalog descriptions. The catalog is injected into the system prompt as a lightweight list. When the model determines a task matches a skill's description, it calls the activate_skill tool to load the full instructions.

Discovery Paths

Paths are resolved relative to role_dir (the role file's parent directory):

Higher-priority scopes override lower-priority scopes on name collision. A warning is logged when shadowing occurs.

Only directory format ({name}/SKILL.md) is supported for auto-discovery. Flat .md files remain available for explicit skills references only.

Configuration

Auto-discovery is enabled by default. Configure it in your role YAML:

auto_skills:
  enabled: true    # default: true
  max_skills: 50   # default: 50, max: 200

To disable auto-discovery:

auto_skills:
  enabled: false

Scanning Rules

• Directories like .git/, node_modules/, __pycache__, .venv, dist are skipped
• Only 1 level deep inside each skills dir (only {name}/SKILL.md, no recursive nesting)
• Total discovered skills capped at max_skills (default 50)
• Skills without a description in frontmatter are skipped
• Skills already referenced in skills are excluded by resolved path to avoid duplication

Interaction with Explicit Skills

Explicit skills (listed in skills) are loaded eagerly with their full prompt and tools merged into the agent at build time. Auto-discovered skills are lazy — only their name and description are injected initially.

If a skill is both explicitly referenced and present in an auto-discovery directory, the auto-discovery system skips it (deduplication by resolved file path).

Trust Model

Project-level skills ({role_dir}/.agents/skills/) are loaded with the same trust as the role file itself. InitRunner already executes the role's system prompt and tool configs from the same directory, so project-level skills do not expand the trust boundary.

Non-Reproducibility

Auto-discovered skills are ambient capabilities by design. Two machines with different installed skills see different catalogs. This is consistent with the agentskills.io model (skills are like extensions/plugins).

• Bundles: only include explicit skills, not auto-discovered skills
• Daemon hot-reload: only watches explicit skill refs; auto-skill directory changes require daemon restart

Security

• The role's SecurityPolicy applies to all tools, including those contributed by skills. Skills cannot weaken or bypass security policies.
• Skills cannot nest — the SkillFrontmatter schema does not include a skills field, so a skill cannot reference other skills.
• Tool sandbox restrictions (blocked modules, MCP command allowlists, sensitive env prefixes) apply uniformly regardless of whether a tool came from a skill or the role itself.
• The activate_skill meta-tool is a privileged tool that bypasses policy/permission wrapping. It only reads SKILL.md files from paths pre-discovered by the harness at build time (not user-controlled input). This is the same trust model as the search_tools meta-tool.

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                           # explicit skills only
initrunner skill list --auto                    # auto-discovered skills only
initrunner skill list --all                     # both explicit and auto-discovered
initrunner skill list --auto --role role.yaml   # auto-discover relative to role
initrunner skill list --skill-dir ./my-skills

Lists skills discovered across search locations. Use --auto for auto-discovered skills, --all for both explicit and auto-discovered, and --role to resolve auto-discovery paths relative to a specific role file.

Scaffold a Skill

initrunner skill new web-research

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

Extra skill directories

--skill-dir adds a directory to the skill search path. It is available on validate, skill list, plan, role, doctor, a2a serve, and mcp serve.

initrunner validate role.yaml --skill-dir ./shared-skills
initrunner skill list --skill-dir ./shared-skills

For initrunner run, use the environment variable:

INITRUNNER_SKILL_DIR=./shared-skills initrunner run role.yaml -i
INITRUNNER_SKILL_DIR=/opt/skills initrunner run role.yaml --daemon

Changed in v2026.8.11: --skill-dir was removed from run. INITRUNNER_SKILL_DIR covers it, and works the same in a container or a systemd unit, where there is no command line to edit.

INITRUNNER_SKILL_DIR Environment Variable

Set INITRUNNER_SKILL_DIR to permanently add an extra skill search directory. It has lower precedence than --skill-dir on the commands that take that flag, and higher precedence than ~/.initrunner/skills/. For run it is the only option.

export INITRUNNER_SKILL_DIR=/opt/shared-skills
initrunner run role.yaml -i

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:

name: code-reviewer
description: Reviews code changes using static analysis tools
model:
  provider: openai
  name: gpt-4o-mini
  temperature: 0.0
prompt: |
  You are a senior code reviewer. When given a branch or commit range,
  review the changes and produce a structured report.
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"

Auto-Discovery Example

Place a skill in a well-known directory and it becomes available automatically:

roles/skills/summarizer/SKILL.md:

---
name: summarizer
description: Summarize long documents, articles, and threads into concise bullet points.
tools:
  - type: web_reader
---

You are a summarization specialist. When asked to summarize content:

1. Read the full source material
2. Identify key points, decisions, and action items
3. Produce a concise bullet-point summary
4. Include source references where applicable

roles/auto-skill-demo.yaml — the summarizer skill is discovered automatically from ./skills/:

name: auto-skill-demo
description: Demonstrates auto-discovered skills with progressive disclosure
model:
  provider: openai
  name: gpt-5-mini
prompt: |
  You are a helpful assistant. Use your available skills when they match the task.
auto_skills:
  enabled: true

Try it:

# List auto-discovered skills for the demo role
initrunner skill list --auto --role roles/auto-skill-demo.yaml

# Run the agent — it will see the summarizer skill in its catalog
initrunner run roles/auto-skill-demo.yaml -i