Skills, Hooks & Custom Commands
Updated
AdvancedWhat you'll learn
~20 min- Author a SKILL.md that works across CLI tools
- Write a hook that enforces a guardrail the model can't forget
- Use permission allowlists as the middle path between approve-everything and YOLO
You’ve typed the same release-notes prompt again and again. “Summarize the commits since last tag, group by feat/fix/chore, output markdown.” You paste it into Claude Code. Then Codex. Then Antigravity. And again next sprint. The copy-paste overhead is the tax you pay for not having a skill yet. Giving Good Instructions’s rule: a reused prompt becomes a skill; this lesson is how to write one well.
This lesson covers three infrastructure-layer mechanisms that make your setup durable:
- Skills — reusable workflows you invoke by name across tools
- Hooks — shell commands the harness runs at lifecycle events, with deterministic enforcement the model cannot override
- Allowlists — pre-approved permissions so you stop rubber-stamping the same safe commands
Skills: write once, invoke everywhere
The Agent Skills standard
The Agent Skills open standard (published December 2025; 46 supporting tools listed on agentskills.io as of August 2026) defines a minimal contract: a skill is a directory containing a SKILL.md file. That file has YAML frontmatter followed by markdown instructions. The agent reads the frontmatter to decide if the skill is relevant to the current task, then reads the body for step-by-step instructions — progressive disclosure by design.
Tools that read SKILL.md include Claude Code, Codex CLI, GitHub Copilot (the CLI and code review), VS Code, Cursor, Gemini CLI, Antigravity CLI, OpenCode, Kiro, JetBrains Junie, and Goose. The payoff: a skill you write today for Claude Code loads unchanged in Codex or Antigravity tomorrow, once it sits in the folder that tool scans (see the table below). The Agent Plugins 1.0 standard (its steering committee has members from Amazon, Cursor, Microsoft, OpenAI, and Vercel) goes one step further and packages skills and MCP servers into a single installable plugin. As of 2026-11-07, Claude Code and Antigravity are not on its compatible-clients list; each has its own plugin format.
Anatomy of a SKILL.md
Here is the release-notes skill, complete and realistic:
REFERENCE FILE .claude/skills/release-notes/SKILL.md cross-tool skill definition open reference hide reference Reference example of an Agent Skills SKILL.md file with YAML frontmatter and verification steps.
---name: release-notesdescription: > Generate structured release notes from git log since the last tag. Use when the user asks for release notes, a changelog, or "what changed since the last release."---
## Steps
1. Run `git describe --tags --abbrev=0` to get the most recent tag.2. Run `git log <tag>..HEAD --oneline --no-merges` to get commits since that tag.3. Group commits by conventional prefix: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`. - If a commit has no prefix, place it under "Other".4. Write the output as markdown: - `## [Unreleased]` heading - One sub-section per non-empty group (### Features, ### Bug Fixes, etc.) - Bullet each commit: `- <message> (<short-hash>)`5. Ask the user if they want the notes saved to `CHANGELOG.md` or printed only.
## Verification
After output, confirm the tag found in step 1 and the commit count match what`git log --oneline <tag>..HEAD | wc -l` returns.The frontmatter description is how the agent decides whether your skill is relevant before reading the body. It is the main signal the agent uses at matching time (alongside the skill’s name), so make it precise and include the phrases a user would actually say.
Where skills live per tool
| Tool | Project skills path | Personal skills path | Plugins |
|---|---|---|---|
| Claude Code | .claude/skills/<name>/SKILL.md | ~/.claude/skills/ | Own format: /plugin install <name>@claude-plugins-official |
| Codex CLI | .agents/skills/<name>/SKILL.md ($skill-creator scaffolds one) | ~/.agents/skills/ | Agent Plugins format: codex plugin add, codex plugin marketplace add |
| Antigravity CLI | .agents/skills/<name>/SKILL.md | ~/.gemini/config/skills/ | Own format: agy plugin install <name>@antigravity-plugins-official; agy plugin import claude reads a Claude Code plugin |
| Copilot CLI | .github/skills/, .agents/skills/ or .claude/skills/ | ~/.copilot/skills/ or ~/.agents/skills/ | Agent Plugins format: /plugin or copilot plugin |
| Cursor, others | Same SKILL.md format; check each tool’s docs for its discovery path |
Commands as of 2026-11-07; each tool’s /skills lists what it found.
In Claude Code, .claude/commands/release-notes.md and .claude/skills/release-notes/SKILL.md both create a /release-notes slash command; the two authoring styles are equivalent. The skills directory is preferred for cross-tool compatibility. Claude Code plugins can bundle skills too: install one with /plugin install <name>@claude-plugins-official, and /reload-plugins picks it up without a restart.
The cross-tool payoff
Commit your skills to the repo. Claude Code reads .claude/skills/; Codex and Antigravity read .agents/skills/; Copilot CLI reads either one (and .github/skills/). Keep one copy and symlink (or copy) it to the other path, and every teammate gets the same skill whichever tool they open: no copy-paste of prompts, no “how did you phrase that?” questions, no drift between tools. The standard is the point.
Hooks: enforcement the model can’t forget
The determinism argument
CLAUDE.md gives the agent instructions. The agent follows them — until context runs long, a follow-up prompt shifts focus, or the model just reasons its way around a soft guideline. Instructions ask. Hooks enforce.
A hook is a handler the harness runs at a lifecycle event (PreToolUse, PostToolUse, and others), most often a shell command. It fires regardless of what the model decides. It cannot be prompted away. It can be switched off from outside the session, though: claude -p --bare skips hooks (along with skills, plugins, MCP servers and CLAUDE.md), so a script that runs bare runs without your guardrails.
The canonical example: this site’s build hook
This training site’s own .claude/settings.json runs the following:
REFERENCE CONFIG .claude/settings.json PostToolUse build verification hook open reference hide reference Reference example of a PostToolUse hook configuration that runs npm run build after file edits and returns exit code 2 on failure.
{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "out=$(npm run build 2>&1); s=$?; echo \"$out\" | tail -5 >&2; [ $s -eq 0 ] || exit 2" } ] } ] }}The loop this creates:
- Agent edits a file (Edit or Write tool call fires)
- PostToolUse hook runs
npm run buildimmediately, keeping its output and its exit status (s=$?) - If the build passes, the hook exits 0 and stays quiet, so the agent sees nothing
- If the build fails, the hook prints the last five lines of build output to stderr and exits 2. For a PostToolUse hook, exit 2 is the one code that feeds stderr back to the agent, so the agent reads the error and fixes it before moving on. Any other non-zero code is recorded as a hook error the agent never sees, which is why the hook turns a failed build into exit 2 instead of passing the build’s own status through. (Piping
npm run buildstraight intotailwould be worse still: the pipeline reportstail’s 0, and the failure passes as a success)
Without this hook, the agent might make three more edits before you discover the first one broke the build. With it, every edit is verified in real time — not because you asked, but because the harness guarantees it.
This pattern generalizes to any project with a fast verification command: a TypeScript typecheck, a test suite, a linter.
More hook ideas
These are directional — the point is the pattern, not the exact commands:
- Lint on edit:
"command": "eslint --fix $(git diff --name-only HEAD)"— keep the working tree clean without remembering to run it - Secret scan before commit: a PreToolUse hook on Bash commands matching
git committhat runsdetect-secrets scanortruffleHog— block the commit if secrets are found - Notify on stop: a hook on the session-end event that sends a desktop notification or a Slack message — useful for long autonomous runs you want to monitor without staring at the terminal
Where hooks live per tool
All four CLIs run hooks; where the file lives and what the events are called differ (as of 2026-11-07):
| Tool | Hook file | Events | Notes |
|---|---|---|---|
| Claude Code | hooks key in .claude/settings.json (or your user settings) | PreToolUse, PostToolUse, Stop and others | /hooks lists them. Handler types: command, http, mcp_tool, prompt, agent. Exit 2 shows stderr to the agent. Not run under claude -p --bare |
| Codex CLI | .codex/hooks.json in the repo, ~/.codex/hooks.json, or a [hooks] table in config.toml | SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop and others | You review and trust each non-managed hook before it runs; /hooks lists them |
| Antigravity CLI | .agents/hooks.json or ~/.gemini/config/hooks.json | SessionStart, PreToolUse, PostToolUse, PreInvocation, PostInvocation, Stop | /hooks lists them |
| Copilot CLI | .github/hooks/<name>.json or ~/.copilot/hooks/ | camelCase: sessionStart, preToolUse, postToolUse and others | Repository hooks load only in a trusted folder (the trust prompt, or COPILOT_ALLOW_ALL=true, which also trusts the folder) |
The JSON structure above is Claude Code’s format. The matcher field, the configuration keys and the exit-code rules vary by tool, so check each tool’s current hooks docs before porting a hook. Inventing syntax here would be worse than unhelpful.
Allowlists: the middle path
In a mode that asks before commands (Claude Code’s manual mode, or any action auto mode does not clear), every command the agent wants to run stops for your approval unless you’ve pre-approved it. Approving npm test for the fifteenth time is friction with no security value.
Permission allowlists in settings.json let you pre-approve commands you’ve already decided are safe. The agent runs them without prompting. Everything else still asks.
This is the middle path on the safety spectrum: not approve-everything, not full autonomy. For the full spectrum and when to use each position, see the Vibe Coding Reference — the spectrum is taught there and won’t be repeated here.
An illustrative example of the allowlist format in Claude Code’s settings.json (this repo’s actual settings.json contains only the hook above; verify current syntax in the Claude Code docs):
{ "permissions": { "allow": [ "Bash(npm test)", "Bash(npm run build)", "Bash(git status)", "Bash(git diff)", "Bash(git log *)" ] }}(Claude Code already runs read-only commands such as git status, git diff and git log without asking, so in practice your list is mostly build and test commands.)
The pattern is: allow the commands whose output you want the agent to see and act on without interruption, and let the approval flow catch anything outside that envelope. Read-only commands and your own test suite are natural candidates. git push, rm -rf, and anything touching production credentials are not.
Add allowlist entries reactively — when you notice you’re approving the same command repeatedly. A short list you actually reviewed beats a long list you copy-pasted from a blog post.
Deny rules: the other half
Allowlists pre-approve the safe. The complement is denying the dangerous outright — blocked even when you’d otherwise be prompted, so a deceived or over-eager agent can’t reach it. Claude Code’s permissions block also takes a deny list (illustrative — verify current syntax in the docs):
{ "permissions": { "deny": [ "Bash(rm *)", "Bash(git push *)", "WebFetch(domain:internal.example.com)" ] }}Deny rules are the right place for irreversible commands, anything touching production, and URLs the agent should never fetch — the last one doubles as an exfiltration guard when the agent processes untrusted input that might try to redirect it. For regulated environments — government, healthcare, finance — a short deny list is a cheap, deterministic floor underneath everything else you allow.
You want Claude Code to always run 'npm test' after editing a file. Which mechanism is correct?
You write a release-notes skill in .claude/skills/release-notes/SKILL.md. A teammate opens the same repo in Codex CLI. What happens?
Which of these is the right job for a CLAUDE.md instruction vs. a hook vs. a skill?
Key takeaways
- A skill is a
SKILL.mdfile in a standard directory: YAML frontmatter for matching, markdown body for instructions. Write it once; it works across Claude Code, Codex, Antigravity, Copilot CLI, and other adopters of the Agent Skills standard, once it sits in a folder each tool scans. - Claude Code merges
.claude/commands/and.claude/skills/— both create slash commands. Prefer the skills directory for cross-tool portability. - Hooks enforce; CLAUDE.md asks. A PostToolUse hook on
Edit|Writeis the canonical pattern for build verification; this site uses it, and you should use it too. In Claude Code only exit code 2 puts the hook’s stderr in front of the agent, andclaude -p --bareskips hooks entirely. - Allowlists are the middle path — pre-approve safe commands to reduce friction without opening the full autonomy door.
- Hook and allowlist syntax is tool-specific. Verify against current docs before porting patterns across tools.
Next: Subagents and Orchestration — how to compose multiple agents into pipelines where each does only what it’s best at.