Add focused references and assets

References hold context the agent needs only in some situations. Assets hold inputs and templates the agent uses to build the result. Keep the two roles separate, and keep both out of SKILL.md.

References are conditional

For release readiness, ecosystem-specific knowledge goes in references. references/npm.md explains how to inspect a package tarball with npm pack --dry-run. references/python.md covers pyproject.toml metadata and building a wheel.

The main workflow tells the agent to open one of them only after it has identified the ecosystem. A Go project never loads npm.md. That’s the whole point.

Keep them small and flat

Don’t write one 5,000-line references/everything.md. Smaller files cost less context and make the loading decision obvious.

Also avoid chains. If SKILL.md points to references/checks.md which points to references/npm-details.md, the agent follows a maze and you lose track of what got loaded. Link every resource directly from SKILL.md, one level deep.

Assets are copied

The report template lives in assets/release-report.md because the agent copies it and fills in the blanks. Make the placeholders unmistakable. [version] and [GO, NO-GO, or NEEDS REVIEW] are hard to leave in by accident.

Never put live credentials, paths from your own machine, or stale project values in an asset. Assets get copied into other people’s repositories. Whatever is in there travels.

Start each reference with its condition

Add one ecosystem reference that matches your sample repository. Start it with the sentence that names when to read it:

# npm release checks

Read this only when the repository has a package.json with a "publish"
or "prepublishOnly" script, or the user names npm as the target.

## Inspect the tarball

Run `npm pack --dry-run` and compare the file list against .npmignore.

Then add the report template from the previous module to assets/.

The context audit

Now go through every resource and answer four questions:

• What exact condition loads it?
• Which decision gets better after reading it?
• Could the agent already infer this on its own?
• Who updates it when the ecosystem changes?

A resource without convincing answers gets deleted. I’ve deleted references I’d spent real time on because the honest answer to the third question was “yes, the agent knows this already”.

A smaller skill is usually the stronger skill. Every file you keep is a file someone has to keep true.