> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/agent-teams-lite/llms.txt
> Use this file to discover all available pages before exploring further.
# SKILL.md Format
> Complete specification for creating Agent Teams Lite skill files
## 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:
1. **YAML Frontmatter** - Metadata and configuration
2. **Markdown Body** - Instructions, workflows, and rules
```markdown theme={null}
---
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.
```yaml theme={null}
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.
```markdown theme={null}
## 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.
```markdown theme={null}
## 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.
```markdown theme={null}
## 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.
```markdown theme={null}
## 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.
```markdown theme={null}
## 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:
```markdown theme={null}
---
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/{change-name}/
└── 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:
```markdown theme={null}
## 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:
```markdown theme={null}
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:
````markdown theme={null}
---
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
Learn how orchestrators launch sub-agents using the Task tool
Understand the three persistence modes: engram, openspec, and none
```