Project - ship a skill to the community

The previous lessons built the skill. This session ships it. Publishing a skill is not a formality — it is the moment when the procedure stops being yours and becomes available to anyone who needs it.

What this actually is

This is a completion exercise. You take one of the skills written in the earlier sessions, bring it to a publishable standard, and submit it to the skills registry. "Publishable standard" means specific things: a working procedure, comprehensive gotchas, a README that explains when to use the skill and when not to, and at least one test run documented.

Walk-through

Step 1: Choose the skill to publish.

Pick the skill that is most useful, most complete, and most general. A skill for your specific internal deployment pipeline is not a good candidate for public distribution. A skill for deploying a Next.js site to Vercel is.

Step 2: Polish the procedure.

Read each step aloud. If you stumble, the step is not clear. Rewrite it until you do not stumble. Check that every step has a success criterion where failure is possible.

Step 3: Expand the gotchas.

Before publishing, run the skill on at least two different environments (two different machines, two different operating systems, two different project configurations). Add a gotcha for every deviation you observe.

Step 4: Write the README.

The README is separate from the skill file itself. It answers:

• What does this skill do?
• When should you use it? (Give a concrete example.)
• When should you not use it? (This is as important as the positive case.)
• What are the prerequisites?
• How do you install it? (One command.)

# deploy-gh-pages

Deploy a static site from `dist/` to GitHub Pages.

## When to use

Use this skill when you have a static site built by any tool (Vite, Next.js static export,
Astro, 11ty) and want to publish it to GitHub Pages from the command line.

## When not to use

Do not use this skill for server-rendered apps, apps that require a build server,
or repos where GitHub Pages is not enabled.

## Prerequisites

- GitHub repository with Pages enabled (Settings > Pages)
- `gh-pages` npm package: `npm install --save-dev gh-pages`
- GitHub token with `repo` scope

## Install

npx skills add deploy-gh-pages

## Usage

Ask Claude: "Deploy the site to GitHub Pages."

Step 5: Tag the skill.

Tags are how the registry surfaces your skill in search. Use the categories the registry defines: deploy, frontend, github, static-site. Do not invent new categories.

Step 6: Publish.

npx skills publish deploy-gh-pages
# # → Validating skill...
# # → Running smoke tests...
# # → Publishing deploy-gh-pages@1.0.0...
# # → Published. Install with: npx skills add deploy-gh-pages

If you get stuck

If the publish command fails validation: the validator will report which field is missing or malformed. The most common issue is a description that is too long (over 120 characters) or a name that contains spaces or uppercase letters.

If the smoke tests fail: the registry runs the skill against a sandboxed environment to verify it does not error on the happy path. If your skill requires environment-specific configuration ({{DEPLOY_URL}}), document the placeholder convention clearly so the smoke test knows to skip that step.

If you are not sure whether your skill is general enough to publish: ask one person outside your team to read the README and tell you what they would use it for. If they describe a use case you did not anticipate, the skill is general enough.

Deliverable

A published skill with:

• A name and description that pass registry validation
• A procedure with at least five steps and success criteria on each step that can fail
• A gotchas section with at least three entries (trigger, symptom, recovery)
• A README that explains when to use the skill and when not to
• At least one tag matching a registry category

The success criterion: run npx skills add your-skill-name from a fresh environment and verify that Claude can execute the procedure using only a natural-language trigger.

Further reading

• "Agentic Economy, Part 1: Three Sessions Running" — what happens when published skills run in parallel agent sessions across the day, not just in a single chat.
• "Agentic Economy, Part 2: The Plugin That Built Itself" — what changes when a skill is consumed by another agent rather than a human operator.
• "Agentic Economy, Part 3: Nine Personas in a Folder" — the registry shape that lets a folder of personas behave like a small marketplace.