Skills

A skill is a bundle of instructions for a particular kind of work - a review checklist, a house style, a domain’s conventions. You switch one on for the session by typing @<name> in a message, and its guidance is added to the system prompt until you turn it off.

---
description: Write commit messages in this repo's house style
---

When asked for a commit message:
- Subject: `<type>(<scope>): <imperative summary>`, 50 chars max, no period.
- Body: wrap at 72; explain why, not what. Omit for trivial changes.
- Types: feat, fix, refactor, test, docs, chore, ci.

Save that as .polyglot/skills/commit-style/SKILL.md, then switch it on:

> @commit-style
skill "commit-style" active - takes effect next turn (/skill off to clear)

> draft a commit message for the change I just made

The system prompt is fixed for the turn already in flight, so a skill applies from the next turn onward - activate it, then ask. (You can put @name in the same message as your request; just expect the skill to bite on the following turn.) /skill off clears it.

Where they load from

Path	Scope
<repo>/.polyglot/skills/<name>/SKILL.md	This project. Meant to be committed.
~/.polyglot/skills/<name>/SKILL.md	Every project.

A project skill overrides a global one with the same name. /skills lists them and marks the active one; /status has a skill: line.

The SKILL.md file

Frontmatter key	Required	Meaning
name	no	Activation name. Defaults to the directory name. Lowercase, digits, -, _.
description	recommended	One line, shown in /skills and the @ picker.

The body - everything after the frontmatter - is the instruction text, spliced into the system prompt as an ## Active skill block right after your project instructions. Capped at 16 KB.

This is the same SKILL.md layout Claude Code uses, so a skill written for one works in the other.

Bundled files

Anything else in the skill’s directory stays on disk. Reference those files from the SKILL.md body by relative path and the model reads them with read_file when it needs them - the body is the always-loaded entry point, the rest is pulled in on demand.

.polyglot/skills/api-conventions/
  SKILL.md            # "our endpoint rules are in rules.md; the OpenAPI spec is spec.yaml"
  rules.md
  spec.yaml

Commands

Command	Action
/skills	List loaded skills; * marks the active one.
/skill	Show which skill is active.
/skill off	Clear the active skill (takes effect next turn).

Headless

In -p mode, a @<name> token in the prompt activates the skill for that run:

polyglot -p "@commit-style write a message for HEAD"

Turning it off

POLYGLOT_NO_SKILLS=1 (or true) skips loading entirely - @name is then just text.