git:20260604.982a8d8 to git:20260702.6607d9d

# skillit

> Compile-time generator of AI agent skills from your codebase. Inline docs, CLI definitions, config schemas, and examples compile into progressively disclosed SKILL.md files that any LLM can discover.

## @skillit/core

Shared types, renderers, and utilities for the skillit 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`.

- **troubleshooting** – content under `## Troubleshooting`, `## Common Issues`, `## Common Errors`,

or `## FAQ`.

```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[]`

### scanRootDocs

Scan root-level .md files that contain useful documentation.

Skips README.md (parsed separately), LICENSE, CODE_OF_CONDUCT.md.

```ts

scanRootDocs(projectRoot: string): ParsedMarkdownDoc[]

```

**Parameters:**

- `projectRoot: string` —

**Returns:** `ParsedMarkdownDoc[]`

### scanExamples

Scan an examples directory for `.ts`/`.js`/`.tsx`/`.jsx` files and parse

their import statements and top-level comments.

```ts

scanExamples(examplesDir: string): ParsedExample[]

```

**Parameters:**

- `examplesDir: string` —

**Returns:** `ParsedExample[]`

```ts

JSDoc tags (use TypeDoc extraction instead)

```

### linkExamplesToSkill

Mutate an `ExtractedSkill` in place by linking each example to the first

matching exported function or class. Falls back to `skill.examples` when no

symbol matches any export.

```ts

linkExamplesToSkill(examples: ParsedExample[], skill: ExtractedSkill): void

```

**Parameters:**

- `examples: ParsedExample[]` —

- `skill: ExtractedSkill` —

### 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.

### ParsedExample

---

## @skillit/typedoc

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

Install as `typedoc-plugin-skillit` for auto-discovery, or import `@skillit/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 `@skillit/core`.

### load

```ts

load(app: Application): void

```

**Parameters:**

- `app: Application` —

---

## @skillit/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 `@skillit/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

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

---