Skip to content

Add SKILL.md convention: per-module operational guide for agents #29

@MehmetSecgin

Description

@MehmetSecgin

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

  1. Convention: document SKILL.md as a first-class module file in MODULE_AUTHORING.md
  2. 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
  3. module inspect output: include a hasSkill: true/false field so agents know whether to fetch it
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions