skillflag

skillflag is a minimal CLI convention for bundling, listing and installing agent skills, so that you don't have to upload them to separate 3rd party skill registries.

Spec: Skillflag Specification

Motivation

Think of skillflag as "--help or manpage for skills": a stable flag-based interface to list and export bundled skills without having to upload it to a third party registry. Any relevant agent instructions live right inside your repo and get published together alongside your tool.

Agent skills are self-contained capability packages: a folder with a SKILL.md (name, description, instructions) plus any scripts, templates, and references the agent needs to execute a specific workflow.

With skillflag, CLI tools can bundle and list these skills without having to upload it to a skill registry. With --skill list|show|export, any agent can discover and install instructions that are required to use the tool.

Example

Suppose that you have installed a CLI tool to control Philips Hue lights at home, hue-cli.

To list the skills that the tool can export, you can run:

$ hue-cli --skill list
philips-hue    Control Philips Hue lights in the terminal

You can then install it to your preferred coding agent, such as Claude Code:

$ hue-cli --skill export philips-hue | npx skillflag install --agent claude
Installed skill philips-hue to .claude/skills/philips-hue

You can optionally install the skill to ~/.claude, to make it global across repos:

$ hue-cli --skill export philips-hue | npx skillflag install --agent claude --scope user
Installed skill philips-hue to ~/.claude/skills/philips-hue

Even better, once this convention becomes commonplace, agents will by default do all these before they even run the tool, so when you ask it to "install hue-cli", it will know to run --skill list the same way a human would run --help after downloading a program, and install the necessary skills themselves without being asked to.

Quick setup — add skillflag to your CLI

Copy the prompt below and paste it into your coding agent. It will add skillflag support to your project.

Currently TypeScript/Node only. Open an issue if you'd like support for another language.

Add skillflag to this project so the CLI can bundle and expose agent skills.

1. Install the skillflag library:
   npm install skillflag

2. Create a skill directory at skills/<skill-id>/SKILL.md with a YAML
   frontmatter (name, description) and markdown instructions for the agent.

3. In the CLI entrypoint, intercept --skill and delegate to skillflag:

   import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";

   await maybeHandleSkillflag(process.argv, {
     skillsRoot: findSkillsRoot(import.meta.url),
   });

4. Verify it works:
   <tool> --skill list
   <tool> --skill show <id>
   <tool> --skill export <id> | npx skillflag install

5. For the full integration guide:
   https://raw.githubusercontent.com/osolmaz/skillflag/main/docs/INTEGRATION.md

6. For the skillflag specification:
   https://raw.githubusercontent.com/osolmaz/skillflag/main/docs/SKILLFLAG_SPEC.md

Install (optional)

npm install -g skillflag

You can also run it without installing by using npx (see below).

skillflag is currently implemented in Node/TypeScript. Reach out if you'd like to see it implemented in other languages.

Quick start

Any CLI that implements the skillflag convention can be used like this:

# list skills the tool can export
<tool> --skill list
# show a single skill's metadata
<tool> --skill show <id>
# install into Codex user skills
<tool> --skill export <id> | npx skillflag install --agent codex
# install into Claude project skills
<tool> --skill export <id> | npx skillflag install --agent claude --scope repo

Interactive mode

When --agent or --scope is omitted and a TTY is available, skill-install launches an interactive wizard:

# pipe a skill and let the wizard guide you
<tool> --skill export <id> | npx skillflag install

The wizard lets you pick agents and scopes with arrow keys and space to select, then confirms before installing. This works even when stdin is piped.

Multi-target install

--agent and --scope flags accept a single value each. To install to multiple agents/scopes in one run, use the interactive wizard:

<tool> --skill export <id> | npx skillflag install

In the wizard, select multiple entries with space, then confirm the matrix install.

Add skillflag to your CLI

1. Add the library and ship your skill directory in the package.
2. Add a skills/<skill-id>/SKILL.md in your repo.
3. In your CLI entrypoint, intercept --skill and delegate to skillflag.

npm install skillflag

import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";

await maybeHandleSkillflag(process.argv, {
  skillsRoot: findSkillsRoot(import.meta.url),
});

See the full guide in docs/INTEGRATION.md.

Supported agents

codex, claude, portable, vscode, copilot, amp, goose, opencode, factory, cursor

Supported scopes

| Scope | Description | | ------ | ------------------------------------------------------------- | | repo | Install into the current repository (e.g. .codex/skills/) | | user | Install into the user's home config (e.g. ~/.codex/skills/) | | cwd | Install relative to the current working directory |

Help

skill-install --help

Bundled skill

This repo ships a single bundled skill at skills/skillflag/ that documents both skillflag and skill-install.