{"id":17366,"library":"skillflag","title":"Skillflag CLI Convention & Library","description":"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.","status":"active","version":"0.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/osolmaz/skillflag","tags":["javascript","typescript"],"install":[{"cmd":"npm install skillflag","lang":"bash","label":"npm"},{"cmd":"yarn add skillflag","lang":"bash","label":"yarn"},{"cmd":"pnpm add skillflag","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Skillflag is an ESM-only module. CommonJS `require` syntax will not work.","wrong":"const { findSkillsRoot } = require('skillflag')","symbol":"findSkillsRoot","correct":"import { findSkillsRoot } from 'skillflag'"},{"note":"This is the primary entry point for integrating skillflag into your CLI, typically awaited at the start of execution.","wrong":"const { maybeHandleSkillflag } = require('skillflag')","symbol":"maybeHandleSkillflag","correct":"import { maybeHandleSkillflag } from 'skillflag'"},{"note":"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.","symbol":"SkillflagCli","correct":"import { SkillflagCli } from 'skillflag'"}],"quickstart":{"code":"import { findSkillsRoot, maybeHandleSkillflag } from 'skillflag';\nimport process from 'node:process';\n\nasync function main() {\n  // Intercept --skill arguments and delegate to skillflag logic\n  const handled = await maybeHandleSkillflag(process.argv, {\n    skillsRoot: findSkillsRoot(import.meta.url), // Automatically locate the 'skills' directory\n  });\n\n  if (handled) {\n    return; // Skillflag handled the command, exit without further CLI processing\n  }\n\n  // ... Your existing CLI logic for other commands ...\n  console.log('Your CLI running other commands...');\n  // Example: hue-cli --help for other commands\n}\n\nmain().catch(console.error);\n","lang":"typescript","description":"Demonstrates how to integrate skillflag into a Node.js/TypeScript CLI by intercepting `--skill` arguments and delegating to the library, ensuring proper skill discovery."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18 or newer.","message":"Skillflag requires Node.js version 18 or higher. Running on older Node.js versions will lead to runtime errors.","severity":"breaking","affected_versions":"<18.0"},{"fix":"Pin skillflag to exact versions or review changelogs carefully when upgrading in pre-1.0 releases.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your project's `package.json` includes `\"type\": \"module\"` and use `import` statements for `skillflag`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Verify that your skill definitions follow the `skills/<skill-id>/SKILL.md` pattern relative to your CLI's root.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Place `await maybeHandleSkillflag(process.argv, { skillsRoot: findSkillsRoot(import.meta.url) });` at the very beginning of your CLI's main function.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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`.","error":"ReferenceError: require is not defined in ES module scope"},{"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.","cause":"The `findSkillsRoot` helper could not locate the `skills/` directory relative to the calling module's path, or the directory structure is incorrect.","error":"Error: Failed to find skills root. Make sure skills/ exists relative to the current module."},{"fix":"Verify the skill ID matches a subfolder name in `skills/` and confirm that `skills/<id>/SKILL.md` exists and has valid YAML frontmatter.","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.","error":"Error: Skill '<id>' not found"},{"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.","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.","error":"Your CLI tool exits without handling `--skill` commands, or prints its own `--help` message instead."}],"ecosystem":"npm","meta_description":null}