Writing Skills

Skills are just directories with a SKILL.md file inside. Here's how to structure yours and what Kasetto looks for.

Directory Layout

Kasetto discovers skills from the source root and from skills/:

repo-root/
├── SKILL.md                ← discovered as repo-name skill
├── my-skill/
│   └── SKILL.md        ← discovered
├── skills/
│   ├── another-skill/
│   │   └── SKILL.md    ← discovered
│   └── third-skill/
│       └── SKILL.md    ← discovered
└── README.md           ← ignored (no SKILL.md)

Kasetto picks up:

• A top-level SKILL.md (installed using the repo name, or sub-dir basename).
• Any root-level subdirectory containing SKILL.md.
• Any skills/<name>/SKILL.md subdirectory.

Directory names are used as skill identifiers for folder-based skills.

SKILL.md Format

SKILL.md is a markdown file. YAML frontmatter is optional but gives you control over how the skill appears in kst list:

---
name: Code Reviewer
description: Reviews pull requests for common issues and style violations.
---
 
# Code Reviewer
 
Detailed instructions for the AI agent go here. This is the content that gets
installed into the agent's skill directory.

Frontmatter Fields

Both are optional. If you skip them, Kasetto parses the markdown body instead:

• Name: First # heading in the document, or the directory name if no heading exists.
• Description: First non-empty, non-heading paragraph, or "No description." if none found.

Minimal Example

No frontmatter? No problem:

# My Skill
 
You are an expert at doing X. When the user asks you to...

Kasetto uses "My Skill" as the display name and the first paragraph as the description.

Referencing Skills in Config

Reference skills by their directory name in kasetto.yaml:

skills:
  - source: https://github.com/org/skill-pack
    skills:
      - my-skill           # matches repo-root/my-skill/ or repo-root/skills/my-skill/
      - another-skill

Want everything from a source? Use "*":

skills:
  - source: ~/Development/my-skills
    skills: "*"

Custom Source Path

If a skill lives somewhere non-standard within the repo, point to it with the path field:

skills:
  - source: https://github.com/acme/monorepo
    skills:
      - name: my-skill
        path: tools/ai-skills    # looks in tools/ai-skills/my-skill/SKILL.md

Limiting Discovery to a Nested Directory

If your skills live under a nested plugin folder, set sub-dir on the source:

skills:
  - source: https://github.com/acme/agents
    sub-dir: plugins/swift-apple-expert
    skills: "*"

Kasetto treats plugins/swift-apple-expert as the source root for discovery.