INTEGRATION.md

Integrating Skillflag into your CLI

This guide shows how to expose --skill in your own CLI using the Skillflag library. The goal is to keep your tool agent-agnostic: you only list/export skills, while users install them with skillflag install (or any compatible installer).

1) Add a skills directory

Create a directory in your repo that will ship with your package, for example:

skills/
  my-skill/
    SKILL.md
    scripts/

Portable repo-local agent skills are also supported:

.agents/
  skills/
    my-skill/
      SKILL.md
      scripts/

Your SKILL.md must include frontmatter with name and description per the spec. Example:

---
name: my-skill
description: Helps with deployment checks and release tagging.
---

# My Skill

Usage, scripts, references...

2) Make sure skills are bundled

Ensure the skills/ or .agents/skills/ directory is included in your published package. For npm:

{
  "files": ["dist", "skills", ".agents/skills", "README.md", "LICENSE"]
}

If you publish via a different mechanism, just make sure the skill directory ships alongside your built CLI output.

3) Wire --skill early in your CLI

Intercept --skill before your regular CLI parsing so Skillflag can take over. Example (ESM):

import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";

await maybeHandleSkillflag(process.argv, {
  skillsRoot: findSkillsRoot(import.meta.url),
  // includeBundledSkill: false, // set to false to exclude skillflag's bundled skill
});

Example (CommonJS):

const { findSkillsRoot, maybeHandleSkillflag } = require("skillflag");

await maybeHandleSkillflag(process.argv, {
  skillsRoot: findSkillsRoot(__dirname),
});

findSkillsRoot() walks upward from the given file/dir until it finds a skills/ or .agents/skills/ directory, so you don't need to hardcode build offsets. It prefers skills/ when both exist. Use findSkillsRoots() if you intentionally ship both roots. If you prefer to be explicit, you can still pass a URL, path, or array of roots directly.

4) Try it locally

<tool> --skill list
<tool> --skill show my-skill
<tool> --skill export my-skill | npx skillflag install --agent codex

That is all you need for a conforming producer CLI.

Tips

• If you want to avoid process.exit, call maybeHandleSkillflag(..., { exit: false }) and handle the return value.
• If you want to test without process exit, pass custom stdout/stderr streams to handleSkillflag.
• Skillflag only expects to list and export skills. Avoid embedding installer logic in your CLI.