skillflag

library0.1.4jsnpmunverified

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.

llm-agents devops

npm install skillflag

github ↗package ↗

INSTALL

IMPORT

SIG · SKILLFLAG

skillflag

llm-agentsjavascriptv0.1.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

findSkillsRoot

✓ import { findSkillsRoot } from 'skillflag'

✗ const { findSkillsRoot } = require('skillflag')

Skillflag is an ESM-only module. CommonJS `require` syntax will not work.

maybeHandleSkillflag

✓ import { maybeHandleSkillflag } from 'skillflag'

✗ const { maybeHandleSkillflag } = require('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.

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);

skillflag --version

Debug

Known issues

breakingSkillflag 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.

affects: <18.0

gotchaAs 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.

affects: >=0.1.0

gotchaSkillflag 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`.

affects: >=0.1.0

gotchaFor `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.

affects: >=0.1.0

gotchaIntegrating `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.

affects: >=0.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

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.

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

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.

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.

Upgrade

Version history

0.1.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/osolmaz/skillflag ↗

packagehttps://www.npmjs.com/package/skillflag ↗