Skip to content
Docs menu

Skills and slash commands

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.

View .md

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

mkdir -p .claude/skills/release-notes
---
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

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.

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.