write-terva-skill

Writing a terva skill

Use this skill when the user asks to create, add, or write a skill for terva. Skim it first, then collaborate with the user on the one skill they want and write it to the right location so terva discovers it on the next launch.

Skill vs. extension, and picking the right one first

These are different things, and asking for "a skill" should land here, NOT on write-terva-extension:

• A skill is just instructions: a SKILL.md markdown file with a short YAML header. terva loads it for the model; nothing executes. Reach for a skill to capture a repeatable workflow, house style, checklist, or domain knowledge the agent should follow ("how we cut a release", "review rules for this repo").
• An extension is code: an executable terva launches as a subprocess to add a slash command, an LLM tool, or a guard hook. Reach for an extension when you need new behavior or a new capability, not just guidance.

If the user wants the agent to know or do something by following written steps, it's a skill, so stay here. If they need a new tool, command, or hook, switch to write-terva-extension.

Anatomy of a skill

One directory per skill, containing a SKILL.md:

<skills-dir>/<name>/SKILL.md

SKILL.md is YAML frontmatter followed by a markdown body:

---
name: cut-release
description: Steps and guardrails for cutting a versioned release of this repo. Use when the user asks to release, tag, or publish a version.
---

# Cutting a release

1. ...
2. ...

Frontmatter fields:

• name (recommended). The skill id the model invokes. It defaults to the directory basename if omitted. Use kebab-case and match the directory name.
• description (required in practice). A one-line trigger. This is the ONLY part of the skill the model sees up front (see below), so phrase it as what the skill is for and when to use it, and include the words a user would say ("review", "release", "deploy"). A vague description means the skill is never reached.
• allowed-tools / permissions (optional). Parsed for compatibility with related ecosystems but advisory only in this version (not enforced). If a skill must restrict itself to certain tools, also say so in the body so the model self-regulates.
• disable-model-invocation (optional). The invocation choice, and it spends one of two budgets:
  • Context load is what always-loaded material costs the model's window. Omit this field and the skill is model-invoked: its description sits in the manifest every turn, whether or not it ever fires, in exchange for the agent reaching it unprompted and other skills being able to name it.
  • Cognitive load is what it costs you. Set it to true and the skill leaves the manifest: no per-turn cost, but you become the index who has to remember it exists. In terva the flag scopes model discovery only, so /skill <name> still loads it.