Skip to main content

​
How skills work

1

Discovery

Docker Agent scans standard directories for SKILL.md files at startup.
2

Injection

Skill names and descriptions are injected into the agent’s system prompt so it knows what skills are available.
3

Matching

When a user request matches a skill’s description, the agent reads the full skill instructions.
4

Execution

The agent follows the skill’s detailed instructions to complete the task.

​
Enabling skills

Add skills: true to an agent config and include the filesystem toolset so the agent can read skill files: 
agents:
  root:
    model: openai/gpt-4o
    instruction: You are a helpful assistant.
    skills: true
    toolsets:
      - type: filesystem

​
SKILL.md format

Each skill is a directory containing a SKILL.md file with YAML frontmatter: 
---
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

FieldRequiredDescription
nameYesUnique skill identifier
descriptionYesShort description shown to the agent for skill matching
contextNoSet to fork to run the skill as an isolated sub-agent
allowed-toolsNoList of tools the skill needs (YAML list or comma-separated string)
licenseNoLicense identifier (e.g., Apache-2.0)
compatibilityNoFree-text compatibility notes
metadataNoArbitrary key-value pairs (e.g., author, version)

​
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 context and pollute the parent conversation. Set context: fork in the frontmatter 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
With context: fork, the agent uses the run_skill tool instead of read_skill. This:
  • Spawns a child session with the skill as the system prompt
  • Isolates the context window — the sub-agent’s tool-call chains don’t affect the parent’s token budget
  • Folds the result — only the sub-agent’s final answer is returned to the parent
  • Inherits the parent’s model and tools
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.

​
Invoking skills

Skills can be invoked in multiple ways:
  • Automatic — the agent detects when your request matches a skill and loads it automatically
  • Explicit — reference the skill name in your prompt: "Use the create-dockerfile skill to..."
  • Slash command — type /{skill-name} in the TUI
# In the TUI:
/create-dockerfile

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

​
Search paths

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

​
Global

PathSearch type
~/.codex/skills/Recursive
~/.claude/skills/Flat (immediate children only)
~/.agents/skills/Recursive

​
Project (from git root toward current directory)

PathSearch type
.claude/skills/Flat
.agents/skills/Flat (each directory from git root to cwd)

​
Precedence

When multiple skills share the same name, global skills load first, then project skills from git root toward the current directory. Skills closer to the current directory win.

​
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 is automatically available to any agent with skills: true.

Build docs developers (and LLMs) love

Get started for freeTalk to us