Skills

A skill is a folder with a SKILL.md file: instructions for one kind of task, plus any scripts, templates or reference files they need. The agent sees each skill's name and description, and loads the full instructions only when a task matches. You can also run a skill yourself as a slash command.

Cusp uses the open Agent Skills format, so skills you already have work as is, from .claude/skills/, .agents/skills/ or .codex/skills/.

Where skills liveCopy Anchor Link

Each skill is a directory: .cusp/skills/release-notes/SKILL.md. When two skills have the same name, the first one found wins, so a project skill overrides a user skill with the same name.

A minimal skillCopy Anchor Link

---
name: release-notes
description: Draft release notes from the commits since the last tag. Use when the user asks for release notes, a changelog entry, or "what changed since …".
---

1. Find the last tag with `git describe --tags --abbrev=0`.
2. List commits since then with `git log <tag>..HEAD --oneline --no-merges`.
3. Group them into Features, Fixes and Internal. Drop chores and merge commits.
4. Write one line per change, in the past tense, without commit hashes.
5. Show the draft. Don't write any files unless asked.

The description is what the agent uses to decide when the skill applies. Say what it does and when to use it, in the words a user would actually type.

FrontmatterCopy Anchor Link

ArgumentsCopy Anchor Link

When you run /release-notes v0.2.0, the text after the command is the argument string.

If you pass arguments but the skill has no placeholder, Cusp appends them as ARGUMENTS: … at the end, so they're never lost.

VariablesCopy Anchor Link

${CUSP_SKILL_DIR} (or ${CLAUDE_SKILL_DIR}) is the directory that contains SKILL.md. Use it to point at files shipped with the skill:

Fill in the template at ${CUSP_SKILL_DIR}/template.md.
Run `python ${CUSP_SKILL_DIR}/scripts/check.py` and fix what it reports.

Shell expansionCopy Anchor Link

!`command` runs a command when the skill loads and inserts its output in place. Use it to give the agent current context without spending a tool call:

Current branch: !`git branch --show-current`
Uncommitted changes:
!`git status --short`

The output is inserted as is and isn't expanded again. If the command fails, loading the skill fails with the exit code and output, so you know why.

Set disableSkillShellExecution: true in settings to turn this off.

Supporting filesCopy Anchor Link

Put anything the skill needs next to SKILL.md:

.cusp/skills/release-notes/
├── SKILL.md
├── template.md
└── scripts/
    └── group_commits.py

The agent reads these files only when the instructions tell it to, so a large reference document costs nothing until it's needed.

Controlling skillsCopy Anchor Link

Turn individual skills off, or limit how they can be used, with skillOverrides in settings:

{
  "skillOverrides": {
    "release-notes": "user-invocable-only",
    "legacy-deploy": "off"
  }
}

disableSkills: true turns off all skills.

PermissionsCopy Anchor Link

Running a skill is itself a tool call (Skill), so you can control it with rules: Skill(deploy), Skill(deploy *) for a skill with any arguments, or Skill(ops:*) for every skill in the ops namespace.

Single-file commandsCopy Anchor Link

A command is a skill without its folder: one Markdown file that runs as /name. Cusp reads them from .cusp/commands/ and .claude/commands/, and from the same folders in your home directory. When a skill and a command share a name, the skill wins.

Other agents' commands, such as Codex prompts, Gemini CLI's TOML commands and Cursor commands, are converted into this form by the import. See Import your setup.