Skills and packages

A skill is a document telling the model how something is done here. It is loaded when a request falls into its area, and not before.

What a skill looks like

A markdown document with front matter carrying a name and a description. The description names the triggers: it is all the model sees until it opens the skill, so it decides whether the skill is ever used.

---
name: release
description: Cutting a release of this crate - version bump, changelog, tag, publish order
---

Bump the version in Cargo.toml first, then ...

A skill may be a single <name>.md file or a directory holding SKILL.md. A directory may carry more:

A front matter line disable-model-invocation: true hides a skill from the model, leaving it available to you as a slash command only; /skills marks such a skill as hidden from the model.

Where skills are read from

1. .revolve/skills/ and .claude/skills/ in every directory between the working directory and the repository root
2. ~/.config/task-agent/skills/
3. The installed packages

The nearest definition of a name wins, so a skill a repository carries with it beats a global one, and a package can never quietly take over a name you use. A duplicate is reported as a warning naming both sides rather than silently shadowed; /skills shows those warnings.

The global directory is seeded from ~/.claude/skills/ on first start, so a Claude Code setup is not lost.

Two ways to use one

The model calls the Skill tool by name when a request matches a description it saw in the list. You can also run a skill yourself as /<name>, which puts the same text in front of the model, with anything you typed after the name appended as your message.

Scripts inside a skill

scripts/ is what makes a skill executable without embedding a second language. A script is a markdown document whose list items are commands; RunScript executes it, and its each puts one agent on every element of a list. Loading a skill that carries scripts appends a line naming them and how to reach them, and the model is told to run the one the skill's own text calls for rather than whatever it finds. The count travels in the system prompt as scripts="2", so the model knows a skill has some before it opens it.

Where a skill came from is always visible

A skill is instructions a model is told to follow, and a script inside one is code it can be told to run, so provenance is shown everywhere a skill appears rather than being an implementation detail.

Skills that ship with the program

A few skills come with revolve and are written into the global skills directory the first time they are missing — today that is theme, which explains editing the color file. They are ordinary files afterwards: edit one and it stays edited, delete one and it stays deleted, because the name is recorded in a marker beside the directory rather than the file's presence being checked each start. That is the difference from a skill the program keeps rewriting, and it is why removing one is a decision rather than a delay.

A shipped skill carries a builtin: line in its own front matter, the way a generated one carries generated:. Deleting that line adopts the document as yours.

Letting the agent write one

/skill reads the session, looks for a workflow that repeated — steps, conventions, traps — and writes it as one document. It lands in the project's .revolve/skills/ by default and in the global directory with /skill global, and a hint after the word says what it should be about:

/skill project the release ritual

A generated skill carries a generated: line in its front matter naming the session it came from. That line is what marks it as generated, so deleting it is how you adopt the skill as your own. Every run is snapshotted first, and /skill history and /skill undo read and walk back that history the same way /refine does.

Skills that came from Claude Code

A seeded skill still describes Claude Code's tools, which is wrong here in ways that make a model hesitate or reach for something that does not exist. /onboard rewrites those documents against this program's tool list and keeps the original beside it as SKILL.claude.md. /reload re-reads the skills directory mid-session, at the cost of the prompt cache.

Packages

A package is a git repository holding one directory per skill, at its top level or under skills/. A repository that is itself a single skill carries its SKILL.md at the root.

revolve install https://example.com/team/skills.git   # into ~/.config/task-agent/packages/<name>
revolve install <url> house-style                     # under a name you choose
revolve packages                                      # what is installed, from where, at which commit
revolve update [name]                                 # git pull --ff-only, all of them or one
revolve remove <name>                                 # delete it and the skills it brought

Installing prints what arrived before anything can run: the package name, the URL, the commit, every skill with its description, every script file underneath, and the sentence that these are someone else's instructions.

Fetching shells out to the git command line rather than linking a git library, because git is already required in a repository this agent edits and it brings ssh and https credentials, submodules, shallow clones and --ff-only semantics with it. It also removes the need for a manifest: the origin URL and the commit are read back out of the clone, so there is no second copy of the truth to go stale.

Installing is a command line action on purpose. No tool exposes it, so the model cannot install a package for itself.

Project context

Beside the skills, revolve reads the global ~/.claude/CLAUDE.md and the first CLAUDE.md or AGENTS.md in each directory between the working directory and the repository root, and puts them into the system prompt. Unlike a skill, this is loaded on every turn, so it is the place for what is always true about the project rather than for what is true of one kind of task. --bare reads none of it.

The chain up to the repository root is what the session starts with; a file below the working directory is picked up when the work arrives there. Reading, writing or editing a file records the directory it sits in, and a directory reached for the first time that holds a CLAUDE.md or an AGENTS.md has it read into the prompt from the next turn on — so the rules of crates/foo stand while crates/foo is being edited, without a session started at the root having to guess they exist. It lands once rather than on every turn, a file that changed on disk replaces the copy that was read before, and one that was deleted is named as gone rather than quietly left standing. Reaching upward changes nothing: the directories above the working directory keep the startup rule.