Skills

A skill is a named block of instructions the model can call up when a task needs it. The model invokes a skill by name through the skill tool, and Polytoken returns the skill’s body as guidance for the work at hand. See Where Instructions Live to weigh a skill against a facet or an AGENTS.md file.

A skill uses the Agent Skills format that other tools share, so a skill you already have works as written. Polytoken reads the same files and adds an optional polytoken frontmatter key for its own controls. Polytoken accepts unquoted YAML scalar values in a skill’s metadata frontmatter and stores each value in its string form. Polytoken rejects sequences, mappings, and empty values.

Where skills live

A skill is a directory containing a SKILL.md file: triage/SKILL.md defines a skill named triage. It is a directory rather than a single file so a skill can include companion files, such as a script or a reference document, alongside its SKILL.md. The directory name is the skill’s name.

Skills go in .polytoken/skills/ in your project, or in $XDG_CONFIG_HOME/polytoken/skills/ (default: ~/.config/polytoken/skills/) for ones you want everywhere.

Polytoken also discovers skills from .agents/skills/ in your project. This is the convention shared by other AI agent tools, so skills you already have for those tools work without copying. When a skill with the same name exists in both .agents/skills/ and .polytoken/skills/, the .polytoken/skills/ version wins.

The same .agents/skills/ convention works globally: skills in ~/.agents/skills/ are discovered everywhere, and $XDG_CONFIG_HOME/polytoken/skills/ overrides them. Precedence from lowest to highest: ~/.agents/skills/, $XDG_CONFIG_HOME/polytoken/skills/, project .agents/skills/, project .polytoken/skills/.

Writing a skill

A skill needs a description in its frontmatter and a body. The description is one line; the model reads it to decide when the skill applies, so write it for that purpose. The body is the instructions themselves.

---
description: Steps for cutting a release, including the version bump and changelog.
---
To cut a release:

1. Bump the version in `Cargo.toml`.
2. Update the changelog with the changes since the last tag.
3. Open a release PR and wait for review.

Polytoken uses the body as written. To render it as a template first, as described in Templating, add a polytoken frontmatter key set to true:

---
description: Steps for cutting a release.
polytoken: true
---

The polytoken key is what turns templating on: a skill with the key set is rendered as a template, and one without it is delivered verbatim. Polytoken does not expose the transclude function in a skill body.

Polytoken controls

Set the polytoken key to true when templating is all you want. To configure tags or model invocation as well, give it an object instead; the object form enables templating just as true does.

polytoken:
  tags: [release, ops]
  disable_model_invocation: false

polytoken.tags groups skills. A facet or subagent that lists tag!release in its polytoken.skills_allow allows every skill tagged release. See Facets for how skill access works.

When polytoken.disable_model_invocation is true, Polytoken hides the skill from the model: it is not listed among the skills the model can see, and the skill tool refuses it. You invoke it yourself by referencing @skill:<name> in a prompt. Use this for a skill you want to invoke deliberately rather than let the model call on its own.

Chained skill references

A skill body may include @skill:<name> to reference another skill. Polytoken resolves chained references transitively and renders the complete chain as one instruction set. Each skill renders once, so cycles do not repeat content. The invoking scope applies its skill policy to every referenced skill. A denied, polytoken.disable_model_invocation: true, or unresolvable reference fails the whole invocation. Polytoken rejects a chain whose combined bodies exceed 64 KiB and reports the measured size instead of truncating an instruction. Polytoken caches every skill in the chain so compaction can restore every referenced body.

Frontmatter keys

Key	Type	Default	Meaning
description	string	required	Tells the model when the skill applies.
polytoken	true or object	absent	Present (as true or an object) renders the skill body as a template. Absent leaves the body verbatim.
polytoken.tags	list	none	Tags for grouping, referenced as tag!<name> in a facet’s or subagent’s skill access.
polytoken.disable_model_invocation	boolean	false	Hides the skill from the model. You invoke it with @skill:<name>.

Loading changes

Polytoken loads skills at startup and when you reload its configuration with /daemon-reload; an edit to a skill takes effect only on the next reload. If one SKILL.md file is invalid, Polytoken skips that file, shows a warning card in the TUI, and keeps loading the other skills. polytoken validate skill <path> and polytoken doctor remain strict checks when you need to diagnose and correct invalid skill files.