Skills, plugins and marketplaces

Package procedural knowledge as a skill that loads only when relevant, then bundle skills, agents and hooks into a plugin your team can install.

A skill is a folder with a SKILL.md

A skill packages instructions plus optional supporting files. Only the name and description sit in context until the skill is relevant; the body is loaded when it is used. That is what keeps a large library of procedures affordable.

---
name: release-notes
description: Produce release notes from merged pull requests since the last tag. Use when the user asks for a changelog, release notes, or what shipped.
allowed-tools: Bash(git log:*), Bash(gh pr list:*), Read, Write
---

1. Find the last tag: git describe --tags --abbrev=0
2. List merged PRs since then, with labels.
3. Group into Added, Changed, Fixed, Security.
4. Write each entry as a user-visible sentence, not a commit subject.
5. Skip internal-only changes unless they affect behaviour.

See references/style.md for the house voice.

Skills live in .claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/ (personal).
The description is the trigger - it decides whether the skill is ever loaded, so include the words a user would actually say.
Supporting files sit next to SKILL.md and are read on demand, which is progressive disclosure: pay for detail only when you need it.
A skill beats a CLAUDE.md line when the knowledge is procedural, lengthy and needed only sometimes.

Which mechanism for which job

Mechanism	Loaded when	Best for
CLAUDE.md	Always, every turn	Short standing rules and exact commands
Slash command	You type it	A procedure you invoke deliberately
Skill	Model decides from the description	Procedures that should apply automatically
Subagent	Model or you delegate	High-volume isolated work with a small answer
Hook	Lifecycle event fires	Rules that must never depend on judgement

💡

The common mistake is putting everything in CLAUDE.md. It is loaded on every turn of every session, so a growing file quietly raises the cost and lowers the signal of every task. Move procedures out - the skill or command loads only when it is actually used.

Bundling a setup as a plugin

my-plugin/
  .claude-plugin/
    plugin.json          # name, version, description, author
  commands/
    review.md            # becomes /review
  agents/
    code-reviewer.md     # a subagent definition
  skills/
    release-notes/
      SKILL.md
  hooks/
    hooks.json           # hook configuration shipped with the plugin

{
  "name": "acme-standards",
  "version": "1.2.0",
  "description": "Review commands, release-notes skill and lint hooks for Acme services"
}

Add a marketplace, then install from it: /plugin marketplace add <owner/repo> followed by /plugin install <name>.
Plugin components are namespaced, so two plugins can ship a review command without colliding.
A plugin can carry hooks. Installing one therefore installs executable behaviour - read the repository before trusting it.
Version the plugin and pin it in onboarding docs; an unpinned plugin changes under your team silently.

FAQ

How do I decide between a skill and a hook?

A skill tells the agent how to do something and relies on it choosing to follow the instructions. A hook guarantees something happens. If failure is unacceptable - formatting, secret scanning, a required test run - make it a hook, even if a skill would be easier to write.

Why is my skill never used?

Usually the description is phrased as a job title rather than a trigger. Write it the way a user would phrase the request, including the words they would actually type, and keep the frontmatter name short.

Subagents and context isolation Hooks and deterministic automation

Last refreshed 2026-09-18.

Skills, plugins and marketplaces

A skill is a folder with a SKILL.md

Which mechanism for which job

Bundling a setup as a plugin

FAQ

Related