Skills

This content was generated with the assistance of AI and should be verified against the official documentation of each tool and framework before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

This page is written against the Claude Code CLI 2.1.283, VS Code 1.139 with the GitHub Copilot Chat extension, and the GitHub Copilot CLI 1.0.88, all re-verified as current as of 2026-09-28; re-check the linked docs before relying on an exact field name, since both products change these surfaces often. Every ai-catalog example is excerpted from the repository at the pinned commit 58fb709 (main).

The Agent Skills open standard

A skill is a folder containing a SKILL.md file — metadata (at minimum a name and a description) plus instructions that tell an agent how to perform a task — and, optionally, bundled scripts, reference material and templates. Anthropic originally developed this format for Claude and later released it as the Agent Skills open standard, documented independently of any one vendor at agentskills.io and now adopted by a growing list of agent products, including GitHub Copilot and VS Code. The standard describes three stages of progressive disclosure:

  1. Discovery — at startup, an agent loads only each skill’s name and description into context, just enough to know it exists.

  2. Activation — when a task matches a skill’s description, the agent reads the full SKILL.md body into context.

  3. Execution — the agent follows the instructions, optionally running bundled scripts or reading referenced files as needed.

This keeps the always-on cost of having many skills installed small (their descriptions), while the more expensive full instructions load only for the skill actually in play — the same context-budget reasoning Context Engineering covers for prompts in general. Claude Code’s own implementation of the standard is documented at code.claude.com/docs/en/skills; the standard itself is specified at agentskills.io — Specification.

SKILL.md anatomy

A minimal skill needs only a name and a description in YAML frontmatter, followed by a Markdown body of instructions:

A minimal SKILL.md
---
name: format-changelog
description: Reformat this repository's CHANGELOG.md entries to Keep a Changelog style. Use whenever a changelog entry needs tidying instead of hand-editing its Markdown.
---

# Format Changelog

1. Read `CHANGELOG.md` at the repository root.
2. Group entries under `### Added` / `### Changed` / `### Fixed` per release heading, in that order.
3. Reformat each entry as an imperative one-liner starting with a capital letter, no trailing period.
4. Leave the version headings and dates untouched.

Claude Code loads every installed skill’s name and description into context up front (unless disable-model-invocation hides it, see below); when the description matches the current task, or the user types /name, the full body is read in and stays in context across later turns (after auto-compaction only the most recent invocations are re-attached, within a token budget).

Frontmatter reference

The table below covers every frontmatter key Claude Code currently documents, verified against the Claude Code Skills reference. The last two rows are accepted for Agent Skills interoperability but are not acted on by Claude Code itself.

Key Type Default What it does

name

string

the skill’s directory name

The command name shown in the / menu and typed to invoke the skill (/name).

description

string

the first non-empty line of the body

What the skill does and when to use it. Always loaded into context (unless hidden, see disable-model-invocation) so Claude can decide whether to auto-invoke; combined with when_to_use, capped at 1,536 characters. See Writing Effective Skills for how to write one that triggers reliably.

when_to_use

string

none

Extra auto-invocation guidance (trigger phrases, example requests), appended to description.

argument-hint

string

none

An autocomplete hint for the expected arguments after /name, e.g. [issue-number].

arguments

string or list

none

Named positional arguments substituted as $name in the body; a space-separated string or a YAML list.

disable-model-invocation

boolean

false

When true, Claude cannot auto-invoke the skill and its description is not loaded into context at all — only the user can run it, by typing /name. Also blocks scheduled-task invocation and subagent preloading.

user-invocable

boolean

true

When false, the skill is hidden from the / menu — only Claude can invoke it automatically; its description still loads into context.

allowed-tools

string or list

none

Tools Claude may use without an interactive permission prompt for the turn that invokes the skill; the grant clears at the next message. Space/comma-separated string or YAML list, e.g. Bash(mvn *) Bash(git status *).

disallowed-tools

string or list

none

Tools removed from Claude’s pool while the skill is active; the restriction also clears at the next message.

model

string

inherit the session’s model

Overrides the model used while the skill runs; accepts the same values as /model, or inherit. Cannot select a model excluded by an availableModels allowlist.

effort

string

inherit the session’s effort

Overrides the reasoning-effort level while the skill runs: low, medium, high, xhigh or max.

context

string

inline (runs in the current conversation)

Set to fork to run the skill in an isolated subagent context instead of inline — see Subagents & Custom Agents for the isolation model this shares with subagents.

agent

string

general-purpose

With context: fork, which subagent type runs the skill: a built-in (Explore, Plan, general-purpose) or a custom agent defined under .claude/agents/.

background

boolean

true

With context: fork, whether the forked subagent runs in the background (true) or the skill waits for its result (false). Requires Claude Code 2.1.218 or later.

hooks

object

none

Hooks registered for the rest of the session when the skill is invoked; see Hooks for the event/matcher format this object follows.

paths

string or list

none

Glob patterns that scope auto-activation: the skill only loads automatically while Claude is working with matching files.

shell

string

bash

Which shell runs the body’s inline dynamic-command injections: bash or powershell. powershell takes effect only where the PowerShell tool is enabled.

metadata

object

none

A free-form key/value map for the skill author’s own use; Claude Code stores it but does not act on it.

license

string

none

An Agent Skills spec field describing the license covering the skill. Claude Code accepts but does not enforce it.

compatibility

string

none

An Agent Skills spec field (up to 500 characters) describing environment requirements. Claude Code accepts but does not enforce it.

Two of those keys together, context: fork plus agent, turn a skill into a one-shot isolated worker. This research skill runs in a fresh Explore subagent that does not see the conversation, and only its summary comes back:

.claude/skills/deep-research/SKILL.md
---
name: deep-research
description: Research a topic across this codebase and report findings with file references. Use when a question needs a broad read of the code rather than one file.
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep.
2. Read and analyze the code.
3. Summarize findings with specific file references.

See Claude Code — Skills ("Run skills in a subagent").

Supporting files, scripts and locations

A skill’s folder can hold more than SKILL.md. The Agent Skills specification names three optional directories:

my-skill/
├── SKILL.md     # required: frontmatter + instructions
├── scripts/     # optional: executable helpers the steps shell out to
├── references/  # optional: longer material read only when a step needs it
└── assets/      # optional: templates or other files the skill produces from

Any other layout works too. The ai-catalog -code-one-task skills, for example, keep their routing tables under a singular reference/ directory. Putting detail in a reference file rather than the SKILL.md body itself is the *progressive-disclosure pattern covered in depth on Optimizing Skills & Agents: the body stays short enough to read in full on activation, and a step points at a reference file (See references/routing.md for which file to open for each stack) only when that particular path is taken. Both the specification and Claude Code’s docs advise keeping SKILL.md under 500 lines. See agentskills.io — Specification.

Where skills are discovered from

Claude Code loads skills from several locations, resolved in this priority order (enterprise beats personal beats project; see the Skills reference for the full precedence table):

Location Path Scope

Enterprise (managed)

.claude/skills/<name>/SKILL.md under the managed-settings directory

Every user on managed org machines

Personal

~/.claude/skills/<name>/SKILL.md

The current user, across all their projects

Project

.claude/skills/<name>/SKILL.md in the start directory or any parent up to the repository root

Everyone working in that repository (this is where ai-catalog’s 102 iru-* skills live at the pinned commit)

Nested

<subdir>/.claude/skills/<name>/SKILL.md

Loads once Claude works on files under <subdir>

Plugin

<plugin>/skills/<name>/SKILL.md

Wherever the plugin is enabled, namespaced as /plugin-name:skill-name — see Plugins & Marketplaces

GitHub Copilot’s agent-skills support (Copilot cloud agent, Copilot code review, the Copilot CLI, the GitHub Copilot app, and agent mode in VS Code and JetBrains IDEs) reads project skills from .github/skills/, .claude/skills/ or .agents/skills/, and personal skills from ~/.copilot/skills/ or ~/.agents/skills/ (VS Code also reads ~/.claude/skills/), verified against GitHub’s Agent Skills documentation and VS Code — Agent Skills. Because Copilot reads the same .claude/skills/ folder Claude Code uses, a project-level skill authored for one tool is picked up by the other without duplicating the folder — the practical basis for Copilot & Claude Code Equivalents's migration guidance.

Copilot’s frontmatter support overlaps with Claude Code’s but is not identical. VS Code documents name and description as required (with name matching the parent directory, lowercase letters, digits and hyphens only), plus argument-hint, user-invocable, disable-model-invocation and an experimental context: fork. The Copilot CLI documents license and allowed-tools; there, pre-approving shell or bash removes the confirmation step for terminal commands, so only do it for a skill and scripts you have reviewed and trust. Treat any other key in the table above (model, paths, hooks, and so on) as Claude Code-only unless the Copilot docs confirm it for a given surface.

In Claude Code
.claude/skills/iru-check-license/SKILL.md   # project scope, read by Claude Code
In GitHub Copilot (VS Code)
.github/skills/format-changelog/SKILL.md    # project scope, read by Copilot
.claude/skills/iru-check-license/SKILL.md   # also read by Copilot -- shared with Claude Code

Invocation: the user vs. the model

A skill can start in either of two ways:

  • By the user, typing /name (optionally with arguments after it, substituted per the arguments frontmatter or as $ARGUMENTS). This always works unless user-invocable: false hides the skill from the / menu.

  • By the model, when the current task’s wording matches a loaded description closely enough that Claude decides to invoke it on its own. This is disabled entirely by disable-model-invocation: true, which is how a skill is made user-only — useful for something destructive or expensive enough that it should never fire without an explicit ask.

A user-only skill, and how each side can invoke it
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite.
2. Build the application.
3. Push to the deployment target.
> /deploy staging          # works: the user typed the name
> the build looks ready    # never triggers /deploy: the model can't invoke it

The inverse, user-invocable: false, hides the skill from the / menu while still letting Claude invoke it; to stop Claude invoking a skill through the Skill tool, only disable-model-invocation: true works. Permission rules add a third control: Skill(deploy) in permissions.deny stops Claude from invoking it. See Claude Code — Skills ("Control who invokes a skill").

Skills invoking skills

A SKILL.md file cannot statically include another skill the way, say, an AsciiDoc partial does. What it can do is instruct Claude, in its own body, to call the Skill tool for another named skill by name — and grant that permission via allowed-tools. This is exactly how ai-catalog’s orchestrator skills compose: iru-code’s `allowed-tools lists Skill and Agent, and its Step 4 tells Claude to reach iru-code-one-task-group not by calling Skill(…​) directly but through the iru-isolated-skill-executor agent, so each task group runs in its own subagent context rather than accumulating in the orchestrator’s:

From iru-code/SKILL.md, Step 4 (abridged)
Agent({
  description: "Implement task group <N>",
  subagent_type: "iru-isolated-skill-executor",
  prompt: "Invoke Skill({skill: \"iru-code-one-task-group\", args: \"<...>\"}).
    Report back, per task in the group: the files touched, tests added/updated, …",
  run_in_background: false
})

Code documents the full dispatch chain, and Orchestration Patterns walks the whole iru-issue → iru-code → iru-gate-runner pipeline this pattern builds up to.

Examples from ai-catalog

Example 1. ai-catalog: iru-check-license/SKILL.md

A small, self-contained skill with no allowed-tools. The read-only git log calls it makes to date headers never prompt anyway, because Claude Code runs a built-in set of read-only commands (including read-only forms of git) without asking, but the Edit calls that rewrite headers go through the normal permission prompt (see Claude Code — Read-only commands). Its frontmatter is just the required minimum plus a model pin to the cheapest tier, because checking and rewriting license headers is mechanical work:

---
name: iru-check-license
description: Check for a license file (LICENSE, LICENSE.txt, LICENSE.md, COPYING, etc.) in the repository root, and if one exists, verify every source and test file carries a header consistent with it. Learns the header format from files that already have one; if none carry a header yet, generates a standard header for that license type. Invoke as `/iru-check-license` to scan the whole repository, or `/iru-check-license <path-or-glob>` to scope the check to specific files/directories. Use whenever the user wants license-header compliance checked or backfilled, instead of eyeballing individual files.
model: haiku
---

This demonstrates a description written for triggering: it names the invocation form (/iru-check-license and the scoped variant), states what the skill does and does not do, and closes with a "Use whenever …​ instead of …​" clause — the pattern Writing Effective Skills covers in depth. See Check License for the full, generated page.

Example 2. ai-catalog: iru-code/SKILL.md (orchestrator frontmatter; description abridged, allowed-tools wrapped)

An orchestrator skill needs a heavier model tier and an explicit allowed-tools grant covering both the commands its own steps run directly and the tools (Skill, Agent) it needs to dispatch to other skills and subagents:

---
name: iru-code
description: Execute the tasks in implementation_plan.md at the repository root, one task group at a time — …
model: sonnet
allowed-tools: Read Edit Write Bash(mvn *) Bash(detect-secrets *) Bash(git status *) Bash(git diff *)
  Bash(git log *) Bash(find *) Bash(grep *) Bash(ls *) Bash(mkdir *) Bash(mv *) Bash(date *)
  Bash(gh issue create *) TaskCreate TaskUpdate TaskList TaskGet Skill Agent
---

This demonstrates least-privilege scoping (every Bash entry names a command prefix, never a bare Bash) and model: sonnet reserved for a skill that actually writes code, in contrast to iru-check-license’s `haiku — the model-tiering technique Optimizing Skills & Agents measures. See Code for the full, generated page.

A generalised orchestrator skill
---
name: run-release-checklist
description: Run this repository's pre-release checklist (tests, changelog, version bump) end to end, delegating each check to its own skill. Invoke as `/run-release-checklist`. Use before tagging a release instead of running each check by hand.
model: sonnet
allowed-tools: Read Bash(git status *) Bash(git tag *) Skill
---

# Run Release Checklist

1. Invoke `Skill({skill: "run-tests"})` and stop if it reports a failure.
2. Invoke `Skill({skill: "update-changelog"})`.
3. Invoke `Skill({skill: "bump-version"})`.
4. Run `git status` and summarize what changed.
5. Ask for confirmation, then run `git tag v<version>` for the bumped version.

How a skill goes from discovered to executed

flowchart LR D["Discovered\n(SKILL.md found in a\nsearched location)"] --> C["description loaded\ninto context"] C --> M{"Matches the\ncurrent task?"} M -->|model decides yes| L["Loaded\n(full SKILL.md read in)"] U["User types /name"] --> L L --> E["Executed\n(steps run, allowed-tools\ngranted for the turn)"]

Related pages

References