Creating and updating skills and agents

This documentation was generated with the assistance of AI. Please report any inaccuracies.

This guide is about authoring skills and agents in general — the mechanics and workflow for creating one in any repository. For the skills and agents this specific catalog already ships, see the skills reference table, the agents reference table, and Agents.

Where each one lives

Artifact Location

Skill

.claude/skills/<name>/SKILL.md — the directory name is the skill’s canonical name and doubles as its slash command (/+<name>). A skill directory may also hold supporting files (scripts, templates) alongside SKILL.md. In this catalog, <name> always starts with the iru- prefix (below).

Custom agent

.claude/agents/<name>.md — YAML frontmatter (system prompt, allowed tools, model) plus the agent’s persona/instructions in the body.

Plugin-bundled skill/agent

The same skills/ and agents/ layout, but rooted under a plugin directory’s .claude-plugin/ sibling folders instead of the repository’s own .claude/ — see Plugins.

Naming: avoiding marketplace collisions

Every skill and agent this catalog ships carries an iru- prefix — the directory name under .claude/skills/, the frontmatter name field, the agent filename under .claude/agents/, and every cross-reference to it from another skill’s own instructions or this documentation. A repository can install skills from more than one source at once (this catalog, a plugin marketplace, another team’s hand-copied skills) into the same .claude/skills/ directory, and slash commands are matched by directory name alone — two differently-sourced skills both named plan or code would silently shadow one another. The prefix is this catalog’s namespace, so /iru-plan never collides with an unrelated /plan a consuming repository picked up elsewhere.

Any new skill or agent added to this catalog must follow the same convention from the start — name the directory/file iru-<name> (not a bare <name> renamed later), and match this catalog’s existing style for the prefix itself (lowercase, hyphen-joined, no separate delimiter between iru and the rest of the name). Adopting a single skill from this catalog into another repository that doesn’t use this convention is free to drop the prefix — it exists to keep this catalog’s own skills from colliding with each other and with other sources once several are installed side by side, not as a requirement for every consumer.

See Extending the skills and agents catalog for how this convention interacts with the language/framework key registry the iru-code pipeline uses — the iru- prefix is stripped back off before that key is derived, since it isn’t part of the semantic key itself.

How each one is actually invoked

Skills and agents are triggered in genuinely different ways — knowing which is the "proper" channel for each avoids the common mistake of expecting one to behave like the other.

Skills — slash command, or natural language, or both

A skill is reachable through two channels, and both are open by default:

  • Explicit slash command — a user (or an orchestrating skill) types /<name>, optionally with arguments, e.g. /iru-plan 42. This is the precise, reproducible way to invoke exactly the skill you mean.

  • Autonomous invocation by Claude — a user just describes the task in plain language ("write me an implementation plan for issue 42"), and Claude, matching the request against the skill’s frontmatter description, decides on its own to run it — no slash command typed at all.

Two frontmatter fields narrow this default:

  • disable-model-invocation: true restricts a skill to explicit slash-command invocation only — Claude will never trigger it on its own, and its description isn’t kept loaded in context waiting to be matched. Worth setting on a skill whose effect is disruptive if it runs by surprise (e.g. one that opens a PR).

  • user-invocable: false is the inverse — the skill can only be triggered by Claude’s own autonomous matching; a user typing /<name> directly does nothing. Suited to a skill that’s really background knowledge for Claude to draw on, not something meant to be run on demand.

Absent either field, the proper way to invoke a skill is whichever channel fits the moment: type the slash command when you already know which skill you want and what arguments to give it, or describe the task in natural language and let Claude pick the matching skill when you’d rather not remember its exact name — reliable in proportion to how distinctive that skill’s description is (see Authoring effective instructions for writing one that matches correctly).

Agents — never a slash command; always a delegation

There is no /agent-name command that directly spawns a specific agent by name the way /<name> invokes a skill — typing that would not do anything special. An agent is only ever reached indirectly, through Claude itself deciding to call the Agent/Task tool with a given subagent_type:

  • An active skill’s own instructions cause the delegation — e.g. iru-code (Code) spawning a general-purpose sub-agent to isolate a noisy quality check, per its own step list.

  • A user asks for it in natural language — "use the Explore agent to find X", "spawn a sub-agent to review this" — which Claude translates into that same Agent tool call. The user is requesting a delegation, not invoking the agent directly.

  • @-mentioning an agent by name in the conversation prompts Claude to run that turn through it.

  • Setting an agent as the session-wide default (e.g. claude --agent <name>, or an agent: setting) makes the whole session inherit that agent’s system prompt, rather than it being spawned mid-task.

So the proper way to get an agent involved is to ask for it — by name, in natural language, or via @mention — and let Claude make the actual tool call; there is no direct, user-typed equivalent to a skill’s slash command. (Don’t confuse this with a /agents management command some Claude Code versions ship, which opens agent configuration/editing — it doesn’t invoke any specific agent by name either.)

Skill or agent — which one?

  • Reach for a skill when the thing you want repeated is a procedure: a sequence of steps a person (or an orchestrating skill) invokes deliberately, on demand, via a slash command — "review this PR", "cut a release", "bootstrap a new repo".

  • Reach for a custom agent when what you actually need is a persona with a narrower tool/context footprint than the main conversation — something spawned mid-task to isolate a noisy sub-task (a full test log, a broad codebase search) or to run with restricted tool access, rather than something a person invokes directly. Claude Code’s built-in general-purpose and Explore agent types already cover most of this without a custom definition — only add a custom .claude/agents/<name>.md when a built-in type’s tool access or system prompt genuinely doesn’t fit (see Agents for how this catalog currently makes that call).

  • Reach for CLAUDE.md instead of either when the thing isn’t a procedure at all but a standing fact or rule that should be true in every session, invoked or not — see The CLAUDE.md file.

The fastest reliable way to draft one

Hand-writing a SKILL.md or agent definition’s frontmatter and prose from a blank file is slower and more error-prone than it needs to be. In practice:

  1. Ask Claude Code itself to draft it. Describe the procedure you want repeated (what to check first, what decisions to make automatically versus ask the user about, what "done" looks like, what it should report back) and ask it to write the SKILL.md — Claude already knows the frontmatter schema and the conventions your other skills use. This is dramatically faster than writing YAML frontmatter and step structure from memory, and it’s easy to review before saving.

  2. Ground it in an existing example. Point it at a similar skill already in .claude/skills/ (or, for an agent, at .claude/agents/ if this repository has any, or Agents’s description of the built-in types) and ask it to follow the same shape — numbered `## Step N headings, an explicit "Report" step, the same tone. Consistency across skills matters more than any one skill’s internal elegance, because a person (or an orchestrator skill) reads several of them together.

  3. Iterate by running it, not just by reading it. Invoke the draft skill/agent against a real, low-stakes case and fix whatever it gets wrong or asks about that it shouldn’t have to — a skill’s instructions are only as good as what actually happens when an agent follows them literally.

  4. Once it’s right, if this repository documents its own catalog (as this one does via iru-generate-skill-docs), re-run that skill so the reference table, dependency graph, and the new skill/agent’s own detail page pick it up — don’t hand-maintain that documentation separately.

How to phrase what you write

Covered in full, with concrete before/after examples, in Authoring effective instructions — the short version: direct imperative steps, one decision per step, explicit stopping/branch conditions, and no more context loaded into the step than that step actually needs.

Packaging and sharing what you create

A skill or agent that’s useful in one repository is often useful in several. See Packaging and distributing skills, agents, and CLAUDE.md for the tradeoff between copying the directory into each repository’s .claude/ versus bundling it into a plugin distributed via a marketplace.

See also