Turn Prompt Engineering into Reusable Skills: A Practical Claude Code Guide

TL;DR

Skills encapsulate procedural knowledge : they package workflows, templates, checklists, and script entry points into a load‑on‑demand module.

Core mechanism is progressive disclosure : initially load only name/description, then fetch SKILL.md, and finally read references/ or execute scripts/ as needed.

Deterministic execution is the biggest benefit : scripts handle multi‑step, certain parts while the model only orchestrates and judges.

Three deployment keys : keep the entry short (<500 lines), write a concrete description (routing rules), and define clear, automatable acceptance criteria.

Team usage is a shared library : store Skills in a version‑controlled repository alongside CLAUDE.md, rules/, commands/, hooks/, and MCP.

1) What Skills Actually Are

A Skill is a directory that contains three parts:

Command entry ( SKILL.md ) : describes what to do, in what order, and how to validate.

Reference material ( references/ ) : standards, templates, checklists, examples, loaded on demand.

Executable scripts ( scripts/ ) : deterministic actions that the model can invoke.

2) Why Teams Need Skills

2.1 Consistency

Without a shared asset, each team member rewrites prompts for tasks such as code reviews, incident triage, or weekly reports, causing drift.

2.2 Acceptance

Skills embed tests, format checks, and output structures so results are objectively verifiable rather than “looks right”.

2.3 Context Overhead

Loading full SOPs into a single prompt makes interactions slower and messier. Skills load information only when needed, keeping the active context small.

3) How Skills Work – Progressive Disclosure

Discovery : read name/description to build a capability catalog.

Activation : when a user intent matches, load the full SKILL.md content.

Execution : during runtime, fetch additional references or run scripts for detailed steps.

4) Physical Shape of a Skill

A minimal Skill directory looks like:

my-skill/
├── SKILL.md          # required entry + metadata
├── references/       # optional: standards, templates, checklists
│   ├── checklist.md
│   └── templates.md
└── scripts/          # optional: executable scripts (recommended)
    └── run.sh

Skills can live in a personal folder ( ~/.claude/skills/) or a project‑level folder ( .claude/skills/) that is version‑controlled.

4.1 SKILL.md Header

The YAML header determines whether the Skill is triggerable. Essential fields include: name: short, stable identifier (always required). description: routing trigger; specify when to use and expected output (always required). allowed-tools: constrain execution surface for security‑sensitive or read‑only flows. context: fork: isolate noisy context for multi‑step or heavy‑log skills. user-invocable: expose as an explicit command (e.g., /xxx) for team members.

Example header:

---
name: code-review
description: 代码评审清单与输出规范。用于 PR 评审、风险识别、可维护性建议与测试补齐。触发词：代码审查、review、PR、可维护性、风险、测试覆盖。
---

4.2 SKILL.md Body

The body should contain only three sections:

Process : ordered steps to perform.

Boundaries : conditions when not to run or required user input.

Acceptance : concrete, automatable criteria (tests, schema checks, sample output).

Detailed templates, checklists, or examples belong in references/ and are referenced from the body.

4.3 Scripts

Scripts handle deterministic work such as format linting, batch file processing, log extraction, or test execution. The model only invokes the script and reads its output, keeping the context clean and improving stability and cost predictability.

5) Team Adoption – Skills as “Configuration‑as‑Code”

Integrate Skills into a broader configuration stack: CLAUDE.md: project‑level memory and conventions. rules/: mandatory policies (security, testing, Git flow). commands/: one‑click high‑frequency workflows (e.g., /plan, /code-review). agents/: sub‑agents for planning, review, triage, E2E testing. hooks/: automated guards (reminders, blocks, consistency checks). skills/: reusable method modules loaded on demand.

MCP configuration: connect external systems (DB, SaaS, GitHub, etc.).

This structure enables PR‑based review of Skill changes, clear evolution of SOPs, and auditability.

6) Common Pitfalls

Entry file too long – hide details behind references/.

Overly generic description – write routing rules with concrete trigger words.

No acceptance criteria – define test commands, schema checks, or output examples.

Relying entirely on model reasoning – script deterministic parts.

Turning Skills into personal cheat‑sheets – keep each Skill focused on a single workflow for composability.

7) Security & Governance

When Skills become executable, enforce three safeguards:

Least‑privilege: read‑only wherever possible.

Auditable actions: encode critical steps in rules/, commands/, and hooks/.

Treat external inputs as untrusted: sanitize web tickets, emails, or issue bodies before execution.

8) Quick‑Start Action Checklist (30 minutes)

Select a high‑frequency task (e.g., PR review, incident triage, weekly report).

Write a short entry file containing process, boundaries, and acceptance.

Script the deterministic parts (validation, log extraction, table generation).

Validate with two real examples, checking triggerability, step execution, and verifiable output.

When these checks pass, the Skill is already more valuable than the majority of ad‑hoc prompt templates.