Skills

Skills provide specialized instructions that agents can load on demand when a task matches a skill's description.

How Skills Work

1. docker-agent scans standard directories for SKILL.md files
2. Skill metadata (name, description) is injected into the agent's system prompt
3. When a user request matches a skill, the agent reads the full instructions
4. The agent follows the skill's detailed instructions to complete the task

Enabling Skills

agents:
  root:
    model: openai/gpt-4o
    instruction: You are a helpful assistant.
    skills: true
    toolsets:
      - type: filesystem # required for reading skill files

Tip

Skills are perfect for encoding team-specific workflows (PR review, deployment, coding standards) that apply across projects.

Filtering Skills

The skills field also accepts a list, letting you restrict the agent to a specific subset of skills instead of exposing every discovered one. List items are classified automatically:

• "local" or any http:// / https:// URL → a source to load skills from
• any other string → the name of a skill to include

When only names are given, local sources are used by default.

agents:
  # Load every discovered local skill (same as `skills: true`).
  full:
    skills: true

  # Load local skills, but only expose "commit" and "poem".
  scoped:
    skills:
      - commit
      - poem

  # Combine an explicit source with a name filter.
  remote_filtered:
    skills:
      - https://skills.example.com
      - commit

  # Disable skills entirely.
  none:
    skills: false

A name that doesn't match any discovered skill is logged as a warning at startup but is otherwise ignored.

Inline Skills

Instead of (or alongside) loading skills from files and URLs, you can define skills directly in the agent config. An inline skill is a mapping item in the skills list, freely mixed with the string items above:

agents:
  root:
    model: openai/gpt-4o
    instruction: You are a helpful assistant.
    skills:
      - name: changelog
        description: Write a concise changelog entry from a diff or description.
        instructions: |
          Produce a single changelog entry in Keep a Changelog style.
          Pick the right category (Added, Changed, Fixed, Removed) and write
          one imperative sentence summarising the user-visible change.

      # A fork-mode inline skill runs in an isolated sub-agent.
      - name: triage
        description: Triage a bug report in an isolated context.
        context: fork
        instructions: |
          Restate the problem, list likely root causes most-probable-first,
          and propose the smallest reproduction and next concrete action.

      # Inline skills mix freely with sources and name filters.
      - local
    toolsets:
      - type: filesystem

Inline skills carry their body in the config itself, so they need no SKILL.md file and require no filesystem source. They are always exposed — the name filter only applies to file- and URL-based skills. Because inline skills travel inside the agent YAML, they also work in --sandbox mode without any kit staging, and they can be shared with the agent via share push.

Inline Skill Fields

Note

Inline vs. file-based skills

Inline skills support the subset of the SKILL.md format that fits in YAML. They cannot bundle supporting files (no read_skill_file) or use !`command` expansion. For skills that need bundled resources or executable helpers, use a SKILL.md directory instead.

SKILL.md Format

---
name: create-dockerfile
description: Create optimized Dockerfiles for applications
license: Apache-2.0
metadata:
  author: my-org
  version: "1.0"
---

# Creating Dockerfiles

When asked to create a Dockerfile:

1. Analyze the application type and language
2. Use multi-stage builds for compiled languages
3. Minimize image size by using slim base images
4. Follow security best practices (non-root user, etc.)

Frontmatter Fields

Running a Skill as a Sub-Agent

By default, when an agent invokes a skill it reads the instructions inline into its own conversation. For complex, multi-step skills this can consume a large portion of the agent's context window and pollute the parent conversation with intermediate tool calls.

Adding context: fork to the SKILL.md frontmatter tells the agent to run the skill in an isolated sub-agent instead:

---
name: bump-go-dependencies
description: Update Go module dependencies one by one
context: fork
---

# Bump Dependencies

1. List outdated deps
2. Update each one, run tests, commit or revert
3. Produce a summary table

When the agent encounters a task that matches a context: fork skill, it uses the run_skill tool instead of read_skill. This:

• Spawns a child session with the skill content as the system prompt and the caller's task as the user message
• Isolates the context window — the sub-agent has its own conversation history, so lengthy tool-call chains don't eat into the parent's token budget
• Folds the result — only the sub-agent's final answer is returned to the parent as the tool result
• Inherits the parent's model and tools — the sub-agent can use all tools available to the parent agent (scope this with allowed_tools / toolsets, see Scoping a fork skill's tools)

Tip

When to use context: fork

Use context: fork for skills that involve many steps, heavy tool usage, or that should not clutter the main conversation — for example dependency bumping, large refactors, or code generation pipelines.

Overriding the model for a fork skill

Fork skills can declare a model field in their frontmatter to use a different model than the parent agent for the duration of the sub-session. This is useful when a skill is best handled by a faster, cheaper, or more specialised model — for example a powerful reasoning model for refactors, or a fast model for routine bookkeeping work. The override only applies while the skill is running; the parent agent keeps its own model.

The model value accepts either a named model from the agent config or an inline provider/model reference (and the same comma-separated alloy syntax as the rest of the agent config):

---
name: bump-go-dependencies
description: Update Go module dependencies one by one
context: fork
model: openai/gpt-4o-mini
---

# Bump Dependencies

1. ...

If the model reference cannot be resolved (unknown name, missing credentials, runtime not configured for model switching, …) the skill falls back to the agent's currently-active model (its configured default, or any override the user previously set via the model picker) and a warning is logged.

When the skill completes, the agent's previous model is restored — but only if no one else changed the model in the meantime. If the user switches the model via the TUI model picker while the fork skill is running, their choice is preserved (the deferred restore becomes a no-op).

Scoping a fork skill's tools

By default a fork skill inherits the parent agent's entire tool set. Two optional fields let you scope what the sub-session can use. Both apply only to fork-mode skills and work the same whether the skill is inline or loaded from a SKILL.md file.

allowed_tools (frontmatter: allowed-tools) is an allow-list over the inherited tools: only tools whose names match an entry are kept, everything else is hidden from the sub-session. Entries support glob patterns (e.g. read_*) and otherwise match exactly. This is the Claude-Code-compatible allowed-tools field, now enforced for fork skills rather than merely recorded.

toolsets references reusable top-level toolsets by name. The referenced toolsets are exposed in the sub-session in addition to the inherited tools, and they bypass the allowed_tools filter (the skill explicitly asked for them).

toolsets:
  web:
    type: fetch

agents:
  root:
    model: openai/gpt-4o
    instruction: You are a helpful assistant.
    toolsets:
      - type: filesystem
      - type: shell
    skills:
      # Inherits the parent tools but is restricted to read-only filesystem
      # access while it runs — shell and write tools are hidden.
      - name: audit
        description: Review the repository layout without modifying anything.
        context: fork
        allowed_tools:
          - read_file
          - list_directory
          - directory_tree
        instructions: Inspect the repository structure and summarise it.

      # Brings in the top-level `web` toolset on top of the parent's tools.
      - name: research
        description: Research a topic using web fetches in an isolated context.
        context: fork
        toolsets:
          - web
        instructions: Research the requested topic and summarise with links.

The equivalent in a SKILL.md file uses frontmatter lists:

---
name: research
description: Research a topic using web fetches
context: fork
allowed-tools:
  - fetch
toolsets:
  - web
---

Note

Fork only

Both fields are rejected by config validation when set on a non-fork skill, and a toolsets entry that doesn't resolve to a top-level toolset is a load-time error.

Search Paths

Skills are discovered from these locations (later overrides earlier):

Global

Project (from git root to current directory)

Invoking Skills

Skills can be invoked in multiple ways:

• Automatic: The agent detects when your request matches a skill's description and loads it automatically
• Explicit: Reference the skill name in your prompt: "Use the create-dockerfile skill to..."
• Slash command: Use /{skill-name} to invoke a skill directly

# In the TUI, invoke skill directly:
/create-dockerfile

# Or mention it in your message:
"Create a dockerfile for my Python app (use the create-dockerfile skill)"

Precedence

When multiple skills share the same name:

1. Global skills load first
2. Project skills load next, from git root toward current directory
3. Skills closer to the current directory override those further away

Skills in Sandbox Mode

When you run an agent with --sandbox, the sandbox VM has its own filesystem with no access to your host's skill directories. docker-agent handles this transparently via the auto-kit: every discovered local skill is staged into a per-agent kit on the host, run through best-effort secret redaction (see the auto-kit docs), and bind-mounted read-only into the sandbox so the agent sees the same skills inside the VM as on the host. No configuration is required — use --no-kit only if you explicitly want to run the sandbox without any host skills.

Creating a Skill

# Create the skill directory
$ mkdir -p ~/.agents/skills/create-dockerfile

# Write the SKILL.md file
$ cat > ~/.agents/skills/create-dockerfile/SKILL.md << 'EOF'
---
name: create-dockerfile
description: Create optimized Dockerfiles for applications
---

# Creating Dockerfiles

When asked to create a Dockerfile:

1. Analyze the application type and language
2. Use multi-stage builds for compiled languages
3. Use slim base images to minimize size
4. Run as non-root user for security
EOF

The skill will automatically be available to any agent with skills enabled (skills: true, or a list that targets its name — see Filtering Skills).

Note

See also

Skills are enabled in the Agent Config with the skills property (boolean or list). For tool-based capabilities, see Tools.

Example configs: examples/skills_inline.yaml (inline skill definition), examples/skills_fork_toolsets.yaml (scoping a fork skill's tools), examples/skills_filter.yaml (filtering which skills load).