Custom Skills — Claude Code Guide

When a prompt becomes a skill

A custom skill is appropriate when a successful prompt has become a repeatable procedure with a stable input, predictable output, similar steps, and a quality check.

If the context changes radically every time or the prompt must be rewritten from scratch, the procedure is not mature enough to package.

Mechanism	Role
Prompt	One-off statement of the current task
CLAUDE.md	Permanent repository rules
Rule	Constraint for selected files or directories
Skill	Repeatable process with input, steps, result, and checks

Minimal skill contract

Describe when the skill should be used.
Define the required inputs.
Name the artifact or report it must produce.
Record forbidden actions and scope boundaries.
Describe how a reviewer verifies the result.

Issue analysis as a bounded procedure

raw issue
   ↓
issue-analysis
   ↓
TASK_SPEC.md
   ↓
plan review before implementation

A skill must stop before implementation

An issue-analysis skill can turn a bug report into TASK_SPEC.md with a goal, scope, non-goals, affected modules, acceptance criteria, verification plan, and open questions. It should not edit code or begin implementation.

This boundary keeps task analysis, plan approval, and execution as separate reviewable steps.

Distribution levels

Level	When it fits
Personal	An experiment or unstable procedure
Project	A process needed regularly in one repository
Team-wide	The same stable scheme is useful across projects

Common mistakes

Making a skill a universal instruction encyclopedia.
Duplicating CLAUDE.md rules.
Mixing analysis, coding, review, and documentation.
Distributing an immature workflow to every project.
Creating a skill without a verifiable result.