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 spec.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 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 reference is a bare name (no / or .md suffix), InitRunner searches these directories in priority order:

The --skill-dir CLI option takes precedence over INITRUNNER_SKILL_DIR. Both are checked before the global ~/.initrunner/skills/ directory.

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 spec.role 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 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.

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 spec.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 spec.skills references only.

Configuration

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

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

To disable auto-discovery:

spec:
  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 spec.skills are excluded by resolved path to avoid duplication

Interaction with Explicit Skills

Explicit skills (listed in spec.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 spec.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 init --template skill --name web-research

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

--skill-dir Option

The --skill-dir option is available on validate and run commands. It adds an extra directory to the skill search path.

initrunner run role.yaml -i --skill-dir ./shared-skills
initrunner run role.yaml --daemon --skill-dir /opt/skills
initrunner run role.yaml --serve --skill-dir ./shared-skills

INITRUNNER_SKILL_DIR Environment Variable

Set INITRUNNER_SKILL_DIR to permanently add an extra skill search directory. It has lower precedence than --skill-dir but higher precedence than ~/.initrunner/skills/.

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:

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"

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

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: auto-skill-demo
  description: Demonstrates auto-discovered skills with progressive disclosure
spec:
  role: |
    You are a helpful assistant. Use your available skills when they match the task.
  model:
    provider: openai
    name: gpt-5-mini
  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