extend

Skills & prompt templates

Two lightweight ways to teach Squeezy your conventions live entirely in your filesystem: skills, instruction bundles that load only when they're relevant, and prompt templates, slash macros that expand into a prepared prompt. Both are plain files you check into a repo or keep in your home directory; neither reaches the network, and neither grants the agent any new power on its own.

Skills: local instruction bundles, loaded only when relevant

A skill is a directory with a single SKILL.md file: YAML-style frontmatter (a name, a description, and optional when-to-use notes and triggers) followed by Markdown instructions. You drop it under a skills directory, and Squeezy discovers it on startup, no installer, no registry, no remote fetch. Skills are how you hand the agent durable, project-specific guidance, the way to navigate a tricky module, the house style for a kind of change, the steps a particular task always needs.

The point is that the instructions stay out of the way until they apply. Squeezy advertises the catalog as compact metadata, one line of name and description per skill, and the full body of an inactive skill never enters a model request. A skill activates only when a trigger phrase appears in your task, when the model asks for it by name, or when you run one of its scripts; at that point Squeezy loads just that body and caches it for the session. Loading a skill only injects instructions. It does not grant tools, bypass an approval, run any shell, or change your permission policy.

Metadata first: the catalog is a short list of names and descriptions; an inactive skill's instructions are never sent.
Loaded on demand: a skill body arrives only when a trigger matches, the model requests it, or you run its script, then it's cached for the session.
Instructions only: loading a skill never adds a tool, skips an approval, or runs a command.

Shared catalogs and monorepos

Skills are layered so a team can share a catalog without overriding personal ones. Squeezy discovers skills from your home directory (personal), from extra roots you point at a shared location (extra_roots, for a team catalog kept on a mounted directory or a checked-out repo), and from a project's own .squeezy/skills/ committed with the code. Higher tiers win on a name clash: a project skill shadows a shared one, which shadows a personal one, so a repository can pin the exact guidance it needs while your own defaults still apply everywhere else.

In a monorepo, a nested package doesn't have to carry its own copy. Squeezy walks the ancestor directories above your working location for project skill roots, so a package inherits the nearest shared .squeezy/skills/ catalog from a parent. The walk stops at the repository boundary, so a package never reaches outside its own repo for instructions.

Skill hooks stay off until you trust the catalog

A skill's frontmatter can declare lifecycle hooks, shell commands that fire at points in the agent loop. Those hooks are inert by default and do nothing until you set skills_enabled to true under [hooks]. The reason for the gate is direct: a hook command runs with the same privileges as Squeezy itself, so enabling hooks for a catalog is equivalent to letting that catalog run the shell tool. Keep the gate off for any skill you didn't write or don't fully trust, and turn it on only for a catalog you control. Hooks you write yourself in a hooks file use the separate [hooks] enabled gate, which is on by default.

skills_enabled is false by default, so a SKILL.md hooks block never runs unless you opt in.
An enabled hook runs with Squeezy's own privileges, so treat enabling a catalog's hooks as trusting it with the shell.
`squeezy skills list` shows the roots scanned and which skills are enabled, so you can audit a catalog before trusting it.

Prompt templates: slash macros for prompts you repeat

A prompt template is a plain Markdown file whose name becomes a slash command when that name is not already built in. Put standup.md under $SQUEEZY_HOME/user/prompts/ and typing /standup in the TUI expands the file into your prompt for that turn. It's the lightweight counterpart to a skill: where a skill injects structured instructions into the model's context when a task matches, a template just substitutes a prepared prompt you'd otherwise retype, an "add tests for X" pattern, a policy reminder you want applied consistently.

Templates take arguments. The body can reference positional values like {1} and {2}, named values from an args list in the frontmatter, or {ARGUMENTS} for everything, with shell-style $1 and $ARGUMENTS supported too, so /test-coverage MyModule fills the module name straight into the prompt. Like skills, templates layer by scope: a project template under .squeezy/prompts/ shadows a same-named personal one, but built-in commands such as /review still take precedence.

Filename is the command when the name is unused: standup.md becomes /standup, with the file's text inserted as your prompt.
Arguments substitute in: {1}, named args, and {ARGUMENTS} (plus shell-style $1/$ARGUMENTS) fill values from what you type after the slash name.
Project shadows user: a workspace template overrides a same-named personal one for project-specific workflows.

A worked example: the built-in trace-symbol skill

Squeezy ships a set of built-in skills in the binary: GitHub workflows like publishing changes and debugging CI, web research, git history archaeology, browser and desktop control, and configuration editing. The one that shows the pattern in practice best is trace-symbol, the guidance for answering "where is this defined, who calls it, what does it call, and what breaks if I change it" with the code knowledge database before reading raw source. It activates on phrases like "who calls", "find references", or "blast radius", and it encodes a knowledge-base-first recipe so the model resolves a name to an exact symbol once and then reuses that handle.

The flow it teaches is the same one the rest of Squeezy is built around: resolve the symbol with a definition search to get a stable id, then ask the knowledge database for callers, callees, and references off that id rather than re-matching the bare name, then read only the exact slices the knowledge database located, never whole files. For an edit, it pulls callers, callees, and references into a single impact packet first, so the blast radius is a query rather than a hunt. It's a concrete template you can copy: a skill that captures a workflow once and applies it whenever the task calls for it.