### Interactive skill installation

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

When run without specifying an agent or scope in a TTY environment, `skillflag install` launches an interactive wizard to guide the user through selecting an agent and scope for installation.

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

--------------------------------

### Combine Export and Install

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

This optional convenience command combines exporting a skill and installing it. It delegates the actual installation to a separate skill-install command.

```bash
tool --skill install [<id>]
```

--------------------------------

### Install Skill with npx

Source: https://github.com/osolmaz/skillflag/blob/main/skills/skillflag/SKILL.md

Uses `npx` to run the `skillflag install` command for installing a skill without a global installation.

```bash
npx skillflag install --agent codex --scope repo ./skills/skillflag
```

--------------------------------

### Install Skillflag Package

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

Install the skillflag library using npm. This is the first step in integrating skillflag into your CLI.

```bash
npm install skillflag
```

--------------------------------

### Install Skill from Local Directory

Source: https://github.com/osolmaz/skillflag/blob/main/skills/skillflag/SKILL.md

Installs the skill located in the './skills/skillflag' directory into the 'codex' agent's 'repo' scope using `skill-install`.

```bash
skill-install ./skills/skillflag --agent codex --scope repo
```

--------------------------------

### Install a skill from a local directory

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Install a skill from a local directory into a specified agent's user scope. Ensure the path to the local directory is correct.

```bash
skill-install ./skills/gh-actions-debug --agent codex --scope user
```

--------------------------------

### Equivalent Export and Install Command

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

This demonstrates the equivalent command when the `--skill install` convenience is invoked with all required arguments. It pipes the exported skill tar stream to the skill-install command.

```bash
tool --skill export <id> | skill-install --agent <agent> --scope <scope>
```

--------------------------------

### Interactive Skill Installation Wizard

Source: https://context7.com/osolmaz/skillflag/llms.txt

Launches an interactive wizard to select the agent and scope for skill installation when TTY is available and flags are omitted.

```bash
# Interactive wizard (when TTY available and flags omitted)
$ mycli --skill export my-skill | skill-install
# Launches interactive wizard to select agent and scope
```

--------------------------------

### Install Skill from Local Directory

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Installs a skill from a local directory path into a specified agent and scope. The path must be a directory containing SKILL.md at its root.

```bash
skill-install ./skills/tmux --agent claude --scope repo
```

--------------------------------

### Install Skill from Directory to Claude Code

Source: https://context7.com/osolmaz/skillflag/llms.txt

Installs a skill bundle from a local directory to the Claude Code agent with repository scope.

```bash
# Install from directory to Claude Code (repo scope)
$ skill-install ./skills/my-skill --agent claude --scope repo
Installed my-skill to /project/.claude/skills/my-skill (claude/repo)
```

--------------------------------

### Skill Install CLI Synopsis

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Provides the general command-line syntax for the skill-install CLI, including required and optional flags for specifying agent, scope, and installation behavior.

```bash
skill-install [PATH ...]
  --agent <pi|opencode|codex|claude|portable|vscode|copilot|amp|factory|cursor|goose>
  --scope <repo|user|cwd>
  [--root <path>]
  [--mode <copy|link>]
  [--force]
  [--dry-run]
  [--json]
  [--id <override-skill-id>]
  [--dest <override-destination-root>]
  [--native]        # only for agents where “portable-first” is the default (goose/amp)
  [--legacy]        # only where a legacy target exists (vscode/copilot -> .claude/skills)
```

--------------------------------

### Export and install a skill globally for a user

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

This command exports a specified skill and pipes it to the skillflag install command to install it globally for the user's agent configuration.

```bash
$ hue-cli --skill export philips-hue | npx skillflag install --agent claude --scope user
```

--------------------------------

### Install Skill to Portable Location

Source: https://context7.com/osolmaz/skillflag/llms.txt

Installs a skill bundle to a portable location, compatible with multiple agents like Amp and Goose, with repository scope.

```bash
# Install to portable location (works with Amp, Goose, and other agents)
$ skill-install ./skills/my-skill --agent portable --scope repo
Installed my-skill to /project/.agents/skills/my-skill (portable/repo)
```

--------------------------------

### Install Skill from Tar Stream (Interactive)

Source: https://github.com/osolmaz/skillflag/blob/main/skills/skillflag/SKILL.md

Installs a skill from a tar stream piped to `skill-install`. If a TTY is available, it will prompt for interactive target selection.

```bash
skillflag --skill export skillflag | skill-install
```

--------------------------------

### Skill Directory Structure Example

Source: https://context7.com/osolmaz/skillflag/llms.txt

Illustrates the required and optional file structure for a skill bundle, including metadata, scripts, and templates.

```markdown
<!-- skills/my-skill/SKILL.md -->
---
name: my-skill
description: Helps with deployment checks and release tagging
version: 1.0.0
---

# My Skill

Instructions for the AI agent on how to use this skill...

## Available Scripts

- `scripts/deploy.sh` - Run deployment checks
- `scripts/tag.sh` - Create release tags

## Templates

Use the config template at `templates/config.yaml` for setup.
```

```tree
# Directory structure
skills/
  my-skill/
    SKILL.md           # Required: skill metadata and instructions
    scripts/
      deploy.sh        # Optional: executable scripts
      tag.sh
    templates/
      config.yaml      # Optional: template files
```

--------------------------------

### Install a bundled skill from a producer CLI

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Use this command to export a skill from a producer CLI and install it into a specific agent with a 'repo' scope.

```bash
producer --skill export tmux | skill-install --agent claude --scope repo
```

--------------------------------

### Export and Install Skill via Adaptor

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Exports a skill and pipes it to the skill-install command for installation into a specific agent ('codex') and scope ('user').

```bash
tool --skill export tmux | skill-install --agent codex --scope user
```

--------------------------------

### Example CLI Skillflag Commands

Source: https://github.com/osolmaz/skillflag/blob/main/docs/INTEGRATION.md

Demonstrates how to use the `--skill` flag with your CLI for listing, showing, and exporting skills.

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

```

--------------------------------

### Export Skill CLI Example

Source: https://github.com/osolmaz/skillflag/blob/main/docs/2026-01-11-skillflag-node-implementation-plan.md

A basic command to export a specific skill by its ID using the Skillflag CLI. This is a canonical producer example.

```bash
skillflag --skill export <id>
```

--------------------------------

### Export and install a skill for a specific agent

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

This command exports a specified skill and pipes it to the skillflag install command to install it for a particular agent (e.g., Claude Code) within the current repository.

```bash
$ hue-cli --skill export philips-hue | npx skillflag install --agent claude
```

--------------------------------

### Global Install skillflag CLI

Source: https://github.com/osolmaz/skillflag/blob/main/skills/skillflag/SKILL.md

Installs the skillflag package globally, making `skillflag` and `skill-install` commands available on the system's PATH.

```bash
npm install -g skillflag
```

--------------------------------

### Skillflag CLI - Export and Install Pipeline

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Demonstrates the pipeline for exporting a skill and piping it to the skill-install CLI.

```APIDOC
## Export and Install Pipeline

This pipeline exports a skill using the Skillflag CLI and pipes the output to the `skill-install` command for installation into a specified agent and scope.

### Example: Export and Install

```bash
tool --skill export <skill-id> | skill-install --agent <agent> --scope <scope>
```

### Example: Export and Inspect

Exports a skill and inspects its contents without installing.

```bash
tool --skill export <skill-id> | tar -tf -
```

### Example: Export and Manual Placement

Exports a skill and manually places it into a local agent's skill directory.

```bash
mkdir -p .agents/skills/<skill-id>
tool --skill export <skill-id> | tar -x -C .agents/skills/<skill-id>
```
```

--------------------------------

### Install Skill to User Scope for Claude

Source: https://context7.com/osolmaz/skillflag/llms.txt

Installs a skill to the user scope for the Claude agent, typically to a global configuration directory.

```bash
# User scope (global installation)
$ skill-install ./skills/my-skill --agent claude --scope user
# Installs to: ~/.claude/skills/my-skill
```

--------------------------------

### Install Skill from Tar Stream to OpenAI Codex

Source: https://context7.com/osolmaz/skillflag/llms.txt

Installs a skill bundle piped as a tar stream to the OpenAI Codex agent with user scope.

```bash
# Install from tar stream to OpenAI Codex (user scope)
$ mycli --skill export my-skill | skill-install --agent codex --scope user
Installed my-skill to ~/.codex/skills/my-skill (codex/user)
```

--------------------------------

### Install Skill from Tar Stream

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Installs a skill by reading a tar stream from standard input. This is commonly used when piping the output of a producer's export command.

```bash
producer --skill export tmux | skill-install --agent claude --scope user
```

--------------------------------

### Install Skill to User Scope for Portable Agent

Source: https://context7.com/osolmaz/skillflag/llms.txt

Installs a skill to the user scope for a portable agent, typically to a user's configuration directory.

```bash
$ skill-install ./skills/my-skill --agent portable --scope user
# Installs to: ~/.config/agents/skills/my-skill
```

--------------------------------

### Export a skill and install into a repository's agent skills

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

This command exports a skill from a tool and pipes it to `skillflag install` to add it to the specified agent's repository-level skills directory.

```bash
<tool> --skill export <id> | npx skillflag install --agent claude --scope repo
```

--------------------------------

### Export a skill and install into a user's agent skills

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

This command exports a skill from a tool and pipes it to `skillflag install` to add it to the specified agent's user-level skills directory.

```bash
<tool> --skill export <id> | npx skillflag install --agent codex
```

--------------------------------

### Force Overwrite Existing Skill Installation

Source: https://context7.com/osolmaz/skillflag/llms.txt

Forces the overwrite of an existing skill installation for the Claude Code agent with user scope.

```bash
# Force overwrite existing installation
$ skill-install ./skills/my-skill --agent claude --scope user --force
```

--------------------------------

### Install to a custom skills root directory

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Use the `--dest` flag to install a skill to a custom skills root directory when the agent or tool is not explicitly listed. This provides flexibility for future agent integrations.

```bash
skill-install --dest <skills-root>
```

--------------------------------

### Export and Install Skill to Claude Repo Scope

Source: https://github.com/osolmaz/skillflag/blob/main/skills/skillflag/SKILL.md

Exports the 'skillflag' skill as a tar stream and pipes it to `skill-install` to install into the 'claude' agent's 'repo' scope.

```bash
skillflag --skill export skillflag | skill-install --agent claude --scope repo
```

--------------------------------

### Example SKILL.md Frontmatter

Source: https://github.com/osolmaz/skillflag/blob/main/docs/INTEGRATION.md

Defines the name and description for a skill. Ensure this frontmatter adheres to the Skillflag specification.

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

# My Skill

Usage, scripts, references...

```

--------------------------------

### Export and Install Skill to Codex Repo Scope

Source: https://github.com/osolmaz/skillflag/blob/main/skills/skillflag/SKILL.md

Exports the 'skillflag' skill as a tar stream and pipes it to `skill-install` to install into the 'codex' agent's 'repo' scope.

```bash
skillflag --skill export skillflag | skill-install --agent codex --scope repo
```

--------------------------------

### Agent Destination Mappings for Repo Scope

Source: https://context7.com/osolmaz/skillflag/llms.txt

Lists the filesystem mappings for various AI agents when installing skills with the repository scope.

```bash
# Agent destination mappings (repo scope)
# codex   -> .codex/skills/<skill_id>/
# claude  -> .claude/skills/<skill_id>/
# portable -> .agents/skills/<skill_id>/
# vscode  -> .github/skills/<skill_id>/
# copilot -> .github/skills/<skill_id>/
# amp     -> .agents/skills/<skill_id>/
# goose   -> .agents/skills/<skill_id>/
# opencode -> .opencode/skill/<skill_id>/
# factory -> .factory/skills/<skill_id>/
# cursor  -> .cursor/skills/<skill_id>/
```

--------------------------------

### Install Skill to User Scope for Codex

Source: https://context7.com/osolmaz/skillflag/llms.txt

Installs a skill to the user scope for the Codex agent, using either the default path or a custom CODEX_HOME environment variable.

```bash
$ skill-install ./skills/my-skill --agent codex --scope user
# Installs to: ~/.codex/skills/my-skill (or $CODEX_HOME/skills)
```

--------------------------------

### Install a skill into 'portable' for multi-agent access

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Install a skill into the 'portable' agent scope so that multiple agents can access it. This is useful for skills that are commonly used across different agent environments.

```bash
producer --skill export api-setup | skill-install --agent portable --scope repo
```

--------------------------------

### Run skillflag CLI with npx

Source: https://github.com/osolmaz/skillflag/blob/main/skills/skillflag/SKILL.md

Executes the `skillflag --skill list` command using `npx` without a global installation, utilizing bundled binaries.

```bash
npx skillflag --skill list
```

--------------------------------

### Recommended Text Output Format

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Skills should be listed one per line, starting with the Skill ID followed by a tab and an optional summary. The summary must not contain newlines or tabs.

```text
<id>\t<summary>
```

--------------------------------

### Integrate skillflag into Node CLI

Source: https://github.com/osolmaz/skillflag/blob/main/skills/skillflag/SKILL.md

Example TypeScript code demonstrating how to integrate `skillflag` into a Node.js CLI application by handling skillflag commands early in the entrypoint.

```typescript
import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";

await maybeHandleSkillflag(process.argv, {
  skillsRoot: findSkillsRoot(import.meta.url),
  // includeBundledSkill: false, // opt out of the built-in skillflag skill
});

// ... normal CLI startup here
```

--------------------------------

### CLI: Export Skill Bundle

Source: https://context7.com/osolmaz/skillflag/llms.txt

Exports a skill as a deterministic tar stream to stdout, suitable for piping to installers or saving to a file.

```APIDOC
## CLI: Export Skill Bundle

### Description
Exports a skill as a deterministic tar stream to stdout. The tar contains a single top-level directory named after the skill ID with all skill files inside.

### Method
GET

### Endpoint
`/` (Root of the CLI, invoked with `--skill export <skill_id>`)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **skill** (string) - Required - Must be `export` to trigger this command.
- **skill_id** (string) - Required - The ID of the skill to export.

#### Request Body
None

### Request Example
```bash
# Export and inspect contents without installing
$ mycli --skill export my-skill | tar -tf -
my-skill/
my-skill/SKILL.md
my-skill/scripts/deploy.sh
my-skill/templates/config.yaml

# Export and save to file
$ mycli --skill export my-skill > my-skill.tar

# Export and pipe to installer
$ mycli --skill export my-skill | skill-install --agent claude --scope repo
```

### Response
#### Success Response (200)
- **stream** - A tar archive stream containing the skill files.

#### Response Example
```bash
my-skill/
my-skill/SKILL.md
my-skill/scripts/deploy.sh
```
```

--------------------------------

### Export and Manually Place Skill Files

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Exports a skill and extracts its contents into a specified directory. This method bypasses the need for an adaptor and assumes a simple untar installation logic.

```bash
mkdir -p .agents/skills/tmux
tool --skill export tmux | tar -x -C .agents/skills
```

--------------------------------

### Project Structure for Skillflag CLI

Source: https://github.com/osolmaz/skillflag/blob/main/docs/2026-01-11-skillflag-node-implementation-plan.md

Defines the directory layout for the Skillflag project, including CLI entry points, core logic modules, installer modules, tests, and bundled skills.

```tree
skillflag/
  src/
    bin/
      skillflag.ts        # CLI entry
      skill-install.ts    # Installer CLI entry
    core/
      list.ts             # discovery logic
      export.ts           # tar export
      show.ts             # optional
      paths.ts            # skills root + id validation
      tar.ts              # deterministic tar creation
      digest.ts           # sha256 streaming
      errors.ts
    install/
      cli.ts              # installer arg parsing
      extract.ts          # tar validation + extraction
      resolve.ts          # agent/scope destination mapping
      validate.ts         # SKILL.md + frontmatter validation
      copy.ts             # install mode (copy)
      link.ts             # optional mode (link)
      json.ts             # JSON output payload
      errors.ts
  test/
    fixtures/skills/...
    integration/...
  skills/                 # bundled skill covering both skillflag + skill-install

```

--------------------------------

### Export and Inspect Skill Archive

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Exports a skill as a tar stream to stdout and then lists the contents of the tar archive without installing it. Useful for inspecting the skill's contents.

```bash
tool --skill export tmux | tar -tf -
```

--------------------------------

### Export Skill Directory via Tar Stream

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

This command exports the full skill directory as a tar stream on stdout. It is used by installers to retrieve skill content.

```bash
tool --skill export <id>
```

--------------------------------

### Add skillflag to a Node.js/TypeScript project

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

Follow these steps to integrate skillflag into your CLI project. This involves installing the library, setting up a skills directory, and intercepting the --skill flag in your CLI's entrypoint.

```text
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
```

--------------------------------

### Display Skill-Install Help

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

View the help information for the skill-install command to understand available options and usage.

```bash
skill-install --help
```

--------------------------------

### skill-install CLI - Inputs

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Describes the different ways to provide input to the skill-install CLI.

```APIDOC
## skill-install Inputs

### 1. Directory Input

Install from a local skill directory.

- `PATH` must be a directory containing `SKILL.md` at its root.
- Implementations may accept multiple `PATH` values.

```bash
skill-install ./skills/tmux --agent claude --scope repo
```

### 2. Stream Input (tar on stdin)

Install from a tar stream, typically produced by `skill-install --skill export`.

- If `PATH` is omitted and stdin is not a TTY, `skill-install` must read a tar stream from stdin.
- The tar stream should contain a single top-level directory `<something>/...` with `SKILL.md` inside that root.

```bash
producer --skill export tmux | skill-install --agent claude --scope user
```
```

--------------------------------

### skill-install CLI - Synopsis and Flags

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Details the command-line interface and available flags for the skill-install CLI.

```APIDOC
## skill-install CLI Synopsis

```bash
skill-install [PATH ...]
  --agent <pi|opencode|codex|claude|portable|vscode|copilot|amp|factory|cursor|goose>
  --scope <repo|user|cwd>
  [--root <path>]
  [--mode <copy|link>]
  [--force]
  [--dry-run]
  [--json]
  [--id <override-skill-id>]
  [--dest <override-destination-root>]
  [--native]
  [--legacy]
```

### Required Flags

- `--agent` is required unless `--dest` is provided.
- `--scope` is required unless `--dest` is provided.

Rationale: Avoid silent installs into the wrong agent/tool.
```

--------------------------------

### List Skills (Text Format)

Source: https://context7.com/osolmaz/skillflag/llms.txt

Lists all available skills bundled with the CLI in a simple text format. Each line displays the skill ID followed by a tab-separated summary.

```bash
# List skills in text format
$ mycli --skill list
my-skill	Helps with deployment checks and release tagging
another-skill	Manages configuration files
```

--------------------------------

### Show Skill Documentation

Source: https://context7.com/osolmaz/skillflag/llms.txt

Displays the full `SKILL.md` content for a specified skill, offering a manpage-like experience. This command is useful for understanding how to use a particular skill.

```bash
# Show skill documentation
$ mycli --skill show my-skill
---
name: my-skill
description: Helps with deployment checks and release tagging
---

# My Skill

Usage instructions and documentation...
```

--------------------------------

### View Skill Documentation

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Displays the documentation for a specific skill, if supported by the tool. Replace 'tmux' with the desired skill ID.

```bash
tool --skill show tmux
```

--------------------------------

### CLI: Show Skill Documentation

Source: https://context7.com/osolmaz/skillflag/llms.txt

Displays the full SKILL.md content for a specific skill, offering a manpage-like experience.

```APIDOC
## CLI: Show Skill Documentation

### Description
Displays the full SKILL.md content for a specific skill, providing a manpage-like experience.

### Method
GET

### Endpoint
`/` (Root of the CLI, invoked with `--skill show <skill_id>`)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **skill** (string) - Required - Must be `show` to trigger this command.
- **skill_id** (string) - Required - The ID of the skill to display documentation for.

#### Request Body
None

### Request Example
```bash
# Show skill documentation
$ mycli --skill show my-skill
---
name: my-skill
description: Helps with deployment checks and release tagging
---

# My Skill

Usage instructions and documentation...
```

### Response
#### Success Response (200)
- **string** - The content of the `SKILL.md` file for the specified skill.

#### Response Example
```markdown
---
name: my-skill
description: Helps with deployment checks and release tagging
---

# My Skill

Usage instructions and documentation...
```
```

--------------------------------

### List available skills

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

Use this command to see the skills a tool can export. It displays the skill ID and a brief description.

```bash
$ hue-cli --skill list
```

--------------------------------

### Package.json Configuration for Skill Bundling

Source: https://context7.com/osolmaz/skillflag/llms.txt

Configures a package.json file to include the skills directory when the package is published, ensuring skills are bundled.

```json
{
  "name": "mycli",
  "version": "1.0.0",
  "bin": {
    "mycli": "dist/bin/cli.js"
  },
  "files": [
    "dist",
    "skills",
    "README.md",
    "LICENSE"
  ],
  "dependencies": {
    "skillflag": "^0.1.0"
  }
}
```

--------------------------------

### List Bundled Skills with skillflag

Source: https://github.com/osolmaz/skillflag/blob/main/skills/skillflag/SKILL.md

Use the `skillflag --skill list` command to see all available skill IDs bundled with the producer.

```bash
skillflag --skill list
```

--------------------------------

### Skillflag Library Entrypoint Options

Source: https://github.com/osolmaz/skillflag/blob/main/docs/2026-01-11-skillflag-node-implementation-plan.md

Defines the options for the `handleSkillflag` function, including the skills root directory and optional streams for stdout/stderr. Use this for integrating Skillflag programmatically.

```typescript
export type SkillflagOptions = {
  skillsRoot: URL | string;
  stdout?: NodeJS.WritableStream;
  stderr?: NodeJS.WritableStream;
  now?: Date; // optional for tests
};

export async function handleSkillflag(
  argv: string[],
  opts: SkillflagOptions,
): Promise<number>;
```

--------------------------------

### Skillflag CLI - Core Commands

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Basic commands for interacting with skills using the Skillflag CLI.

```APIDOC
## Skillflag CLI Commands

### List Skills

Lists all available skills.

```bash
tool --skill list
```

### View Skill Documentation

Shows documentation for a specific skill, if supported.

```bash
tool --skill show <skill-id>
```

### Export Skill

Exports a skill as a tar stream to stdout.

```bash
tool --skill export <skill-id>
```
```

--------------------------------

### CLI: List Skills

Source: https://context7.com/osolmaz/skillflag/llms.txt

Lists all available skills bundled with the CLI. Supports plain text and JSON output formats.

```APIDOC
## CLI: List Skills

### Description
Lists all available skills bundled with the CLI. Each line contains the skill ID followed by an optional tab-separated summary. Supports JSON output with digests for integrity verification.

### Method
GET

### Endpoint
`/` (Root of the CLI, invoked with `--skill list`)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **skill** (string) - Required - Must be `list` to trigger this command.
- **json** (boolean) - Optional - If present, outputs skills in JSON format.

#### Request Body
None

### Request Example
```bash
# List skills in text format
$ mycli --skill list
my-skill\tHelps with deployment checks and release tagging
another-skill\tManages configuration files

# List skills in JSON format with digest for integrity verification
$ mycli --skill list --json
{
  "skillflag_version": "0.1",
  "skills": [
    {
      "id": "my-skill",
      "digest": "sha256:a1b2c3d4...",
      "files": 3,
      "summary": "Helps with deployment checks and release tagging",
      "version": "1.0.0"
    }
  ]
}
```

### Response
#### Success Response (200)
- **string** (text format) - Each line is `skill_id\tsummary`.
- **object** (JSON format) - Contains `skillflag_version` and an array of `skills` objects, each with `id`, `digest`, `files`, `summary`, and `version`.

#### Response Example
```json
{
  "skillflag_version": "0.1",
  "skills": [
    {
      "id": "my-skill",
      "digest": "sha256:a1b2c3d4...",
      "files": 3,
      "summary": "Helps with deployment checks and release tagging",
      "version": "1.0.0"
    }
  ]
}
```
```

--------------------------------

### List Skills (JSON Format)

Source: https://context7.com/osolmaz/skillflag/llms.txt

Lists all available skills in JSON format, including a digest for integrity verification. This format provides more detailed information about each skill, such as its ID, digest, file count, summary, and version.

```bash
# List skills in JSON format with digest for integrity verification
$ mycli --skill list --json
{
  "skillflag_version": "0.1",
  "skills": [
    {
      "id": "my-skill",
      "digest": "sha256:a1b2c3d4...",
      "files": 3,
      "summary": "Helps with deployment checks and release tagging",
      "version": "1.0.0"
    }
  ]
}
```

--------------------------------

### Package.json Scripts for Skillflag Project

Source: https://github.com/osolmaz/skillflag/blob/main/docs/2026-01-11-skillflag-node-implementation-plan.md

Standard npm scripts for building, linting, formatting, and testing the Skillflag Node.js project, mirroring SimpleDoc conventions.

```json
"build": "tsc -p tsconfig.json",
"lint": "eslint . --max-warnings 0",
"format": "prettier",
"format:check": "prettier:check",
"test": "tsc -p tsconfig.test.json && node --test"

```

--------------------------------

### Include Skills Directory in npm Package

Source: https://github.com/osolmaz/skillflag/blob/main/docs/INTEGRATION.md

Specifies which files and directories to include in an npm package. Ensure your 'skills/' directory is listed here.

```json
{
  "files": ["dist", "skills", "README.md", "LICENSE"]
}

```

--------------------------------

### List Available Skills

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

This command lists the available Skill IDs. The output should only contain the Skill IDs and nothing else on stdout.

```bash
tool --skill list
```

--------------------------------

### Show a single skill's metadata (CLI)

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

This command displays the metadata for a specific skill, identified by its ID, from a CLI tool that supports the skillflag convention.

```bash
<tool> --skill show <id>
```

--------------------------------

### TypeScript Types for Skillflag Options

Source: https://context7.com/osolmaz/skillflag/llms.txt

Demonstrates importing and using TypeScript types for Skillflag configuration options, including basic and dispatch options.

```typescript
import type {
  SkillflagOptions,
  SkillflagDispatchOptions,
} from "skillflag";

// SkillflagOptions
const options: SkillflagOptions = {
  skillsRoot: new URL("file:///path/to/skills/"),
  stdin: process.stdin,
  stdout: process.stdout,
  stderr: process.stderr,
  cwd: process.cwd(),
  includeBundledSkill: true, // include skillflag's own bundled skill
};

// SkillflagDispatchOptions extends SkillflagOptions
const dispatchOptions: SkillflagDispatchOptions = {
  ...options,
  exit: process.exit, // or false to prevent process.exit
};
```

--------------------------------

### Integrate Skillflag into CLI Entrypoint

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

In your CLI entrypoint, intercept the '--skill' argument and delegate to skillflag. Ensure you have the necessary imports.

```typescript
import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";

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

--------------------------------

### List skills the tool can export (CLI)

Source: https://github.com/osolmaz/skillflag/blob/main/README.md

This command lists the skills that a CLI tool, implementing the skillflag convention, can export. It's analogous to a `--help` command for skills.

```bash
<tool> --skill list
```

--------------------------------

### Skillflag Conformance Checklist

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Criteria for a producer CLI to be considered Skillflag-compliant.

```APIDOC
## Skillflag Conformance Checklist

A producer CLI is **Skillflag-compliant** if:

- `--skill list` outputs Skill IDs on stdout with no extra stdout noise.
- `--skill list --json` includes `digest` for each skill.
- `--skill export <id>` emits a tar stream on stdout.
- (Optional) `--skill install [<id>]` follows the convenience behavior described in section 6.
- The tar stream contains exactly one top-level directory `<id>/`.
- `<id>/SKILL.md` exists in the exported stream.
- Tar entries are deterministic (stable order, normalized metadata).
- No absolute paths or path traversal segments appear in the tar entries.
- Failures exit `1` and write errors to stderr.
```

--------------------------------

### Producer API: findSkillsRoot

Source: https://context7.com/osolmaz/skillflag/llms.txt

Locates the 'skills/' directory by walking upward from a given path. Returns a URL to the skills root.

```APIDOC
## Producer API: findSkillsRoot

### Description
Walks upward from the given file or directory path to locate the `skills/` directory. Returns a `URL` pointing to the skills root. Throws if no `skills/` directory is found.

### Method
Synchronous function call

### Endpoint
N/A (Internal CLI function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { findSkillsRoot } from "skillflag";

// From ESM module (import.meta.url)
const skillsRoot = findSkillsRoot(import.meta.url);
console.log(skillsRoot.href);
// Output: file:///path/to/project/skills/

// From CommonJS module (__dirname)
const skillsRootCjs = findSkillsRoot(__dirname);

// With explicit path
const skillsRootPath = findSkillsRoot("/path/to/my/cli/src/index.ts");
```

### Response
#### Success Response
- **URL** - A URL object pointing to the `skills/` directory.

#### Response Example
```json
{
  "skillsRootUrl": "file:///path/to/project/skills/"
}
```
```

--------------------------------

### Skill List JSON Schema

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

When the --skill list --json flag is used, a single JSON object is printed to stdout conforming to this schema. Optional fields should be omitted if not provided.

```json
{
  "skillflag_version": "0.1",
  "skills": [
    {
      "id": "tmux",
      "summary": "Drive an interactive tmux session",
      "version": "1.0.0",
      "files": 3,
      "digest": "sha256:a1b2c3..."
    }
  ]
}
```

--------------------------------

### Export Skill Bundle to Tar Stream

Source: https://context7.com/osolmaz/skillflag/llms.txt

Exports a skill as a deterministic tar stream to standard output. The tarball contains a single top-level directory named after the skill ID, including all its associated files.

```bash
# Export and inspect contents without installing
$ mycli --skill export my-skill | tar -tf -
my-skill/
my-skill/SKILL.md
my-skill/scripts/deploy.sh
my-skill/templates/config.yaml
```

```bash
# Export and save to file
$ mycli --skill export my-skill > my-skill.tar
```

```bash
# Export and pipe to installer
$ mycli --skill export my-skill | skill-install --agent claude --scope repo
```

--------------------------------

### Producer API: maybeHandleSkillflag

Source: https://context7.com/osolmaz/skillflag/llms.txt

Integrates Skillflag support into a CLI by intercepting '--skill' flags. Returns true if handled, false otherwise.

```APIDOC
## Producer API: maybeHandleSkillflag

### Description
The primary integration point for adding skillflag support to a CLI. This function intercepts `--skill` flags from argv and delegates to the skillflag handler, returning `true` if handled or `false` to continue normal CLI execution.

### Method
Asynchronous function call

### Endpoint
N/A (Internal CLI function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";

// In your CLI entrypoint (src/bin/cli.ts)
// Call early before any other CLI parsing

await maybeHandleSkillflag(process.argv, {
  skillsRoot: findSkillsRoot(import.meta.url),
  // includeBundledSkill: false, // opt out of the built-in skillflag skill
});

// If --skill flag was not present, continue normal CLI startup
console.log("Running normal CLI commands...");
```

### Response
#### Success Response
- **boolean** - `true` if the skillflag was handled, `false` otherwise.

#### Response Example
```json
{
  "handled": true
}
```
```

--------------------------------

### Wire Skillflag in CLI (CommonJS)

Source: https://github.com/osolmaz/skillflag/blob/main/docs/INTEGRATION.md

Integrates Skillflag into a CommonJS-based CLI by calling `maybeHandleSkillflag` early. It uses `findSkillsRoot` with `__dirname` to locate the skills directory.

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

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

```

--------------------------------

### Producer API: handleSkillflag

Source: https://context7.com/osolmaz/skillflag/llms.txt

A lower-level API that always processes skillflag arguments, returning an exit code. Useful for testing and granular control.

```APIDOC
## Producer API: handleSkillflag

### Description
Lower-level API that always processes skillflag arguments without checking for `--skill` presence. Returns an exit code (0 for success, 1 for errors). Useful for testing or when you need more control over execution flow.

### Method
Asynchronous function call

### Endpoint
N/A (Internal CLI function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { handleSkillflag, findSkillsRoot } from "skillflag";
import { Writable } from "node:stream";

// Create custom streams for capturing output
const outputChunks: string[] = [];
const stdout = new Writable({
  write(chunk, encoding, callback) {
    outputChunks.push(chunk.toString());
    callback();
  },
});

// Handle skillflag with custom options
const exitCode = await handleSkillflag(
  ["node", "mycli", "--skill", "list"],
  {
    skillsRoot: findSkillsRoot(import.meta.url),
    stdout,
    stderr: process.stderr,
    includeBundledSkill: true,
  }
);

console.log("Exit code:", exitCode);
console.log("Output:", outputChunks.join(""));
// Output: myskilL\tMy skill description
```

### Response
#### Success Response (0)
- **number** - Exit code 0 indicates success.

#### Error Response (1)
- **number** - Exit code 1 indicates an error.

#### Response Example
```json
{
  "exitCode": 0
}
```
```

--------------------------------

### Locate Skill Directory

Source: https://context7.com/osolmaz/skillflag/llms.txt

The `findSkillsRoot` function locates the `skills/` directory by walking upwards from a given path. It returns a `URL` to the root or throws an error if not found. Supports both ESM (`import.meta.url`) and CommonJS (`__dirname`).

```typescript
import { findSkillsRoot } from "skillflag";

// From ESM module (import.meta.url)
const skillsRoot = findSkillsRoot(import.meta.url);
console.log(skillsRoot.href);
// Output: file:///path/to/project/skills/

// From CommonJS module (__dirname)
const skillsRootCjs = findSkillsRoot(__dirname);

// With explicit path
const skillsRootPath = findSkillsRoot("/path/to/my/cli/src/index.ts");
```

--------------------------------

### Integrate Skillflag Support in CLI

Source: https://context7.com/osolmaz/skillflag/llms.txt

Use `maybeHandleSkillflag` in your CLI entrypoint to intercept and handle `--skill` flags. Call this function early before other CLI parsing. It returns `true` if the flag was handled, allowing normal CLI execution to continue if `false`.

```typescript
import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";

// In your CLI entrypoint (src/bin/cli.ts)
// Call early before any other CLI parsing

await maybeHandleSkillflag(process.argv, {
  skillsRoot: findSkillsRoot(import.meta.url),
  // includeBundledSkill: false, // opt out of the built-in skillflag skill
});

// If --skill flag was not present, continue normal CLI startup
console.log("Running normal CLI commands...");
```

--------------------------------

### Wire Skillflag in CLI (ESM)

Source: https://github.com/osolmaz/skillflag/blob/main/docs/INTEGRATION.md

Integrates Skillflag into an ESM-based CLI by calling `maybeHandleSkillflag` early. It uses `findSkillsRoot` to locate the skills directory.

```typescript
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
});

```

--------------------------------

### Handle Skillflag with Custom Streams

Source: https://context7.com/osolmaz/skillflag/llms.txt

Use `handleSkillflag` for lower-level control, always processing skillflag arguments and returning an exit code. This is useful for testing or custom execution flows. It allows specifying custom stdout and stderr streams.

```typescript
import { handleSkillflag, findSkillsRoot } from "skillflag";
import { Writable } from "node:stream";

// Create custom streams for capturing output
const outputChunks: string[] = [];
const stdout = new Writable({
  write(chunk, encoding, callback) {
    outputChunks.push(chunk.toString());
    callback();
  },
});

// Handle skillflag with custom options
const exitCode = await handleSkillflag(
  ["node", "mycli", "--skill", "list"],
  {
    skillsRoot: findSkillsRoot(import.meta.url),
    stdout,
    stderr: process.stderr,
    includeBundledSkill: true,
  }
);

console.log("Exit code:", exitCode);
console.log("Output:", outputChunks.join(""));
// Output: myskilL	My skill description
```

--------------------------------

### Skill JSON Schema Field Requirements

Source: https://github.com/osolmaz/skillflag/blob/main/docs/SKILLFLAG_SPEC.md

Details the requirements for fields within the skill JSON object. The 'id' and 'digest' fields are required, while 'summary', 'version', and 'files' are optional.

```json
{
  "id": "string, **required**": Skill identifier. MUST NOT be empty.
  "summary": "string, optional": If omitted, treat as empty string. If present, MUST be a string (not null).
  "version": "string, optional": Semver-style version. If omitted, assume unversioned. If present, MUST be a non-empty string.
  "files": "integer, optional": Number of files in the skill bundle.
  "digest": "string, **required**": SHA-256 hash of the exported tar stream, prefixed with `sha256:`. MUST be present for integrity verification.
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.