SKILL.md Format - Agent Teams Lite

Overview

Skills in Agent Teams Lite are defined using SKILL.md files with YAML frontmatter and Markdown instructions. Each skill represents a specialized sub-agent that can be invoked by an orchestrator to perform focused tasks.

File Structure

A skill file consists of two parts:

YAML Frontmatter - Metadata and configuration
Markdown Body - Instructions, workflows, and rules

---
name: skill-name
description: >
  Brief description of what this skill does.
  Trigger: When to invoke this skill.
license: MIT
metadata:
  author: your-name
  version: "1.0"
---

## Purpose

Detailed description of the sub-agent's responsibility...

## What to Do

Step-by-step instructions...

Frontmatter Fields

string

required

Unique identifier for the skill. Used in skill invocations and file paths.Format: kebab-case (lowercase with hyphens)Example: sdd-init, sdd-propose, sdd-apply

string

required

Multi-line description with two parts:

What: Core capability of the skill
Trigger: When the orchestrator should invoke this skill

Use YAML block scalar (>) for multi-line descriptions.

description: >
  Create a change proposal with intent, scope, and approach.
  Trigger: When the orchestrator launches you to create or update a proposal for a change.

string

default:"MIT"

Open source license for the skill. Typically MIT for Agent Teams Lite skills.

object

Additional metadata about the skill.

string

Author or organization name.

string

Semantic version of the skill (e.g., "1.0", "2.0").

Body Structure

The Markdown body contains the instructions that the sub-agent will follow. Use a consistent structure:

1. Purpose Section

Define the sub-agent’s role and responsibility.

## Purpose

You are a sub-agent responsible for creating PROPOSALS. You take the exploration 
analysis (or direct user input) and produce a structured `proposal.md` document 
inside the change folder.

2. Inputs Section

Document what the sub-agent receives from the orchestrator.

## What You Receive

From the orchestrator:
- Change name (e.g., "add-dark-mode")
- Exploration analysis (from sdd-explore) OR direct user description
- Artifact store mode (`engram | openspec | none`)

3. Execution Contract

Specify how the skill interacts with persistence backends.

## Execution and Persistence Contract

Read and follow `skills/_shared/persistence-contract.md` for mode resolution rules.

- If mode is `engram`: Read and follow `skills/_shared/engram-convention.md`
- If mode is `openspec`: Read and follow `skills/_shared/openspec-convention.md`
- If mode is `none`: Return result only. Never create or modify project files.

4. Workflow Steps

Provide concrete, actionable steps.

## What to Do

### Step 1: Detect Project Context

Read the project to understand:
- Tech stack (check package.json, go.mod, pyproject.toml, etc.)
- Existing conventions (linters, test frameworks, CI)
- Architecture patterns in use

### Step 2: Initialize Persistence Backend

If mode resolves to `openspec`, create this directory structure:

openspec/ ├── config.yaml ├── specs/ └── changes/

5. Rules Section

Define constraints, best practices, and error conditions.

## Rules

- NEVER create placeholder spec files - specs are created via sdd-spec during a change
- ALWAYS detect the real tech stack, don't guess
- If the project already has an `openspec/` directory, report what exists
- Keep config.yaml context CONCISE - no more than 10 lines

Complete Example

Here’s a real skill from the Agent Teams Lite repository:

---
name: sdd-propose
description: >
  Create a change proposal with intent, scope, and approach.
  Trigger: When the orchestrator launches you to create or update a proposal for a change.
license: MIT
metadata:
  author: gentleman-programming
  version: "2.0"
---

## Purpose

You are a sub-agent responsible for creating PROPOSALS. You take the exploration 
analysis (or direct user input) and produce a structured `proposal.md` document 
inside the change folder.

## What You Receive

From the orchestrator:
- Change name (e.g., "add-dark-mode")
- Exploration analysis (from sdd-explore) OR direct user description
- Artifact store mode (`engram | openspec | none`)

## Execution and Persistence Contract

Read and follow `skills/_shared/persistence-contract.md` for mode resolution rules.

- If mode is `engram`: Read and follow `skills/_shared/engram-convention.md`. 
  Artifact type: `proposal`. Retrieve `explore` and `sdd-init/{project}` as dependencies.
- If mode is `openspec`: Read and follow `skills/_shared/openspec-convention.md`.
- If mode is `none`: Return result only. Never create or modify project files.

## What to Do

### Step 1: Create Change Directory

Create the change folder structure:

openspec/changes// └── proposal.md

### Step 2: Read Existing Specs

If `openspec/specs/` has relevant specs, read them to understand current behavior 
that this change might affect.

### Step 3: Write proposal.md

```markdown
# Proposal: {Change Title}

## Intent

{What problem are we solving? Why does this change need to happen?}

## Scope

### In Scope
- {Concrete deliverable 1}
- {Concrete deliverable 2}

### Out of Scope
- {What we're explicitly NOT doing}

## Approach

{High-level technical approach.}

## Risks

| Risk | Likelihood | Mitigation |
|------|------------|------------|
| {Risk description} | Low/Med/High | {How we mitigate} |

## Rollback Plan

{How to revert if something goes wrong.}

Step 4: Return Summary

Return to the orchestrator:

## Proposal Created

**Change**: {change-name}
**Location**: openspec/changes/{change-name}/proposal.md

### Summary
- **Intent**: {one-line summary}
- **Scope**: {N deliverables in, M items deferred}
- **Approach**: {one-line approach}

### Next Step
Ready for specs (sdd-spec) or design (sdd-design).

Rules

In openspec mode, ALWAYS create the proposal.md file
If the change directory already exists with a proposal, READ it first and UPDATE it
Keep the proposal CONCISE - it’s a thinking tool, not a novel
Every proposal MUST have a rollback plan
Apply any rules.proposal from openspec/config.yaml

## Best Practices

### 1. Use Deterministic Outputs

Skills should produce consistent, predictable results. Avoid randomness or ambiguity.

### 2. Reference Shared Conventions

Use shared documentation for cross-cutting concerns:

```markdown
Read and follow `skills/_shared/persistence-contract.md` for mode resolution rules.

3. Support Multiple Modes

Make skills work across all persistence backends:

engram: Memory-based persistence
openspec: File-based artifacts
none: Ephemeral (no writes)

4. Return Structured Results

Always return a structured envelope to the orchestrator:

Return a structured envelope with:
- `status`: success | failure | blocked
- `executive_summary`: One-paragraph summary
- `detailed_report`: Optional detailed findings
- `artifacts`: Paths or IDs of created/updated artifacts
- `next_recommended`: Suggested next command
- `risks`: Any blockers or concerns

5. Keep Instructions Concise

Sub-agents start with fresh context. Focus on:

What to do (clear steps)
How to do it (concrete examples)
Why it matters (constraints and rules)

Avoid:

Long-winded explanations
Philosophical discussions
Redundant information

Directory Structure

Skills are typically organized like this:

skills/
├── _shared/
│   ├── persistence-contract.md
│   ├── engram-convention.md
│   └── openspec-convention.md
├── sdd-init/
│   └── SKILL.md
├── sdd-explore/
│   └── SKILL.md
├── sdd-propose/
│   └── SKILL.md
├── sdd-spec/
│   └── SKILL.md
├── sdd-design/
│   └── SKILL.md
├── sdd-tasks/
│   └── SKILL.md
├── sdd-apply/
│   └── SKILL.md
├── sdd-verify/
│   └── SKILL.md
└── sdd-archive/
    └── SKILL.md

Skill Template

Use this template as a starting point for new skills:

---
name: your-skill-name
description: >
  One-line description of what this skill does.
  Trigger: When the orchestrator should invoke this skill.
license: MIT
metadata:
  author: your-name
  version: "1.0"
---

## Purpose

You are a sub-agent responsible for {CAPABILITY}. You take {INPUTS} and produce {OUTPUTS}.

## What You Receive

From the orchestrator:
- {Input 1}
- {Input 2}
- Artifact store mode (`engram | openspec | none`)

## Execution and Persistence Contract

Read and follow `skills/_shared/persistence-contract.md` for mode resolution rules.

- If mode is `engram`: {Engram-specific behavior}
- If mode is `openspec`: {File-based behavior}
- If mode is `none`: Return result only. Never create or modify project files.

## What to Do

### Step 1: {First Action}

{Instructions...}

### Step 2: {Second Action}

{Instructions...}

### Step 3: Return Summary

Return to the orchestrator:

```markdown
## {Skill Name} Complete

**Status**: {success | blocked | needs-review}

### Summary
{Key results}

### Next Step
{Recommended next action}

Rules

Rule 1: Follow the persistence contract
Rule 2: Return structured results
Return a structured envelope with: status, executive_summary, detailed_report (optional), artifacts, next_recommended, and risks

## Related Resources

<Card title="Orchestrator API" icon="diagram-project" href="/api/orchestrator-api">
  Learn how orchestrators launch sub-agents using the Task tool
</Card>

<Card title="Persistence Contract" icon="database" href="/guides/persistence">
  Understand the three persistence modes: engram, openspec, and none
</Card>

​Overview

​File Structure

​Frontmatter Fields

​Body Structure

​1. Purpose Section

​2. Inputs Section

​3. Execution Contract

​4. Workflow Steps

​5. Rules Section

​Complete Example

​Step 4: Return Summary

​Rules

​3. Support Multiple Modes

​4. Return Structured Results

​5. Keep Instructions Concise

​Directory Structure

​Skill Template

​Rules

Overview

File Structure

Frontmatter Fields

Body Structure

1. Purpose Section

2. Inputs Section

3. Execution Contract

4. Workflow Steps

5. Rules Section

Complete Example

Step 4: Return Summary

Rules

3. Support Multiple Modes

4. Return Structured Results

5. Keep Instructions Concise

Directory Structure

Skill Template

Rules