Authoring a Skill

A Skill in Koda is a reusable expert methodology captured as a markdown file. Skills live in koda/skills/, are hot-reloaded from disk, and are invoked either explicitly via the /skill command or automatically by the selector when a user's query matches their triggers.

Anatomy of a skill

Every skill is one markdown file. The filename stem becomes the skill ID — code-review.md registers as code-review. A skill has three parts: YAML frontmatter, a <when_to_use> block, and a methodology body.

---
name: Software Best Practices
aliases: [boas-praticas, quality, standards]
category: engineering
tags: [solid, best-practices, refactoring, code-quality]
triggers:
  - "(?i)\\bbest\\s+practices?\\b"
  - "(?i)\\bsolid\\s+principles?\\b"
  - "(?i)\\brefactor(ing)?\\b"
priority: 45
max_tokens: 2500
instruction: "Analyze code against SOLID principles and common anti-patterns. Prioritize findings by structural impact and provide concrete refactored code, not abstract advice."
output_format_enforcement: "Format per finding as: **Principle** violated, **Location** (file:line), **Problem** (concrete impact), **Suggestion** (refactored code), **Priority** (High/Medium/Low)."
---
# Software Best Practices
You are an expert in software engineering best practices...
<when_to_use>
Apply when reviewing code quality, refactoring existing code, or when the
user asks for best practice guidance. Focus on the most impactful issues
first — not every code smell needs immediate attention.
</when_to_use>
## Approach
1. Analyze code against SOLID principles...
2. Check for common anti-patterns...
## Output Format
...

Frontmatter fields

Every field is optional — but skills with no metadata can't be auto-selected, only invoked by name. The selector leans on frontmatter to decide whether a skill applies.

Body sections

The markdown body speaks directly to the model when the skill is composed. Three conventions recur in every curated skill.

• Persona — open with a one-liner that establishes the expert role: You are an expert in …. The model adopts this framing for the duration of the task.
• <when_to_use> block — a natural language applicability statement. Crucially, it should also state when not to apply the skill: "For small features, this level of analysis is unnecessary."
• Approach + Output Format — numbered methodology steps followed by a strict output-format section that pairs with the output_format_enforcement frontmatter field.

From file to composed prompt

1. 1

   Drop a markdown file

   Create the file under koda/skills/. The directory can be overridden with the SKILLS_DIR environment variable if you ship skills from a different location.
2. 2

   The registry picks it up automatically

   SkillRegistry scans the directory on startup and every 30 seconds thereafter. Changed or new files are re-parsed — no build step, no restart.
3. 3

   The selector ranks candidates

   When a user query lands, the selector combines alias matches, trigger regex matches, and semantic embedding scores against the skill's embedding_text. Skills with requires pull their dependencies in; conflicts are filtered out.
4. 4

   The composer assembles the prompt

   The composer walks the selected skill graph, extracts the methodology sections, enforces the token budget, and layers everything under the active agent's prompt contract. The model sees the methodology first, then the user's request.
5. 5

   The runtime executes

   From this point the normal runtime pipeline takes over — provider dispatch, tool loop, persistence. The skill's output_format_enforcement travels in the prompt and shapes the response.

Invocation

Skills can be reached two ways:

• Explicit via /skill. Users type /skill <name> [question]. Without arguments the command lists every available skill.
• Automatic via the selector. When no explicit skill is named, the selector decides. Trigger regex matches and semantic similarity both contribute — a skill with strong trigger matches still needs a reasonable semantic score to win.

/skill code-review
Review packages/cli/bin/koda.mjs for security issues

Listing and discovery

Skills show up in three places: the /skill command with no arguments, the dashboard's Skills catalogue, and the /api/control-plane/skills endpoint (for programmatic listing). All three share the same registry.

Next steps

• Skill best practices — patterns from the existing skill corpus that age well and scale across agents.
• Runtime — how the composer and selector fit into the execution lifecycle.