How to Package a Skill for Claude Code Agents

If you are learning how to package a skill for Claude Code agents, start by thinking like a tool maintainer—not a prompt collector. A useful skill packages one repeatable behavior with the metadata, instructions, examples, scripts, and checks an agent needs to perform it reliably.

The difference matters. A 700-line file that says “be a senior engineer” is difficult to trigger, difficult to test, and difficult to improve. A focused package that reviews a pull request against five explicit rules can become a dependable part of a team workflow.

This guide builds a practical skill from scratch, explains where each file belongs, and shows how to choose between a project skill, a personal skill, and a plugin.

How to Package a Skill for Claude Code Agents: The Core Model

Claude Code skills are filesystem-based packages. The required entry point is SKILL.md, and the directory can also contain references, templates, examples, and executable scripts. Claude can discover the skill from its frontmatter description and load supporting material when the task needs it.

The official Claude Code documentation describes the pieces that can live around SKILL.md, including supporting files, invocation controls, dynamic context, and subagent execution.

A minimal package looks like this:

# Skill package layout
.claude/skills/pr-review/
├── SKILL.md
├── references/
│   └── review-checklist.md
├── examples/
│   └── good-review.md
└── scripts/
    └── collect-diff.sh

Use the main file for the behavior and the decision process. Move long reference material into references/. Put deterministic work—such as collecting a diff or running a validator—in scripts/. Examples should demonstrate the output you actually want.

That separation is the foundation for a package that stays readable as it grows.

Design the Skill Around One Repeatable Behavior

Start with a failure you have seen more than once. Good skill candidates include:

• reviewing pull requests against project-specific rules;

• preparing release notes from a diff;

• checking accessibility before shipping a page;

• migrating a known kind of configuration;

• turning a research process into a repeatable brief.

Write the behavior as an observable outcome. “Improve code quality” is too broad. “Review the staged diff for missing tests, unsafe input handling, and public API changes, then produce a severity-ranked report” is testable.

Keep the scope narrow enough that you can answer three questions:

1. When should this skill trigger?

2. What inputs does it need?

3. What output proves that it worked?

The Anthropic guide to building skills and Anthropic’s lessons from operating many internal skills both emphasize a useful principle: do not restate generic model abilities. Add the project knowledge, workflow, constraints, and gotchas that change the result.

Once the behavior is specific, the package becomes much easier to design.

Build the Package: Frontmatter, SKILL.md, and Supporting Files

Create the directory in the scope where it belongs:

# Project-scoped skill
.claude/skills/pr-review/SKILL.md

# Personal skill shared across your projects
~/.claude/skills/pr-review/SKILL.md

Then write frontmatter that acts as a trigger, not just a marketing summary:

---
name: pr-review
description: Review staged or pull-request changes for project-specific correctness, security, testing, and API-compatibility risks. Use when reviewing a PR, checking a diff before merge, or auditing a proposed change.
---

The description should contain the situations that should activate the skill and the terms a user is likely to use. Avoid “A helpful code review skill.” It describes the package but gives the agent little signal about when it applies.

Next, keep SKILL.md procedural and compact:

# Pull-request review

## Inputs

- The current diff or pull request
- Project instructions from CLAUDE.md
- Tests and checks relevant to changed files

## Workflow

1. Read the project instructions and identify the changed surface.
2. Inspect the diff before making recommendations.
3. Check correctness, security, tests, and compatibility.
4. Run the available deterministic checks.
5. Report findings by severity with file and line references.

## Output

Start with blocking findings. Then list non-blocking risks, missing tests, and a short summary.

## Gotchas

- Do not call a review complete because the code looks reasonable.
- Do not invent test results; state when a check could not run.
- Do not report style preferences as bugs unless the project rules require them.

The Gotchas section is especially valuable. It records the mistakes the agent actually makes in your workflow, so the skill improves from use instead of accumulating generic advice.

Add supporting files only when they reduce repetition or improve accuracy. A reference file can contain a longer API checklist. An example can show the exact review format. A script can collect changed files or invoke a linter. If a file is not needed for the behavior, leave it out.

Add Gotchas, Tests, and Deterministic Quality Gates

Instructions guide an agent; they do not make its behavior deterministic. Treat a skill like a small software tool and test it with representative tasks.

Create at least three test cases:

• a clean change that should produce no blocking findings;

• a change containing an obvious defect;

• an ambiguous change where the correct response is to ask for context or report uncertainty.

For each case, check whether the skill triggers, whether it reads the right files, and whether the output follows the required format. Repeat the test after changing the description or workflow. A skill that works only when you manually explain it is not packaged well yet.

Pair model instructions with deterministic checks wherever possible:

• linters and formatters for style;

• type checking for interface errors;

• unit and integration tests for behavior;

• secret scanners for accidental credentials;

• shell scripts that fail loudly when required inputs are missing;

• CI checks that validate the final artifact.

This is also where security belongs. A third-party skill may include shell commands, hooks, network access, or instructions to read sensitive files. Review every script before installing it, pin dependencies where appropriate, and avoid granting more access than the workflow needs.

Community discussions repeatedly surface the same lesson: specific rules plus a post-write review outperform vague attempts to force an agent to be perfect on its first pass. The skill should create a reliable loop—inspect, act, verify—not merely issue stronger-sounding instructions.

That loop is what turns a markdown file into a useful engineering asset.

Choose the Right Distribution Path

Use the smallest distribution mechanism that matches your audience.

Project skill

Put the package in .claude/skills/ when it encodes repository-specific rules. Anyone who clones the project can discover the same workflow, and changes can be reviewed alongside code.

Personal skill

Put it in ~/.claude/skills/ when it represents your own preferences or a workflow you use across unrelated projects. Examples include commit-message style, research structure, or a personal debugging routine.

Git repository

Use a repository when several people need to install or review the package independently. Include a README, version history, compatibility notes, and a small test fixture. Treat the repository as the source of truth rather than copying edited files between machines.

Plugin or marketplace package

Use a plugin when you need to distribute several skills together with commands, hooks, agents, or MCP configuration. This adds installation and versioning convenience, but also increases the trust surface. Document what the package can execute and what permissions it expects.

The boundary is simple: CLAUDE.md is for context that should apply broadly, a skill is for on-demand behavior, and a plugin is a bundle for distribution. The Claude Platform documentation on Agent Skills is a useful reference when deciding how the package should be structured.

Do not choose a marketplace merely because it sounds more professional. Choose it when repeatable installation, versioning, and discoverability justify the extra packaging work.

A Complete Packaging Checklist

Before sharing a skill, verify each layer:

• The directory name is short and descriptive.

• SKILL.md exists at the expected path.

• Frontmatter is valid and the description includes clear trigger situations.

• The skill solves one coherent problem.

• Instructions describe inputs, workflow, output, and stopping conditions.

• Long material is moved into references instead of bloating the main file.

• Examples show realistic successful output.

• Scripts validate inputs and fail safely.

• Gotchas capture observed failure modes.

• At least one clean case and one failure case have been tested.

• Deterministic checks are used where they are available.

• Compatibility and required tools are documented.

• No secret, destructive command, or unnecessary network access is hidden in the package.

• The installation path and update process are clear.

The best package is usually smaller than the first draft. Start with the narrowest useful behavior, test it, then add a reference or script only when a real failure justifies it.

Packaging a skill for Claude Code agents is ultimately an exercise in operational clarity. The markdown is only the visible part. The real value comes from a precise trigger, a focused procedure, useful resources, explicit failure handling, and a verification loop that keeps the agent honest.

If you build skills that way, they become reviewable tools your team can maintain—not mysterious prompt files that happen to work once.