llms-full.txt git:20260413.ff1f5e0A

Immutable. This exact content is served forever at /api/v1/blob/7f4458a4271a0b6e.

# to-skills

> Generate structured AI agent skills (SKILL.md) and llms.txt from your TypeScript API documentation

## @to-skills/core

Shared types, renderers, and utilities for the to-skills ecosystem.

Core provides the intermediate representation (ExtractedSkill), the SKILL.md renderer
with progressive disclosure (lean discovery file + on-demand reference files), the
audit engine (20 checks across fatal/error/warning/alert), and utilities for
token budgeting, README parsing, and docs scanning.

### renderSkills

Render multiple extracted skills into progressive disclosure file sets.

```ts
renderSkills(skills: ExtractedSkill[], options?: Partial<SkillRenderOptions>): RenderedSkill[]
```

**Parameters:**
- `skills: ExtractedSkill[]` — 
- `options: Partial<SkillRenderOptions>` (optional) — 

**Returns:** `RenderedSkill[]`

### renderSkill

Render a single skill into SKILL.md + references/.

```ts
renderSkill(skill: ExtractedSkill, options?: Partial<SkillRenderOptions>): RenderedSkill
```

**Parameters:**
- `skill: ExtractedSkill` — 
- `options: Partial<SkillRenderOptions>` (optional) — 

**Returns:** `RenderedSkill`

### writeSkills

Write rendered skill file sets to disk (SKILL.md + references/).

```ts
writeSkills(skills: RenderedSkill[], options: Pick<SkillRenderOptions, "outDir">): void
```

**Parameters:**
- `skills: RenderedSkill[]` — 
- `options: Pick<SkillRenderOptions, "outDir">` — 

### estimateTokens

Rough token estimate: ~4 chars per token for English/code.
Not exact, but good enough for budgeting skill file sizes.

```ts
estimateTokens(text: string): number
```

**Parameters:**
- `text: string` — 

**Returns:** `number`

### truncateToTokenBudget

Truncate text to fit within a token budget, preserving complete lines.

```ts
truncateToTokenBudget(text: string, maxTokens: number): string
```

**Parameters:**
- `text: string` — 
- `maxTokens: number` — 

**Returns:** `string`

### renderLlmsTxt

Render llms.txt and llms-full.txt from extracted skills

```ts
renderLlmsTxt(skills: ExtractedSkill[], options: LlmsTxtOptions): LlmsTxtResult
```

**Parameters:**
- `skills: ExtractedSkill[]` — 
- `options: LlmsTxtOptions` — 

**Returns:** `LlmsTxtResult`

### parseReadme

Parse a README markdown string and extract structured sections.

Extraction rules:
- **blockquote** – first `> …` line between `# title` and the first `## heading`.
- **firstParagraph** – first prose lines before the first `## heading` that are
  not a heading, badge (`[![`), image (`![`), blockquote, or blank.
  Consecutive lines are joined with a single space.
- **quickStart** – content under `## Quick Start`, `## Usage`, or `## Getting Started`.
- **features** – content under `## Features`, `## Key Features`, or `## Highlights`.
- **pitfalls** – content under `## Pitfalls`, `## Common Mistakes`, `## Gotchas`,
  or `## Caveats`.

```ts
parseReadme(markdown: string): ParsedReadme
```

**Parameters:**
- `markdown: string` — 

**Returns:** `ParsedReadme`

### auditSkill

Run the documentation audit on a single extracted skill.

Executes 20+ checks across fatal/error/warning/alert severity levels and returns
a structured result with issues, passing checks, and summary counts.

```ts
auditSkill(skill: ExtractedSkill, context: AuditContext): AuditResult
```

**Parameters:**
- `skill: ExtractedSkill` — 
- `context: AuditContext` — 

**Returns:** `AuditResult`

### formatAuditText

Format an AuditResult as human-readable text suitable for TypeDoc logs.

Output groups issues by severity (fatal → error → warning → alert),
then lists passing checks at the end. Empty severity groups are omitted.

```ts
formatAuditText(result: AuditResult): string
```

**Parameters:**
- `result: AuditResult` — 

**Returns:** `string`

### formatAuditJson

Format an AuditResult as pretty-printed JSON for machine consumption.

Returns the full result object serialized with 2-space indentation so it
can be parsed by downstream tooling without any further transformation.

```ts
formatAuditJson(result: AuditResult): string
```

**Parameters:**
- `result: AuditResult` — 

**Returns:** `string`

### renderConfigSurfaceSection

Render ExtractedConfigSurface[] as SKILL.md inline sections.

CLI surfaces → ## Commands
Config/env surfaces → ## Configuration

```ts
renderConfigSurfaceSection(surfaces: ExtractedConfigSurface[] | undefined): string
```

**Parameters:**
- `surfaces: ExtractedConfigSurface[] | undefined` — 

**Returns:** `string`

### renderConfigReference

Render ExtractedConfigSurface[] as per-option detail for reference files.

CLI surfaces → # Commands with ## commandName / #### --flag
Config/env surfaces → # Configuration with ## InterfaceName / #### propertyName

```ts
renderConfigReference(surfaces: ExtractedConfigSurface[] | undefined): string
```

**Parameters:**
- `surfaces: ExtractedConfigSurface[] | undefined` — 

**Returns:** `string`

### parseMarkdownDoc

Parse a markdown document string into a structured `ParsedMarkdownDoc`.

```ts
parseMarkdownDoc(markdown: string, filePath: string): ParsedMarkdownDoc
```

**Parameters:**
- `markdown: string` — Raw markdown source text.
- `filePath: string` — File path used for `relativePath`, title fallback, and order fallback.

**Returns:** `ParsedMarkdownDoc`

### scanDocs

Scan a docs directory and return parsed markdown documents.

- Returns `[]` when `docsDir` does not exist.
- Recursively collects `.md` / `.mdx` files, honouring exclude patterns.
- Default exclusions: **/api/**, **/node_modules/**, **/.specify/**, **/superpowers/**.
- Sorts ascending by `order`, then alphabetically by `title`.
- Truncates to `maxDocs` (default 20).

```ts
scanDocs(options: DocsExtractionOptions): ParsedMarkdownDoc[]
```

**Parameters:**
- `options: DocsExtractionOptions` — 

**Returns:** `ParsedMarkdownDoc[]`

### docsToExtractedDocuments

Convert parsed markdown documents to the generic `ExtractedDocument` shape.

```ts
docsToExtractedDocuments(docs: ParsedMarkdownDoc[]): ExtractedDocument[]
```

**Parameters:**
- `docs: ParsedMarkdownDoc[]` — 

**Returns:** `ExtractedDocument[]`

### ExtractedSkill

Extracted API surface for a single package/module

### ExtractedFunction

### ExtractedClass

### ExtractedType

### ExtractedEnum

### ExtractedParameter

### ExtractedProperty

### ExtractedVariable

### ExtractedDocument

### RenderedFile

A single rendered file

### RenderedSkill

A rendered skill with progressive disclosure structure

### LlmsTxtResult

### AuditSeverity

Severity levels for audit issues, ordered from most to least severe.
- `fatal`: Disqualifying problems that prevent the skill from being used safely
- `error`: Serious problems that significantly degrade skill quality
- `warning`: Moderate problems that reduce skill effectiveness
- `alert`: Minor issues or suggestions for improvement

```ts
type AuditSeverity = "fatal" | "error" | "warning" | "alert"
```

### AuditIssue

A single audit finding that identifies a problem in the skill package.

### AuditPass

A check that the audit engine ran and the skill package passed.

### AuditContext

Contextual metadata about the package being audited, used to evaluate
relevance and quality of skill content.

### ParsedReadme

Structured representation of key sections extracted from a package README.

### AuditResult

The complete output of an audit run against a single skill package.

### ConfigSourceType

The source type of a configuration surface:
- 'cli'    — a command-line command or subcommand
- 'config' — a configuration file (e.g. JSON, YAML, TOML)
- 'env'    — environment variables

```ts
type ConfigSourceType = "cli" | "config" | "env"
```

### ExtractedConfigSurface

Describes a single configuration surface: a CLI command, config file schema,
or environment-variable group that an agent may need to invoke or populate.

### ExtractedConfigOption

A single configurable option within a surface: a CLI flag, a config-file key,
or an environment variable (or any combination of the three).

### ExtractedConfigArgument

A positional command-line argument accepted by a CLI surface.
Positional arguments are ordered and do not use flag prefixes.

### ParsedSection

A single section extracted from a markdown document, corresponding to one
heading and all content that follows it until the next heading.

### ParsedMarkdownDoc

A fully parsed markdown document with structured metadata and sections.

---

## @to-skills/typedoc

TypeDoc plugin that extracts structured AI agent skills from the TypeDoc reflection tree.

Install as `typedoc-plugin-to-skills` for auto-discovery, or import `@to-skills/typedoc`
directly. The plugin hooks into TypeDoc's converter to extract functions, classes, types,
enums, config surfaces, and documents, then renders them as SKILL.md + reference files
via `@to-skills/core`.

### load

```ts
load(app: Application): void
```

**Parameters:**
- `app: Application` — 

---

## @to-skills/cli

CLI extraction for commander/yargs programs.

Provides a three-phase pipeline for extracting structured skill data from CLI tools:
1. **Introspect** — walk a Commander program tree to extract commands, options, and arguments
2. **Parse** — fallback: parse `--help` text output when runtime introspection is unavailable
3. **Correlate** — merge JSDoc metadata from typed config interfaces into CLI option metadata

The result is an `ExtractedSkill` that can be rendered by `@to-skills/core`.

### introspectCommander

Introspects a commander Program object and extracts all top-level command
definitions as ExtractedConfigSurface[].

```ts
introspectCommander(program: any): ExtractedConfigSurface[]
```

**Parameters:**
- `program: any` — A commander `Command` instance (typed as `any` to avoid
  a hard dependency on the commander package at the call site).

**Returns:** `ExtractedConfigSurface[]`

### parseHelpOutput

Parse standard `--help` text output into an ExtractedConfigSurface.

This is the framework-agnostic fallback used when runtime introspection of a
commander/yargs program is not available.

```ts
parseHelpOutput(text: string, commandName: string): ExtractedConfigSurface
```

**Parameters:**
- `text: string` — Raw text emitted by `program --help`
- `commandName: string` — Canonical name for this surface (e.g. `"generate"`)

**Returns:** `ExtractedConfigSurface`

### correlateFlags

Merges JSDoc tag metadata from a typed config interface surface into CLI
option metadata extracted from commander/--help output.

The CLI surface is treated as authoritative for structural fields (flags,
description, required, defaultValue). The config surface contributes rich
JSDoc metadata (remarks, useWhen, avoidWhen, pitfalls, category) that the
CLI help text does not capture.

```ts
correlateFlags(cliSurface: ExtractedConfigSurface, configSurface: ExtractedConfigSurface | undefined): ExtractedConfigSurface
```

**Parameters:**
- `cliSurface: ExtractedConfigSurface` — The surface extracted from CLI introspection/help parsing
- `configSurface: ExtractedConfigSurface | undefined` — The surface extracted from a typed config interface (optional)

**Returns:** `ExtractedConfigSurface`

### extractCliSkill

Extract a structured skill from a CLI program.

Runs the three-phase pipeline: introspect (or parse help) → correlate with typed interfaces → produce ExtractedSkill.

```ts
extractCliSkill(options: CliExtractionOptions): Promise<ExtractedSkill>
```

**Parameters:**
- `options: CliExtractionOptions` — 

**Returns:** `Promise<ExtractedSkill>`

---