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

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

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

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