Summary
Each dispatch module should ship with a SKILL.md file — an operational guide written for agents, not humans. When an agent is about to compose a job using a module, it reads the module's SKILL.md to understand what the module does, what actions are available, how to compose jobs with it, and what to watch out for.
This is distinct from README.md which is for human developers.
Why
Right now an agent working with a module has to infer its capabilities from dispatch module inspect output and job examples. SKILL.md makes the operational knowledge explicit and agent-consumable — especially important once modules are fetched from a registry and the source isn't local.
Proposed SKILL.md structure
# <module-name> — Dispatch Module
<one-paragraph domain summary>
## Actions
### `<module>.<action>`
<intent description — what it does, not what endpoint it calls>
**Payload:** field inventory with types and required/optional
**Exports:** exported fields and what they contain (if any)
**Credential:** credential profile name and what it expects (if required)
## Common job patterns
<prose or pseudocode showing how to compose jobs with this module>
## Prerequisites
<env vars required, credential setup, ordering requirements>
## Behavioral notes
<caveats, silent no-ops, partial update risks, ordering dependencies>
What needs to happen
- Convention: document
SKILL.md as a first-class module file in MODULE_AUTHORING.md
- CLI support:
dispatch module skill --name <module> prints the module's SKILL.md to stdout — so agents can consume it without knowing the install path
module inspect output: include a hasSkill: true/false field so agents know whether to fetch it
- Module authoring skills: the module implementer skill creates
SKILL.md as part of scaffolding; the module extender skill updates it when adding actions
Relationship to other ideas
Consolidates #18 (module capability cards) and #19 (generate SKILL guidance from workflows). The dispatch module skill command is the capability card surface. Workflow-based generation (#19) is a future enhancement on top of this foundation.
Future
Once the public registry exists (#26), SKILL.md travels with the published module tarball, making every community module agent-native out of the box.
Summary
Each dispatch module should ship with a
SKILL.mdfile — an operational guide written for agents, not humans. When an agent is about to compose a job using a module, it reads the module'sSKILL.mdto understand what the module does, what actions are available, how to compose jobs with it, and what to watch out for.This is distinct from
README.mdwhich is for human developers.Why
Right now an agent working with a module has to infer its capabilities from
dispatch module inspectoutput and job examples.SKILL.mdmakes the operational knowledge explicit and agent-consumable — especially important once modules are fetched from a registry and the source isn't local.Proposed
SKILL.mdstructureWhat needs to happen
SKILL.mdas a first-class module file inMODULE_AUTHORING.mddispatch module skill --name <module>prints the module'sSKILL.mdto stdout — so agents can consume it without knowing the install pathmodule inspectoutput: include ahasSkill: true/falsefield so agents know whether to fetch itSKILL.mdas part of scaffolding; the module extender skill updates it when adding actionsRelationship to other ideas
Consolidates #18 (module capability cards) and #19 (generate SKILL guidance from workflows). The
dispatch module skillcommand is the capability card surface. Workflow-based generation (#19) is a future enhancement on top of this foundation.Future
Once the public registry exists (#26),
SKILL.mdtravels with the published module tarball, making every community module agent-native out of the box.