---
title: Skills and slash commands
description: Add skills the agent loads on demand and slash commands from markdown files, list what is loaded, and find skills the agent asked for but did not have.
section: plugins
order: 60
audience: [user, builder, agent]
sources: [packages/harness/src/extensions/compat.ts, packages/harness/src/skillgaps/index.ts, cli/src/skills-gaps.ts, cli/AGENTS.md]
features: [plugins.skill]
---

A **skill** is a directory with a `SKILL.md`: a name and description in frontmatter and instructions in the body. The model sees the name and description and reads the body only when a task matches (the Agent Skills format, as in Claude Code). A **slash command** is a markdown file whose body becomes your message when you type `/name`.

## Quick start

```bash
mkdir -p .claude/skills/release-notes
```

```markdown
---
name: release-notes
description: Write release notes from the merged PRs since the last tag.
---
1. Find the last tag with `git describe --tags --abbrev=0`.
2. List merged PRs since then.
3. Group them by component and write one line each.
```

In a session, `/skill:release-notes` runs it, or the agent reads it when you ask for release notes. `/skills` lists every skill the agent can load (built-ins marked); `/commands` lists slash commands from files (built-ins and macros marked).

## Where skills and commands come from

| Kind | Locations |
|---|---|
| Skills | `.claude/skills/*/SKILL.md`, `~/.claude/skills`, `~/.venom/agent/skills`, a trusted project's `.venom/skills` and `.agents/skills`, plugins' `skills/`, your org's library (Venom Cloud) |
| Commands | `.claude/commands/**/*.md`, `~/.claude/commands`, plugins' `commands/` (as `/<plugin>:<command>`), org prompts (as `/org:<name>`) |

A skill or command named like a venom built-in replaces it (built-in skills include `repo-map`, `tdd`, `fix-tests`, `debug`, `bisect`, `commit`, `pr-description`). Skills with non-strict YAML frontmatter, or a description over 1,024 characters, are served from a normalized copy in `~/.venom/cache/claude-skills/`; the originals are never changed.

## Commands from files

Commands take `$ARGUMENTS`, `$1` to `$9` and `${1:-default}`; arguments not referenced are appended. Frontmatter: `description`, `argument-hint`, `model` (switched for that turn), `allowed-tools` (granted as allow rules for that turn; a project command's only once the project is trusted). `` !`cmd` `` in the body runs through the permission gate first and its output is inlined. A body made only of `/step` lines is a macro that runs those commands in order.

## Skill listing and prompt size

The system prompt lists each skill's name, path and a description cut to 120 characters. If that listing would take more than 5% of the model's context window, descriptions drop to 60 characters; if it still does not fit, the listing becomes a compact index and the agent gets a `skill_search` tool to look up a skill's full description by name or topic. The choice is made once per session, so the prompt prefix stays stable for caching.

## Skill gaps {#gaps}

venom keeps a local ledger of requests for skills, slash commands, skill searches and subagent types: whether each one existed (hit) or not (miss). It holds names only, never arguments or prompt text, and nothing is uploaded.

```bash
venom skills gaps           # per name and agent (main or subagent), most misses first
venom skills gaps --json    # {"type":"skill-gaps","rows":[...]}
```

| Column | What |
|---|---|
| `kind` | `skill`, `command`, `search` (a `skill_search` with no match) or `agent` (an unknown `task` agent type) |
| `name` | what was asked for |
| `agent` | `main` or `subagent` |
| `misses`, `hits`, `miss rate` | counts |

The ledger is `~/.venom/skill-gaps.jsonl` (mode 0600), compacted into one line per name past 256 KiB. A name the agent keeps missing is a skill worth writing.

## Related

- [Write a plugin](/docs/plugins/writing.md) (shipping skills in a plugin, and locking tools behind a skill)
- [Team library](/docs/plugins/library.md)
- [Templates](/docs/plugins/templates.md)
