Package, document, and version the skill

A skill ships as a directory. Make that directory understandable to someone who has never talked to you.

Validate everything

Before you package, run through the checks:

• the SKILL.md frontmatter parses and the name matches the folder
• the bundled script’s tests pass
• every relative link in SKILL.md points at a file that exists
• nothing in the folder is an absolute path, a temporary report, a credential, a private project name, or a generated file

A quick way to catch the last group:

rg -n "/Users/|/home/|TOKEN|SECRET|password" release-readiness/

If that prints anything, look at it before you ship.

License, version, compatibility

Add a license field when you want others to reuse the skill. Without one, most people can’t legally do so.

Add version information in metadata if your distribution process needs it. Don’t add it because it feels professional. An unmaintained version number is worse than none.

State compatibility only for real requirements. We covered ours: Git, a host that runs local commands, Node.js for the validator.

Record the owner and the source repository in your project’s documentation, not in new required fields you invented. Other hosts won’t know what to do with them.

What goes in the box

The final package for our project:

release-readiness/
├── SKILL.md
├── assets/
│   └── release-report.md
├── references/
│   └── npm.md
└── scripts/
    └── validate-report.mjs

Four files. That’s it.

Don’t bundle evaluation outputs, local caches, copied sample repositories, or anything with a secret in it. The evaluation suite stays beside the skill in its development repository, where you can rerun it. It’s not part of what you distribute.

Installation is part of the test

Install the packaged folder in a clean environment. A fresh clone, a different machine, a colleague’s laptop. Then:

1. Confirm the skill is discoverable by asking the agent what skills it has.
2. Run one positive activation prompt and one negative one.
3. Complete a full readiness review on a sample repository.
4. Run the validator on the report it produced.

This is roughly what you want to see in the trace:

Loaded skill: release-readiness
Reading references/npm.md (package.json has a publish script)
Running scripts/validate-report.mjs release-report.md
report structure ok

If step 1 fails, it’s usually the name or the folder location. If step 3 fails somewhere the source checkout didn’t, you had an absolute path or an assumption about your machine.

A folder that only works from where you wrote it isn’t portable, and portability is the whole reason the format exists.