Docs/Extend

Skills

Skills are markdown procedures your AI agent discovers and runs on demand — a place for anything you would otherwise re-explain every session.

Skills come from the official skills plugin; bare Gray has none. The install wizard picks it by default, or add it later with gray plugin install skills.

A skill is a directory containing SKILL.md. The plugin reads ~/.gray/skills plus the skill folders other agents use (~/.claude/skills, ~/.agents/skills, opencode's, and Claude Code plugins'). Project skills in .gray/skills, .claude/skills, .opencode/skills or .agents/skills, up to the git root, load only in projects you have run gray trust on.

.gray/skills/release/SKILL.md
---
name: release
description: Cut a release — bump, changelog, tag, push.
---
Bump the version in Cargo.toml to the version you're given, move the
Unreleased changelog section under it, commit, tag and push.
Helper scripts live in this skill's scripts/ directory.

Every turn the model sees every skill's name, the way Claude Code lists them. Descriptions share 1% of the context window, at most 1,536 characters each, and the skills you use least lose theirs first. The model loads a skill through the skill tool; set GRAY_SKILL_CHAR_BUDGET to give descriptions more room.

bash
$/skills # list what was discovered (alias /skill)
$/skills release 0.2.0 # run one; the rest of the line is its arguments
$/skills off # stop sending the list each turn (on to restore)
$/skills disable <name> # hide one skill (enable to restore)
$/skills search <query> # find skills on npm, GitHub and skills.sh
$/skills install owner/repo # install into ~/.gray/skills (remove <name> undoes it)

Cron jobs can attach skills too: gray cron add … --skills release.

Join the Discord

Chat with the people building and running Gray. Show what you made with it.

Join Discord →

Need help?

Open an issue on GitHub, run /feedback from the REPL, or ask in Discord.

Open an issue →