Skip to main content
Both skills and roles use YAML frontmatter in their markdown files. This page documents the complete schema.

​
Skill Frontmatter (SKILL.md)

---
name: code-review                          # Required: package slug
description: "Code review checklist"       # Required: one-line summary
metadata:
  strawpot:
    dependencies:                          # Optional: skill dependencies
      - security-baseline                  #   latest version
      - git-workflow>=1.0.0                #   minimum version
      - python-testing^2.0.0              #   compatible version
      - code-style==1.5.0                 #   exact version
    tools:                                 # Optional: system tool requirements
      gh:
        description: GitHub CLI
        install:
          macos: brew install gh
          linux: apt install gh
          windows: winget install GitHub.cli
---

# Skill Title

Markdown body with instructions for the agent...

​
Fields

FieldRequiredDescription
nameYesPackage slug (unique within skills)
descriptionYesOne-line summary
metadata.strawpot.dependenciesNoFlat list of skill slugs with optional version constraints
metadata.strawpot.toolsNoSystem tool requirements

​
Role Frontmatter (ROLE.md)

---
name: implementer                           # Required: package slug
description: "Implements features"          # Required: one-line summary
metadata:
  strawpot:
    dependencies:                           # Optional: dependencies
      skills:                               #   skill dependencies
        - git-workflow>=1.0.0
        - code-review
      roles:                                #   role dependencies
        - reviewer
    default_model:                          # Optional: model configuration
      provider: claude_session
      id: claude-opus-4-6
    tools:                                  # Optional: system tool requirements
      gh:
        description: GitHub CLI
        install:
          macos: brew install gh
          linux: apt install gh
          windows: winget install GitHub.cli
---

# Role Title

Markdown body with role instructions for the agent...

​
Fields

FieldRequiredDescription
nameYesPackage slug (unique within roles)
descriptionYesOne-line summary
metadata.strawpot.dependencies.skillsNoList of skill dependencies
metadata.strawpot.dependencies.rolesNoList of role dependencies
metadata.strawpot.default_model.providerNoModel provider identifier
metadata.strawpot.default_model.idNoModel ID
metadata.strawpot.toolsNoSystem tool requirements

​
Version Specifiers

Used in dependency declarations:
FormatMeaningExample
slugLatest versiongit-workflow
slug==X.Y.ZExact versiongit-workflow==1.0.0
slug>=X.Y.ZMinimum versiongit-workflow>=1.0.0
slug^X.Y.ZCompatible (same major)git-workflow^1.0.0

​
System Tools Schema

metadata:
  strawpot:
    tools:
      <tool-name>:
        description: <string>          # What the tool is
        install:
          macos: <shell command>       # macOS install command
          linux: <shell command>       # Linux install command
          windows: <shell command>     # Windows install command
  • Tool names should match the CLI binary name (used for PATH detection)
  • Install commands run in the user’s shell
  • Only the current OS command is executed
  • Supported OS keys: macos, linux, windows

​
Key Differences: Skills vs Roles

AspectSkillsRoles
FileSKILL.mdROLE.md
Dependencies formatFlat list (skills only)Structured with skills and roles sub-keys
Model configNot supporteddefault_model field
NamespaceSeparateSeparate (same slug allowed in both)