Skills

A skill is reusable workflow instructions the agent loads on demand — never speculatively. The index (name + description) lives in the tool description the model always sees; the full body loads only when a request matches; supporting files load only when the body actually references them. This progressive disclosure means a large skill library costs almost nothing in context until a specific skill is actually used.

Layers — project wins on name

~/.visvoai/skills/<name>/SKILL.md              global
<project>/.visvoai/skills/<name>/SKILL.md      project (may be checked in)
<project>/.visvoai/skills/<name>.md            flat, single-file skill also works

Format

Frontmatter between --- lines, then the body:

---
description: Draft release notes from the git log
args:
  version: The version being released
---
1. Run `git log $version..HEAD --oneline`.
2. Group changes by type; see checklist.md for the house format.

• description is required — it's the index line the model sees before loading anything else.
• args is an optional block of named $placeholders the caller fills in; $ARGUMENTS expands to all supplied args as key: value lines. Substitution happens only in the main body read — supporting files are served verbatim, never templated.
• Everything after frontmatter is the body: the instructions the agent follows with its own tools.

Supporting files load lazily

Files next to SKILL.md (.md, .py, .js, .ts, .json, .yaml, .toml, .sh, …) are readable via the skill tool's resource argument, but only fetched when a step in the body actually points at one — nothing is loaded speculatively "in case it's needed."

A skill grants knowledge, never capability

The model reads the steps and executes them with its normal, gated tool set — an edit_file call a skill's instructions trigger still hits the same approval gate as any other edit. A skill cannot unlock a tool or bypass a permission the agent wouldn't otherwise have.

Bring your own library

Already have a skills folder (a team's shared repo, Claude Code's skill directory)? Point at it and it loads as your own trusted skills — no per-file approval, because you configured it yourself:

# ~/.visvoai/config.toml
[skills]
extra_dirs = ["~/.claude/skills", "~/dotfiles/skills"]

Trust

Project-defined skills carry the same threat model as project agents: a repo-controlled skill body is a prompt that steers tool use on your machine, so it needs one-time approval — a hash of the whole definition (description + body + args + the names of its resource files) recorded in ~/.visvoai/projects/<project-id>/skill_trust.toml. Any edit re-prompts. Global skills (yours) are implicitly trusted.

Two real examples, from simple to progressive-disclosure

Both ship in examples/ in the repo — copy either straight into ~/.visvoai/skills/.

Simple — one arg, one lazily-loaded reference file:

---
description: Draft release notes from the git log
args:
  version: The version being released (the previous tag to diff from)
---
1. Run `git log $version..HEAD --oneline` to list the changes.
2. Group them: Features, Fixes, Internal. Drop chore/noise commits.
3. Write the notes in the house format — see format.md for the rules.
4. Save to RELEASE_NOTES.md and show me the result.

Complex — classifies first, then loads only the one reference file the branch needs; the model never reads all three checklist files:

---
description: Review a pull request or diff with house rules, sized to the change
args:
  target: What to review — a PR number, branch, or "working tree"
---
## Step 1 — Classify (no file reads yet)
Look at $target: run `git diff --stat` for it and classify the change:
Output: {size: "small" (<150 changed lines) | "large", risk: "low" | "touches
auth/db/money paths"}

## Step 2 — Load ONE rules file, per the classification
- small + low risk    → read checklist-quick.md
- large OR risky      → read checklist-deep.md
- if the diff touches SQL/migrations, ALSO read sql-rules.md (only then)

## Step 3 — Review
Read the diff hunk by hunk against the loaded checklist. For each finding:
file:line, severity (blocker/major/nit), one-line why, concrete fix.

## Step 4 — Report
Findings ordered by severity, then a verdict: approve / approve-with-nits /
request-changes. State what you did NOT review (paths, generated files).

pr-review/ ships three checklists next to SKILL.md (checklist-quick.md, checklist-deep.md, sql-rules.md) — a small diff to a config file loads one ~4-line file; a large change touching a migration loads two. Nothing is read speculatively.