Summary
Allow skills to be defined inline within agents.yaml so that a single file (or remote URL) is all that's needed to run a fully functional agent: no local skill imports, no repository scaffolding required.
Motivation
Currently, using skills with an agent requires either:
- placing skill files in the user's home folder, or
- including them in the current project repository
This creates friction when sharing agents across machines, teams, or environments. The dream is to be able to run:
docker-agent run https://<remote_agent_specs>
from any machine, and have the agent work exactly as intended, no setup, no file hunting.
Proposed Solution
Extend the agents.yaml schema to support an inline skills block where skill logic can be embedded directly:
agents:
root:
skills:
- name: summarize
inline: |
You are a summarization expert. Given any text, return a concise summary...
- name: code-reviewer
inline: |
Review the following code for bugs, style issues, and performance...Alternatively (or additionally), support referencing remote skill URLs alongside inline definitions:
skills:
- name: summarize
source: https://skills.example.com/summarize.yamlAnd/or top-level skills definitions, similarly to OpenAPI specs?
skills:
- name: summarize
source: https://skills.example.com/summarize.yaml
agents:
root:
skills:
- name: summarize
ref: '#/skills/summarize'
Schema Naming Conflict
The skills field feels like a natural fit for this feature but it likely collides with the existing behavior of the field (skill discovery / import path resolution). To avoid a breaking change and make the distinction explicit, the current field would be renamed to something like skillsDiscovery (open to bikeshedding):
agents:
root:
skillsDiscovery: true # additionally look skills found from local dirs
skills:
- name: summarize
inline: |
...This gives skills an intuitive, declarative meaning ("these are the skills this agent has") while skillsDiscovery clearly conveys the path-resolution/import mechanism.
Goals
agents.yaml becomes a fully portable, self-contained artifactdocker-agent run <url> works end-to-end with zero local dependencies
Summary
Allow skills to be defined inline within
agents.yamlso that a single file (or remote URL) is all that's needed to run a fully functional agent: no local skill imports, no repository scaffolding required.Motivation
Currently, using skills with an agent requires either:
This creates friction when sharing agents across machines, teams, or environments. The dream is to be able to run:
from any machine, and have the agent work exactly as intended, no setup, no file hunting.
Proposed Solution
Extend the
agents.yamlschema to support an inlineskillsblock where skill logic can be embedded directly:Alternatively (or additionally), support referencing remote skill URLs alongside inline definitions:
And/or top-level
skillsdefinitions, similarly to OpenAPI specs?Schema Naming Conflict
The
skillsfield feels like a natural fit for this feature but it likely collides with the existing behavior of the field (skill discovery / import path resolution). To avoid a breaking change and make the distinction explicit, the current field would be renamed to something likeskillsDiscovery(open to bikeshedding):This gives
skillsan intuitive, declarative meaning ("these are the skills this agent has") whileskillsDiscoveryclearly conveys the path-resolution/import mechanism.Goals
agents.yamlbecomes a fully portable, self-contained artifactdocker-agent run <url>works end-to-end with zero local dependencies