Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us