I built npx build-skill, here's why you should use it

Every time I wanted to create a new AI agent 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 marketplace config. Wire up GitHub Actions for validation. Write sync scripts. Copy-paste from old repos and hope I didn't miss a replacement.

I got tired of it, so I built build-skill.

npx build-skill

One command. Answer a few prompts. Get a complete, spec-compliant skills repository ready to publish.

What is build-skill?

build-skill is an open source CLI that scaffolds AI agent skill repositories following the Agent Skills Specification. It generates everything you need to start writing and distributing skills for AI coding agents like Claude Code, Cursor, Codex, and 35+ others.

Think of it like create-react-app, but for agent skills.

The problem it solves

If you've tried creating a skills repository from scratch, you know the setup is tedious. A properly structured repo needs a specific folder layout with SKILL.md files containing correct YAML frontmatter, a .claude-plugin/marketplace.json for the plugin marketplace, a plugin.json inside each skill's directory, a GitHub Actions workflow for validation on PRs and syncing on push, and helper scripts to keep your README and configs in sync as you add or remove skills.

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.

What you get when you run it

When you run npx build-skill, the CLI walks you through a few prompts (your brand name, skill name, and description) and generates this structure:

your-brand-skills/
├── .claude-plugin/
│   └── marketplace.json
├── .github/
│   └── workflows/
│       └── process-skills.yml
├── scripts/
│   ├── add-skill.js
│   └── sync-skills.js
├── skills/
│   └── your-skill-name/
│       ├── .claude-plugin/
│       │   └── plugin.json
│       └── SKILL.md
└── README.md

The GitHub Actions workflow validates all skills on pull requests using the Validate Agent Skill action and syncs the README, marketplace.json, and plugin configs on push to main. That means your repo stays correct without manual maintenance.

How to use it

Interactive mode

The simplest way to get started:

npx build-skill

You'll be prompted for your brand/organization name, skill name, and a description of what the skill does.

Quiet mode for CI and scripting

If you want to skip the prompts (useful for CI pipelines or scripting), pass everything as flags:

npx build-skill \
  --brand acme-corp \
  --name data-processor \
  --description "Processes CSV and JSON data files" \
  --quiet

Adding more skills later

The generated repo includes a helper script for adding new skills:

node scripts/add-skill.js my-new-skill "Description of what it does"

This creates the skill directory, generates the SKILL.md and plugin.json, and automatically runs the sync script to update your README and marketplace config.

Why not just use a template repo?

I tried that first. 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.

Where this fits in the ecosystem

The Agent Skills ecosystem is growing fast. Vercel launched the skills CLI as a package manager for skills. Anthropic baked skills into Claude Code. The Agent Skills Specification is becoming a real standard across 35+ agents.

build-skill sits at the beginning of that workflow. Before you can install, share, or discover skills, someone has to create them. And the less friction there is in getting from "I have an idea for a skill" to "I have a working repo ready to publish", the more skills get built.

Frequently Asked Questions

What agents does build-skill support?

build-skill generates repositories that follow the open Agent Skills Specification. Any agent that supports this spec can use the skills you create. That currently includes Claude Code, Cursor, Codex, Windsurf, OpenCode, GitHub Copilot, and over 35 others.

Do I need to install build-skill globally?

No. Running npx build-skill fetches and runs the latest version without a global install. If you prefer a global install, you can run npm install -g build-skill.

Can I add multiple skills to one repository?

Yes. The generated repo is designed for multiple skills. Use the included add-skill.js script to add new skills, and the sync-skills.js script keeps your README and marketplace config up to date automatically.

Is build-skill tied to Claude Code specifically?

No. While the generated repo includes .claude-plugin configs for Claude Code's marketplace, the skills themselves follow the open Agent Skills Specification and work across any compatible agent.

How is this different from npx skills init?

npx skills init creates a single SKILL.md file. build-skill scaffolds an entire repository with CI/CD workflows, marketplace configuration, sync scripts, and helper utilities for managing multiple skills over time.

Get started

npx build-skill

The project is open source under MIT. The repo is at github.com/Flash-Brew-Digital/build-skill and the package is on npm.

Issues, PRs, and feedback are all welcome. I'm curious what skills you're building for your agents.