Claude Code Skills: Keep Repeated Procedures in the Repository

A deployment procedure usually includes details the repository cannot explain on its own: which checks must pass, how to inspect the proposed change and where to find the rollback instructions. Repeating that procedure in each coding session is tedious, and omitting a step is easy.

A Claude Code skill stores the procedure as instructions the agent can load for a relevant task. It is useful for work that recurs often enough to deserve a maintained checklist.

Start with one procedure

A skill directory contains a SKILL.md file. Its frontmatter supplies a name and description; its body explains the work. Here is a small example:

---
name: review-change
description: Review a proposed code change against the project's release requirements.
---

Read the diff and the release checklist.
Check that the change addresses the stated problem.
Identify missing validation and explain any release risk.
Return findings with file references before proposing edits.

For personal use, this could live at ~/.claude/skills/review-change/SKILL.md. A project can keep shared skills under .claude/skills/ in its repository. The official skills guide covers discovery, invocation and supported frontmatter.

Keep the first version specific. “Write good code” gives the agent little help. “Check that database migrations have a rollback procedure and that the release notes describe the data change” gives it something to examine.

Decide how it should be invoked

A description helps Claude decide whether a skill is relevant. For a procedure you want to invoke yourself, disable-model-invocation: true prevents automatic invocation. A skill with user-invocable: false is hidden from the slash-command menu but can still be available to the model.

Neither setting makes instructions run continuously. The skill has to be loaded, and the agent still needs the tools and permissions to carry out its steps. Keep repository-wide conventions in the appropriate project instructions rather than assuming a hidden skill is always active.

Names can conflict across personal, project, plugin and managed sources. Check the documented resolution rules and inspect the loaded skill if Claude appears to follow an unexpected version.

Add context without filling every session

A short procedure can point to supporting references, scripts or templates. The agent can consult those when the task needs them. This is easier to maintain than a large instruction file repeated in every conversation.

Skills can also inject command output into their instructions. That can give a review the current diff or a deployment the current environment state. Treat those commands as executable code: keep them bounded and inspect what they can read or change.

A skill can be configured to run in a subagent context. That separates its working context from the main conversation; it does not guarantee background execution or make the work free. Parallel tasks still need clear ownership, especially when they share files.

Test the instruction, then maintain it

Try the skill on a task you understand. Read the result and check whether it consulted the intended references, found the relevant risks and stopped at the right point. A procedure that produces a polished answer while skipping a required check needs revision.

After a real failure, update the relevant step and rerun that case. Keep an owner for shared skills, just as you would for a release script. Instructions drift when the tools and process change.

A useful skill saves repeated explanation while making the procedure visible to reviewers. It cannot guarantee expert judgment or replace permission enforcement. Its value is a concrete checklist that the team can inspect, test and improve.