Skills

Skills are reusable instruction packages that let Swival load detailed guidance only when a task needs it. Instead of injecting every instruction into the base prompt, Swival uses progressive disclosure: the model sees a compact catalog first and loads a specific skill body on demand through use_skill or automatically via $skill-name mentions in user messages.

Creating A Skill

A skill lives in its own directory and must include SKILL.md. The file begins with YAML frontmatter containing name and description, followed by the full instruction body.

skills/
  deploy/
    SKILL.md
    scripts/
      deploy.sh

A typical SKILL.md file looks like this:

---
name: deploy
description: Deploy the application to production using the deploy script.
---

Run `scripts/deploy.sh` from the skill directory, check the output for errors,
and verify the deployment through the health endpoint.

The deploy script expects `DEPLOY_ENV` to be set. Use `production` for prod
and `staging` for staging.

The name field must be lowercase alphanumeric with hyphens, must match the directory name, cannot contain leading or trailing hyphens, cannot contain consecutive hyphens, and cannot exceed 64 characters. The description field is what the model sees in the catalog and cannot exceed 1,024 characters.

The instruction body after frontmatter can be up to 20,000 characters, and longer bodies are truncated.

Skill Discovery Locations

Swival checks these locations for skills, in precedence order:

  1. .swival/skills/ — Swival-specific project skills (highest precedence)
  2. .agents/skills/ — common cross-agent standard (OpenCode, OpenHands, etc.)
  3. --skills-dir paths — explicit extra directories
  4. ~/.config/swival/skills/ (or $XDG_CONFIG_HOME/swival/skills/) — global Swival skills
  5. ~/.agents/skills/ — global cross-agent skills (lowest precedence)

Every immediate subdirectory that contains SKILL.md is treated as a skill. If the same skill name exists in multiple locations, the first one in the precedence order wins. Skills in project-local locations are normally shown with file paths in the catalog and need no allowlist entries. The exception is symlinks: if .agents or a skill directory symlinks to a path outside the project root, those skills resolve as external and follow external-skill access rules instead.

Global skills

Place skill directories in ~/.config/swival/skills/ (or $XDG_CONFIG_HOME/swival/skills/) for Swival-specific global skills, or in ~/.agents/skills/ for skills shared across agents. Both are scanned automatically. Global skills have the lowest precedence, so any project-local skill or --skills-dir skill with the same name takes priority. Global skills are typically outside the project, so they resolve as non-local: they don't show file paths in the catalog and are auto-added to the read-only allowlist at setup time. In the unusual case where a global path resolves inside the project (e.g. via symlinks), they behave as local skills instead.

Extra skill directories

You can add additional skill locations with --skills-dir or skills_dir in config.

swival --skills-dir ~/my-skills "task"

Each --skills-dir path can point directly at one skill directory that contains SKILL.md, or at a parent directory where nested subdirectories contain skill files. If duplicate skill names exist across extra directories, first discovery wins. Extra directories override global skills of the same name.

If you do not want skill loading at all, use --no-skills.

How Progressive Disclosure Works

At startup, Swival builds a compact skill catalog that includes names, descriptions, and file paths (for local skills). That catalog is appended to the system prompt under a ## Skills heading, and the use_skill tool is exposed.

$skill-name mentions (automatic activation)

When a user message contains $skill-name (e.g. "please $deploy"), Swival automatically activates matching skills before the model's turn. Each mentioned skill produces a synthetic use_skill tool-call/result pair injected into the conversation history. This teaches the model the correct single-skill-per-call API shape while giving it the full instructions without requiring an extra round-trip.

Because injections use assistant+tool messages (not user messages), compaction can shrink or drop them when context pressure grows.

Manual activation

When the model decides a skill is relevant on its own, it calls use_skill with the skill name. Swival reads the full body from SKILL.md and returns it inside <skill-instructions> tags along with the skill directory path. For local skills, the model can also read the SKILL.md file directly using the path shown in the catalog.

Trigger rules in the prompt

The catalog includes guidance telling the model that if a task clearly matches a skill's description, it should use that skill. This reduces the chance of the model ignoring available skills.

File Access For External Skills

Project-local skills are already inside normal sandbox roots, so they use standard file access rules. External skills (including global skills) are automatically added as read-only roots at session setup time. That means the model can read helper files under those skill directories with absolute paths, but cannot write into those external skill directories.