Packaging a skill for Claude adds a distribution boundary. Validate the manifest, relative paths and installed tool connection rather than assuming a folder that works in a checkout will work after installation.
- 1Plugin folder
- 2Manifest validation
- 3Clean install
- 4Tool check
Work through the example
Inspect the repository's Claude package layout and verify which files are included. Keep machine-specific paths out of the distributable.
Start with a disposable branch and synthetic data. Write the expected outcome before changing the implementation, then keep the first failing result. This prevents a later repair from quietly redefining the task. The procedure below is grounded in the repository reference; its examples must still be checked against your project and installed toolchain.
Package the skill separately from your app
A Claude plugin exercise starts with a package root containing .claude-plugin/plugin.json and the skill directory. Keep application source outside that distribution folder unless it is an intentional example.
my-swift-review/
.claude-plugin/
plugin.json
skills/
swift-review/
SKILL.md
A minimal manifest supplies an identity and description:
{
"name": "my-swift-review",
"version": "0.1.0",
"description": "A focused Swift review procedure."
}
The skill should identify its trigger and required inputs, then tell the agent to inspect a bounded diff, locate findings and report evidence. Avoid filling the skill with installation commands for unrelated clients.
Check the package boundary
Parse the manifest with python3 -m json.tool .claude-plugin/plugin.json, confirm the skill file exists, and inspect the package inventory before testing installation. Follow Claude's current plugin documentation for the installed version rather than assuming another client's ZIP layout or manifest schema applies.
After installation, run a synthetic review that actually triggers the skill. Confirm both discovery and the relevant behavior. If the plugin also configures MCP or hooks, test those surfaces independently: the skill loading does not prove the server started, and the server starting does not prove the hook dispatched.
Keep one installation route active during diagnosis. A direct MCP registration plus a plugin-provided registration can make duplicate tools look like a packaging defect. Record the client version, package version and the exact scope of the test before sharing the plugin.
Acceptance and failure review
| Checkpoint | What to inspect | If it does not match |
|---|---|---|
| Plugin folder | Confirm the input and environment | Preserve the failure and return to this step |
| Manifest validation | Inspect the intermediate artifact | Preserve the failure and return to this step |
| Clean install | Run the focused check | Preserve the failure and return to this step |
| Tool check | Record the observed result | Preserve the failure and return to this step |
Ask the agent to explain the smallest change that resolves the observed mismatch. Keep unrelated refactors out of the repair. A change that makes a warning disappear is not enough if the behavior or ownership contract has changed. Re-run the same acceptance check so the before and after results are comparable.
Evidence and limits
A marketplace submission is not acceptance or an installed-client test.
This is an educational guide. Its presence in the series does not certify a completed client-specific lab. The series evidence record separates executed checks from exercises and blocked environments.
Inspect the source used in this lesson.
Related reading
- How can Claude Code hooks protect generated files and verify a project before stopping?
A tested generated-file guard and Stop check, with configuration, reproducible exit codes, and enforcement limits.
- Claude Code: turn a Swift finding into a tested patch
A small review-to-test loop for an existing iOS project.