Skillflag CLI Convention & Library

0.1.4 · active · verified Wed Apr 22

Skillflag is a CLI convention and library for bundling, listing, and installing agent skills directly from a CLI tool's repository without relying on third-party registries. It provides a standardized `--skill` flag interface (`list`, `show`, `export`) for agents to discover and integrate capabilities. The current stable version is 0.1.4, indicating early development and a nascent ecosystem. As a new project, release cadence is currently irregular, but recent updates suggest active development. Its key differentiator is decentralizing skill discovery, enabling agents to parse skills directly from a tool's published repository, akin to a `--help` or `manpage` for skills, reducing overhead and central points of failure associated with traditional skill registries. It targets Node.js (>=18) environments and ships with TypeScript types.

Common errors

```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use CommonJS `require()` syntax in a Node.js project configured as an ES module or when using an ES module-only library like `skillflag`.

fix Update your project to use ES module `import` syntax (`import { ... } from 'skillflag';`) and ensure your `package.json` specifies `"type": "module"` or that files using `import` have `.mjs` extension.
```
Error: Failed to find skills root. Make sure skills/ exists relative to the current module.
```
cause The `findSkillsRoot` helper could not locate the `skills/` directory relative to the calling module's path, or the directory structure is incorrect.

fix Ensure a `skills/` directory exists at the root of your project (or a predictable location) and that `SKILL.md` files are correctly placed within `skills/<skill-id>/SKILL.md`. Adjust the `skillsRoot` path in `maybeHandleSkillflag` if necessary.
```
Error: Skill '<id>' not found
```
cause The specified `<id>` does not correspond to any skill defined in your `skills/` directory, or the `SKILL.md` file for that ID is missing or malformed.

fix Verify the skill ID matches a subfolder name in `skills/` and confirm that `skills/<id>/SKILL.md` exists and has valid YAML frontmatter.
```
Your CLI tool exits without handling `--skill` commands, or prints its own `--help` message instead.
```
cause The `maybeHandleSkillflag` function is either not called early enough in your CLI entry point, or the `process.argv` arguments are not passed correctly, preventing `skillflag` from intercepting the `--skill` flag.

fix Place the `await maybeHandleSkillflag(process.argv, { skillsRoot: findSkillsRoot(import.meta.url), });` call at the very beginning of your CLI's main execution path, before any other argument parsing logic.

Warnings

breaking Skillflag requires Node.js version 18 or higher. Running on older Node.js versions will lead to runtime errors.
Fix: Upgrade your Node.js environment to version 18 or newer.
gotcha As a pre-1.0 package (v0.1.x), the API and internal specification for skillflag are subject to change, potentially introducing breaking changes in minor or patch releases.
Fix: Pin skillflag to exact versions or review changelogs carefully when upgrading in pre-1.0 releases.
gotcha Skillflag is an ES module (ESM) only. Projects using CommonJS (`require()`) will need to be configured as ES modules or use dynamic `import()` if mixing module types.
Fix: Ensure your project's `package.json` includes `"type": "module"` and use `import` statements for `skillflag`.
gotcha For `skillflag` to discover skills, they must be organized in a specific directory structure: `skills/<skill-id>/SKILL.md`. Deviations will prevent `findSkillsRoot` from locating them.
Fix: Verify that your skill definitions follow the `skills/<skill-id>/SKILL.md` pattern relative to your CLI's root.
gotcha Integrating `skillflag` requires manually intercepting `--skill` arguments in your CLI's entry point. Failure to do so, or placing it after other argument parsers, will prevent skillflag from activating.
Fix: Place `await maybeHandleSkillflag(process.argv, { skillsRoot: findSkillsRoot(import.meta.url) });` at the very beginning of your CLI's main function.

Install

npm install skillflag npm
yarn add skillflag yarn
pnpm add skillflag pnpm

Imports

findSkillsRoot
wrong:
```
const { findSkillsRoot } = require('skillflag')
```
correct:
```
import { findSkillsRoot } from 'skillflag'
```
Skillflag is an ESM-only module. CommonJS `require` syntax will not work.
maybeHandleSkillflag
wrong:
```
const { maybeHandleSkillflag } = require('skillflag')
```
correct:
```
import { maybeHandleSkillflag } from 'skillflag'
```
This is the primary entry point for integrating skillflag into your CLI, typically awaited at the start of execution.
SkillflagCli
```
import { SkillflagCli } from 'skillflag'
```
While `maybeHandleSkillflag` is for integration, `SkillflagCli` is the class behind the `npx skillflag install` command, useful if you need programmatic access to the installation logic.

Quickstart

Demonstrates how to integrate skillflag into a Node.js/TypeScript CLI by intercepting `--skill` arguments and delegating to the library, ensuring proper skill discovery.

import { findSkillsRoot, maybeHandleSkillflag } from 'skillflag';
import process from 'node:process';

async function main() {
  // Intercept --skill arguments and delegate to skillflag logic
  const handled = await maybeHandleSkillflag(process.argv, {
    skillsRoot: findSkillsRoot(import.meta.url), // Automatically locate the 'skills' directory
  });

  if (handled) {
    return; // Skillflag handled the command, exit without further CLI processing
  }

  // ... Your existing CLI logic for other commands ...
  console.log('Your CLI running other commands...');
  // Example: hue-cli --help for other commands
}

main().catch(console.error);

view raw JSON →