DEV Community

Cover image for Sharing skills with NPX
baltz
baltz

Posted on

Sharing skills with NPX

#ai #beginners #productivity #tutorial

Maintaining, sharing, and updating skills can get messy when a team grows. People copy files around, different agents end up with different versions, and small process improvements get lost in chat.

We can make easier with the skills package: a small CLI you can run with npx to install, list, update, and remove skills across different coding agents.

The idea is simple: put a skill in a GitHub repo, and anyone can install it with one command.

It looks like the skill was published to npm, but that is not what is happening.

When you run:

npx skills@latest add owner/repo --skill my-skill
Enter fullscreen mode Exit fullscreen mode

the flow is roughly:

npx runs the "skills" CLI
skills reads the GitHub repo
skills looks for SKILL.md files
skills installs the skill into the agent
Enter fullscreen mode Exit fullscreen mode

So you do not need to publish an npm package, create your own registry, or ask someone to copy files by hand.

The CLI can read a few different sources: GitHub shorthand like owner/repo, a full GitHub URL, a direct path to a skill inside a repo, a GitLab URL, any git URL, or even a local folder while you are testing.

You only need a folder like this in your repo:

skills/
  my-skill/
    SKILL.md
Enter fullscreen mode Exit fullscreen mode

And a basic SKILL.md:

---
name: my-skill
description: "When the agent should use this skill."
---

# My Skill

Instructions the agent should follow.
Enter fullscreen mode Exit fullscreen mode

After that, publishing is just commit and push.

One nice detail: the same CLI also handles maintenance. You can list installed skills with npx skills list, update them with npx skills update, and remove them with npx skills remove.

Our first skill

In this repo, I created a small skill called quality-gate.

It does one thing: at the end of a technical coding task, the agent should run the best quality gate available in the project before handing the task back.

That might be lint, tests, type check, build, formatting. It depends on the project.

To list the skills in the repo:

npx skills@latest add baltazarparra/ai-native-engineering --list
Enter fullscreen mode Exit fullscreen mode

To install quality-gate:

npx skills@latest add baltazarparra/ai-native-engineering --skill quality-gate
Enter fullscreen mode Exit fullscreen mode

To install it globally for Codex:

npx skills@latest add baltazarparra/ai-native-engineering --skill quality-gate --agent codex --global
Enter fullscreen mode Exit fullscreen mode

By default, skills installs into the current project. With --global, it installs into your user directory, so the skill is available across projects. For Codex, that global location is ~/.codex/skills/.

You can also make the command non-interactive with --yes, which is useful for setup scripts:

npx skills@latest add baltazarparra/ai-native-engineering --skill quality-gate --agent codex --global --yes
Enter fullscreen mode Exit fullscreen mode

Why this is nice

Skills are a lightweight way to share process.

Every team has small habits that make the work better: how to review a PR, how to validate a change, how to write release notes, how to investigate a bug, how to prepare a handoff.

Usually, that stuff lives in chats, forgotten docs, or in the heads of people who have been around longer.

With skills, that process becomes a versioned file that is easy to review, install, and update.

The point is not to make the agent "smarter". It is to make the agent more aligned with the way you want to work.

The catch

A good skill does not need to be big.

In fact, it is usually better to start small:

  • one clear behavior;
  • one obvious trigger;
  • a few steps;
  • one validation at the end.

For us, quality-gate is exactly that: an operational reminder so the agent does not hand back code before validating it.

Small, simple, useful.

More about Skills? https://baltazarparra.github.io/ai-native-engineering/en/skills/

Top comments (1)

Collapse
 
baltz profile image
baltz •

baltazarparra.github.io/ai-native-...