Why I built npx build-skill

If you're not familiar, Agent Skills are the open standard for packaging instructions, scripts, and resources that AI coding agents can discover and use — think Claude Code, Cursor, Codex, and dozens of others. It's a simple idea with a lot of power: you write a SKILL.md file, structure a folder around it, and suddenly your agent knows how to do something new.

The concept is great. The setup? Not so much.

The problem I kept running into

Every time I wanted to create a new skills repository, I found myself doing the same tedious dance. Create the folder structure. Write the SKILL.md with the right frontmatter. Set up the .claude-plugin/marketplace.json. Wire up a plugin.json for each skill. Add a GitHub Actions workflow for validation. Write sync scripts to keep the README and marketplace config in sync as skills get added or removed.

None of it is hard. All of it is annoying. And if you get the structure wrong, your skills just silently don't work — no error, no feedback, just an agent that doesn't pick up what you built.

I caught myself copy-pasting from old repos more than once, and that's usually my signal that something should be automated.

What build-skill does

It's a single command:

npx build-skill

You answer a few prompts — your brand name, skill name, description — and it generates a complete, spec-compliant skills repository. The output includes the folder structure the spec expects, a SKILL.md with proper frontmatter, marketplace and plugin configs, a GitHub Actions workflow that validates skills on PRs and syncs everything on push to main, and helper scripts so adding new skills later is just as painless. There's also a quiet mode (--quiet) with CLI flags for everything, so you can use it in CI pipelines or script it into your own tooling.

Why not just use a template repo?

I tried that first, honestly. But template repos have a few problems in this context. You still have to manually find-and-replace your brand name, skill name, and description across multiple files. The marketplace config and plugin.json need to reference the right paths. And every time the spec evolves, you're updating a template instead of bumping a version.

With a CLI, the scaffolding adapts. You run the latest version and get the latest structure. No stale templates, no missed replacements.

The broader picture

The Agent Skills ecosystem is still early, but it's moving fast. Vercel launched the skills CLI, Ian Nuttall added support for skills to Playbooks, and Context7 even jumped in to add skills support. The spec at agentskills.io is becoming a real standard. More developers are going to want to package their team's coding standards, deployment workflows, or domain knowledge into skills. The less friction there is in getting started, the more skills get built.

That's really all build-skill is: removing the friction between "I have an idea for a skill" and "I have a working repo ready to publish."

Try it out

npx build-skill

It's open source under MIT. I'd genuinely love feedback; whether it's missing options you'd want, structure decisions you'd do differently, or skills you're building that surface edge cases. The repo is at github.com/Flash-Brew-Digital/build-skill and issues/PRs are welcome.