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
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
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.
Open source license for the skill. Typically MIT for Agent Teams Lite skills.
Additional metadata about the skill.Author or organization name.
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.
## 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:
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:
### 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>
