extend

Skills & prompt templates

Skills and prompt templates are two ways to teach Squeezy how you work, and both are plain files on your disk. A skill is a folder of instructions the agent loads only when the task calls for it. A prompt template is a Markdown file whose name becomes a slash command. Nothing is downloaded, there is no registry to install from, and neither one hands the agent a power it did not already have.

contents

Skills: local instruction bundles, loaded only when relevant

A skill is a folder holding a SKILL.md file: a short YAML header that gives the skill a name, a description, and optional trigger phrases, followed by the instructions themselves in Markdown. Helper scripts and a small metadata file can sit beside it in the same folder. Drop the folder into a skills directory and Squeezy picks it up the next time it opens that workspace. There is no installer, no registry, and nothing fetched over the network. Skills are where durable guidance belongs: how to navigate an awkward module, the house style for a kind of change, the steps a particular job always needs.

The model sees a bounded catalog before loading skill bodies. An explicit /skill <name> or /<name> directive, or load_skill with activation enabled, selects a task workflow. Trigger phrases only identify candidates, including quoted or negated mentions. Reading SKILL.md or running a skill’s scripts does not activate its workflow. Instruction bodies follow the configured context budgets.

Skill instructions do not grant permissions. Skill hooks have their own opt-in and trust gates; loading guidance does not bypass those controls.

Metadata first: the roster is names and one-line descriptions, so the instructions of a skill nobody reached for are never sent.
Selected for the task: workflows survive follow-up prompts and compactions, even if their bodies are omitted from context. The exact name remains available to load_skill for recovery.
Explicit lifetime: the agent retires a completed or superseded workflow through update_skill_workflow. Its active instructions and skill hooks end; its body remains available for inspection.

Where Squeezy looks, and which copy wins

Skills use layered roots, so a shared catalog can coexist with personal guidance. Built-in skills are followed by $SQUEEZY_HOME/user/skills/, then configured extra_roots, then project .squeezy/skills/ and .agents/skills/ roots, then private Local skills. A nearer or higher-priority definition wins a duplicate name. Run squeezy skills paths to inspect the actual roots and precedence.

In a monorepo, a nested package does not have to carry its own copy. When your working directory is not itself a repository checkout, Squeezy climbs the directories above it looking for more project skill roots, and the nearest one wins. The climb stops at the first directory that is a repository checkout, so it never reaches past your repository root.

squeezy skills paths prints every directory that will be scanned, in precedence order. That is the answer when a skill you expected did not show up.
squeezy skills list prints what was actually found: each skill's name, whether it is enabled, which tier it came from, and the file it was read from.
A checked-in project config cannot add discovery roots, so cloning a repository never points Squeezy at a catalog you have not seen.

Skill hooks stay off until you turn them on

A skill's header can also declare hooks: commands that fire at points in the agent loop. Those do nothing by default. They stay inert until you set skills_enabled to true under [hooks], in settings you own, and a checked-in project config cannot set it for you. The reason for the gate is direct. A hook command runs with Squeezy's own privileges and does not pass through the rules that gate the agent's own shell commands, so enabling hooks for a catalog means trusting that catalog to run commands on your machine.

Even with the channel on, a hook declared by a skill that lives inside your workspace waits for one more step: you approve it by name with squeezy hooks trust. Hooks you wrote yourself in your own hooks file are a separate channel with a separate switch, [hooks] enabled, which is on by default.

skills_enabled is false by default, so a hooks block in a SKILL.md never runs until you opt in.
A skill hook declared inside your workspace still needs squeezy hooks trust, even once the channel is on.
squeezy hooks list shows every declared hook and its current trust status, so you can read a catalog before approving any of it.

Prompt templates: slash macros for prompts you repeat

A prompt template is a Markdown file whose name becomes a slash command, as long as that name is not already one. Save standup.md under $SQUEEZY_HOME/user/prompts/ and typing /standup expands the file into your prompt for that turn. It is the lighter counterpart to a skill. A skill hands the model instructions when a task matches; a template substitutes text you would otherwise retype, an "add tests for this" pattern, a policy reminder you want worded the same way every time.

Templates take arguments. In the body, {1} and {2} are the first and second arguments you typed after the command, a name in curly braces reads from an args list in the file's header, and {ARGUMENTS} is all of them at once. The shell spellings $1, $@ and $ARGUMENTS work too, so /test-coverage MyModule drops the module name straight into the prompt. A dollar amount in the text survives: a $50 past the last supplied argument is left as written rather than emptied.

Templates layer the way skills do. A project template under .squeezy/prompts/ shadows a personal one of the same name, and built-in commands such as /review keep their names, so a template that reuses one loads but can never be reached. Ctrl+X, T opens a picker over the same files: choose one, fill its arguments in place, and the resolved text lands in the composer for you to read before it is sent.

The filename is the command when the name is free: standup.md becomes /standup, and the file's text becomes your prompt.
Arguments substitute in: {1}, names from the header's args list, and {ARGUMENTS} for all of them, plus the shell spellings $1 and $ARGUMENTS.
Project shadows personal: a template committed under .squeezy/prompts/ overrides a same-named one in your home directory.

The built-in skills, and writing your own

Squeezy ships a set of skills inside the binary, so a fresh install already knows a number of workflows. Among them: committing changes and opening a pull request, watching one until it settles, working through review feedback, reading and repairing CI, mining git history, drafting release notes, researching on the web with cited sources, driving the isolated browser or an approved desktop window, authoring a new skill, and answering questions about Squeezy's own configuration. Each is an ordinary skill, so one of yours with the same name replaces it.

The one that shows the pattern best is trace-symbol. It answers "where is this defined, who calls it, what does it call, and what breaks if I change it" from the code knowledge database before reading raw source, and it activates on phrases like "who calls", "find references", or "blast radius". The recipe it teaches is the one the rest of Squeezy is built around: resolve the name to an exact symbol once, reuse that handle for callers, callees, references, and members instead of re-matching the bare name, then read only the exact slices the database located, never whole files. Before an edit, ask for the blast radius as a single query rather than hunting for it.

Writing your own takes three commands. squeezy skills create <name> scaffolds a SKILL.md under your personal directory, or under the repository's own with --project. squeezy skills validate checks the header and metadata of every skill it discovered and reports each error and warning. squeezy skills show <name> --dry-run prints the opening of the body the agent would be handed, without activating the skill.

the contents list reaches every page in the docs