Build Artifact Checker
Validate build scripts catch missing inputs, size limits, and stale artifacts before shipping.
Installation
- Make sure Claude is on your device and in your terminal.
Skills load from
~/.claude/skills/when Claude Code starts up β so you need it on your machine first. If you don't have it yet, install it once with the command below, then runclaudein any terminal to verify.One-time setupnpm i -g @anthropic-ai/claude-codeAlready have it? Skip ahead.
- Paste into Claude Code or into your terminal.
This copies the whole skill folder into
~/.claude/skills/shipping-build-artifacts-kajisho5/β the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Works for every skill.What this command does
- Makes a new, empty temporary folder.
- Downloads the skill's folder,
.claude/skills/build-artifacts, fromgithub.com/kajisho5/ffmpeg-skill(branchmain), the GitHub repository it's listed from. You get the version that is there now, not a copy we keep. - Copies that folder to
~/.claude/skills/shipping-build-artifacts-kajisho5/. - Deletes the temporary folder.
Installing runs none of the skill's files; it only downloads and copies them. When you later use the skill, Claude follows its SKILL.md and may run scripts that come with it. Read them first.
Faster alternative (instruction-only skills)
Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates β they won't be downloaded and the skill will fail when it tries to load them.
Quick install (SKILL.md only)Sign up to copy - Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from
~/.claude/skills/). New skills are picked up on startup. - Just ask Claude.
Skills auto-activate when your request matches the skill's description β no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the βWhat this skill doesβ section above.
Prefer to read the source first? Open on GitHub.
When Claude uses it
Make the build step a real gate on what you actually distribute β build scripts that warn and exit 0 on a missing input, size checks with only an upper bound, hand-maintained file lists that drift from the entrypoints they must cover, committed bundles that go stale when only the source changes, GNU-only shell in release scripts that aborts on the other OS, and verification that runs against the source tree instead of the artifact. Use when writing or reviewing a build/package script, a `dist/` copy step, a release workflow that uploads a zip or installer, or a committed compiled asset.
What this skill does
Shipping Build Artifacts
Lint, type-check, and tests run against the source tree. What users install is a different set of bytes β assembled by a script that most gates never look at, then uploaded by a workflow that trusts whatever the script left behind. Every failure below ships a broken or stale artifact under fully green CI.
A script that warns and exits 0 is not a gate
The shape is universal: a declared list of inputs, a copy loop, a friendly warning when one is missing.
for (const f of DIST_FILES) {
if (!fs.existsSync(f)) {
console.warn(`Warning: ${f} not found, skipping`); // build "succeeds"
continue;
}
fs.copyFileSync(f, path.join("dist", f));
}
Move one required file aside and the script prints a line nobody reads, exits 0,
and produces a dist/ without it. Nothing downstream notices: the test job ran
against the source tree, and the release job zips dist/ and attaches it to a
public release. The artifact is wholly non-functional β the entrypoint imports a
file that isn't there β and the failure is discovered by users.
const missing = DIST_FILES.filter((f) => !fs.existsSync(f));
if (missing.length) {
console.error(`Missing build inputs: ${missing.join(", ")}`);
process.exit(1);
}
The rule: inside a build script, warn may only describe something the artifact
survives without. If you cannot say what still works when that file is absent, it
is an error and the process must exit non-zero.
Bound the artifact size on both sides
A packaging check with only a ceiling β "fail if the zip exceeds 500 KB" β is a cost guard, not a correctness one. A build that silently dropped half its files is smaller, so it passes the only check that exists.
assert(bytes < 500 * 1024, "package too large");
assert(bytes > 20 * 1024, "package suspiciously small β inputs likely missing");
assert(entries.length === DIST_FILES.length, "package entry count mismatch");
Better still, assert on contents rather than a proxy: list the archive's entries and compare against the set the entrypoints require.
Derive the file list, or check it against the entrypoints
DIST_FILES β like a build backend's only-include, or a hand-written
package_data β is a second copy of "what this app is made of." The first copy
is the manifest, the entry HTML, and the import graph. They drift in one
direction: someone adds utils.js, references it from the popup, and forgets the
copy list. The build stays green and the feature is dead in the packaged app.
Either derive the list (bundle from the real entrypoints), or add a check that
every path referenced by the manifest and by <script src> / importScripts
exists in dist/ after the build. A hand-maintained allowlist with no such check
is a bug scheduled for a future commit.
The same rule covers any place dependency or asset metadata is restated by hand β
a standalone launcher script whose inline dependency header duplicates the
project manifest's dependencies, for instance. If duplication is unavoidable,
add a test that normalizes both lists and compares them, so drift fails in CI
instead of at a user's install.
Committed build outputs go stale silently
When a compiled or minified bundle is committed and served directly, the bundle is the program and its source is a comment until someone rebuilds. Editing only the source ships nothing; the page keeps serving the previous bundle, and no test or linter says a word.
- Rebuild in CI and
diffagainst the committed output; fail on drift. - Pin the builder to an exact version β the diff is only meaningful if the output is byte-deterministic.
- Confirm that determinism once across the environments people actually use (native toolchain vs. container image), so the check is runnable locally too.
npx -y esbuild@0.24.2 src/app.jsx --jsx=transform --minify --outfile=/tmp/app.js
diff /tmp/app.js web/app.js
Rebuild and commit the output in the same commit as the source change. A "rebuild bundles" follow-up commit means every commit in between shipped code that does not match its source.
Release scripts run on an OS you didn't write them on
Build scripts are written on a developer machine and executed on the runner.
GNU-only tooling is the usual break, and set -e turns it into a total abort on
a line that merely reads a version number:
# Breaks under BSD grep (macOS): -P / lookbehind are GNU extensions.
VERSION=$(grep -Po '(?<=^version = ")[^"]+' pyproject.toml)
Read structured metadata with a parser instead of a regex, and prefer a runtime you already depend on:
VERSION=$(python -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')
VERSION=$(jq -r .version package.json)
Then pin it with a test: the version the build script extracts must equal the
version declared in the project manifest. Without that, the failure mode is a
release tagged v1.4.0 whose artifact reports 1.3.2, and nothing in the
pipeline disagrees.
Verify the artifact, then publish β in that order, in that job
Attaching a file to a public release, pushing a tag, or uploading to a registry are the least reversible steps in the project. The verification must sit between the build and the upload, in the same job. A separate green "test" job proves nothing about the artifact: it ran against the source tree.
Minimum ordering:
- Build.
- List every entry in the artifact and assert the entrypoints are present.
- Install or load it from a directory the source tree is not on the load path of, and exercise one real symbol or command β not merely that a top-level name resolves.
- Only then upload.
Step 3 is the one that gets skipped, and it is the only step that distinguishes "the archive has files in it" from "the thing runs." Run it somewhere else on disk, or it passes against the sources and proves nothing.
Checklist
Build script:
- [ ] Missing declared input β non-zero exit, not a warning
- [ ] Size assertions have a floor as well as a ceiling
- [ ] File list is derived, or checked against manifest/entry-HTML references
- [ ] Duplicated dependency metadata has a drift test
- [ ] No GNU-only flags (grep -P, sed -i'' semantics) in scripts CI also runs
- [ ] Version extracted with a parser, and asserted equal to the declared version
Committed build outputs:
- [ ] CI rebuilds and diffs; drift fails
- [ ] Builder pinned to an exact version; output confirmed deterministic
- [ ] Output committed alongside the source change, not in a follow-up
Release:
- [ ] Artifact contents listed and asserted before upload
- [ ] Artifact installed/loaded from outside the repo and exercised
- [ ] Verification runs in the same job as the upload, before it
Note for this repository (ffmpeg-skill)
package.json's "files" list is the equivalent of DIST_FILES here β it must
list exactly what ships (bin/, scripts/, templates/, mcp/, the shipped
references/*.md files one by one, docs/contract.md, SKILL.md, README.md,
LICENSE), and .claude/ (this file included) must NEVER appear
in it. npm publish --dry-run is the "list every entry and assert the
entrypoints are present" step (step 2 above) β run it before every publish, and
watch for stray __pycache__/.pyc files sneaking into the tarball from a
local test run (this actually happened once this session and was caught by
exactly this check). The "install from outside the repo and exercise a
symbol" step is npm run release-check (tests/release_check.sh): it packs
the tarball, installs from it into a temp HOME, and asks the installed copy
for its contract, its MCP tool list and doctor.
Source: wdm0006/python-skills (MIT).
Related skills
Documentation Co-Authoring
anthropics
Guide structured workflows for writing docs, proposals, and technical specs collaboratively.
MCP Server Builder
anthropics
Build protocol servers that connect language models to external APIs and services.
Skill Builder & Optimizer
anthropics
Create, edit, and optimize Claude skills with performance testing and benchmarking.
Multi-Component Web Artifacts
anthropics
Build complex React artifacts with Tailwind CSS and shadcn/ui components.