Skill

Generate Markdown skill files from CLI commands for AI agent discovery

The Skill module generates Markdown skill files from CLI commands, enabling AI agents to discover and use your CLI tools.

Functions

generate

Generates a Markdown skill file from a CLI name and collected command data.

function generate(
  name: string,
  commands: CommandInfo[],
  groups?: Map<string, string>
): string

name · string · required

The CLI name

commands · CommandInfo[] · required

Array of command information objects

groups · Map<string, string>

Optional map of group names to descriptions. Defaults to an empty Map.

return · string

Generated Markdown content for the skill file

Example

import { Skill } from 'incur'

const commands: Skill.CommandInfo[] = [
  {
    name: 'deploy',
    description: 'Deploy your application',
    args: z.object({ target: z.string() }),
    options: z.object({ verbose: z.boolean().optional() })
  }
]

const markdown = Skill.generate('mycli', commands)
console.log(markdown)

split

Splits commands into skill files grouped by depth.

function split(
  name: string,
  commands: CommandInfo[],
  depth: number,
  groups?: Map<string, string>
): File[]

name · string · required

The CLI name

commands · CommandInfo[] · required

Array of command information objects

depth · number · required

Grouping depth for skill files. 0 creates a single file, 1 groups by first segment, 2 by first two segments, etc.

groups · Map<string, string>

Optional map of group names to descriptions. Defaults to an empty Map.

return · File[]

Array of skill file entries with directory names and content

Example

import { Skill } from 'incur'

const commands: Skill.CommandInfo[] = [
  { name: 'db migrate', description: 'Run migrations' },
  { name: 'db seed', description: 'Seed database' },
  { name: 'server start', description: 'Start server' }
]

// Split by first segment (depth 1)
const files = Skill.split('mycli', commands, 1)
// Returns:
// [
//   { dir: 'db', content: '...' },
//   { dir: 'server', content: '...' }
// ]

hash

Computes a deterministic hash of command structure for staleness detection.

function hash(commands: CommandInfo[]): string

commands · CommandInfo[] · required

Array of command information objects

return · string

16-character hex hash of the command structure

Example

import { Skill } from 'incur'

const commands: Skill.CommandInfo[] = [/* ... */]
const currentHash = Skill.hash(commands)

// Compare with stored hash to detect changes
if (currentHash !== storedHash) {
  console.log('Commands have changed, regenerating skills')
}

Types

CommandInfo

Information about a single command passed to generate() and split().

type CommandInfo = {
  name: string
  description?: string | undefined
  args?: z.ZodObject<any> | undefined
  env?: z.ZodObject<any> | undefined
  hint?: string | undefined
  options?: z.ZodObject<any> | undefined
  output?: z.ZodType | undefined
  examples?: { command: string; description?: string }[] | undefined
}

name · string · required

Command name (e.g., "deploy" or "db migrate")

description · string

Human-readable command description

args · z.ZodObject<any>

Zod schema for positional arguments

env · z.ZodObject<any>

Zod schema for environment variables

hint · string

Additional hint text displayed after examples

options · z.ZodObject<any>

Zod schema for command options/flags

output · z.ZodType

Zod schema for command output

examples · Array<{ command: string; description?: string }>

Array of usage examples with optional descriptions

File

A skill file entry with its directory name and content.

type File = {
  /** Directory name relative to output root (empty string for depth 0) */
  dir: string
  /** Markdown content */
  content: string
}

dir · string · required

Directory name relative to output root. Empty string for depth 0.

content · string · required

Markdown content for the skill file

Related

• SyncSkills - Sync skills to agent config directories
• Agent Discovery - Learn about AI agent discovery