> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-b-sync-npm-packages-docs-bf03420.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# agent-skills-ts-sdk

> TypeScript parser, validator, prompt builder, and patch utilities for the AgentSkills specification.

`agent-skills-ts-sdk` is a TypeScript implementation of the [AgentSkills specification](https://agentskills.io/specification). It parses `SKILL.md` files, validates frontmatter, generates prompt blocks, and applies patches. This package sits adjacent to the core WebMCP runtime and does not depend on it.

```
npm: agent-skills-ts-sdk
license: MIT
node: >= 22.12
dependencies: yaml
```

## Installation

```bash theme={null}
npm install agent-skills-ts-sdk
```

## Minimal example

<Snippet file="snippets/packages/agent-skills-quickstart.ts" />

## Parsing

### `parseSkillContent(content, options?)`

Parses a `SKILL.md` string into frontmatter properties and a markdown body.

```typescript theme={null}
import { parseSkillContent } from 'agent-skills-ts-sdk';

const { properties, body } = parseSkillContent(`---
name: my-skill
description: A test skill
---
# My Skill

Instructions here.`);
```

For content extracted from a DOM `<script>` element (which may have a leading newline), use embedded mode:

```typescript theme={null}
const { properties, body } = parseSkillContent(contentFromDom, {
  inputMode: 'embedded',
});
```

### `parseFrontmatter(content, options?)`

Parses YAML frontmatter into the spec's hyphenated keys. Trims required fields and preserves metadata scalars as strings.

### `frontmatterToProperties(frontmatter)`

Converts a `SkillFrontmatter` object to a camelCased `SkillProperties` shape without re-parsing.

### `extractBody(content)`

Strips frontmatter and returns the markdown body.

### `findSkillMdFile(files)`

Finds the `SKILL.md` entry in an in-memory file list. Does not assume a filesystem.

```typescript theme={null}
import { findSkillMdFile, readSkillProperties } from 'agent-skills-ts-sdk';

const files = [{ name: 'SKILL.md', content: skillMarkdown }];
const entry = findSkillMdFile(files);
const properties = readSkillProperties(files);
```

### `readSkillProperties(files, options?)`

Reads and parses skill properties from an in-memory file list.

### `extractResourceLinks(body)`

Extracts resource links from the markdown body.

## Validation

### `validateSkillContent(content)`

Validates a single `SKILL.md` string. Checks frontmatter fields, unknown fields, and structural rules.

```typescript theme={null}
import { validateSkillContent } from 'agent-skills-ts-sdk';

const errors = validateSkillContent(content);
if (errors.length > 0) {
  console.error('Validation errors:', errors);
}
```

### `validateSkillProperties(properties, options?)`

Validates a `SkillProperties` object against name/description/compatibility rules.

```typescript theme={null}
import { validateSkillProperties } from 'agent-skills-ts-sdk';

const errors = validateSkillProperties({
  name: 'my-skill',
  description: 'A test skill',
});
```

### `validateSkillEntries(files, options?)`

Mirrors the reference library's `skills-ref validate` for in-memory file lists. Hosts supply their own storage model.

### Validation rules

| Rule            | Constraint                                                                                                                  |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `name`          | Required. Max 64 characters. Lowercase only. Hyphens allowed (not at start/end, no consecutive). Unicode normalized (NFKC). |
| `description`   | Required. Max 1024 characters.                                                                                              |
| `compatibility` | Optional. Max 500 characters.                                                                                               |
| `license`       | Optional.                                                                                                                   |
| `metadata`      | Optional. Key-value pairs.                                                                                                  |
| `allowed-tools` | Optional. Experimental.                                                                                                     |

### Validation constants

| Constant                   | Value                                |
| -------------------------- | ------------------------------------ |
| `MAX_SKILL_NAME_LENGTH`    | `64`                                 |
| `MAX_DESCRIPTION_LENGTH`   | `1024`                               |
| `MAX_COMPATIBILITY_LENGTH` | `500`                                |
| `ALLOWED_FIELDS`           | Set of valid frontmatter field names |

## Prompt utilities

### `toPrompt(entries)`

Builds an `<available_skills>` XML block from parsed entries or raw `SKILL.md` content.

```typescript theme={null}
import { toPrompt } from 'agent-skills-ts-sdk';

const promptBlock = toPrompt([
  { content: skillMarkdown, location: 'skills/my-skill/SKILL.md' },
]);
```

### `toDisclosurePrompt(entries)`

Generates a disclosure prompt, optionally including resource names for tier-3 hints.

```typescript theme={null}
import { toDisclosurePrompt } from 'agent-skills-ts-sdk';

const xml = toDisclosurePrompt([
  { name: 'pizza-maker', description: 'Interactive pizza builder', resources: ['build-pizza'] },
]);
```

### `toDisclosureInstructions(options)`

Generates canonical read-protocol instruction text.

```typescript theme={null}
import { toDisclosureInstructions } from 'agent-skills-ts-sdk';

const instructions = toDisclosureInstructions({ toolName: 'read_site_context' });
```

### `toReadToolSchema(skills, options?)`

Builds a strict JSON Schema declaration for a read tool.

```typescript theme={null}
import { toReadToolSchema } from 'agent-skills-ts-sdk';

const schema = toReadToolSchema(
  [{ name: 'pizza-maker' }],
  { toolName: 'read_site_context' }
);
```

### `handleSkillRead(args)`

Handles 2-level read requests in memory (overview vs. specific resource).

## Diff and patch

### `createSkillPatch(oldContent, newContent, options?)`

Builds a contextual patch from two `SKILL.md` strings.

```typescript theme={null}
import { createSkillPatch, applySkillPatch } from 'agent-skills-ts-sdk';

const patch = createSkillPatch(oldContent, newContent);
const result = applySkillPatch(oldContent, patch);

if (!result.ok) {
  console.error(result.errors);
} else {
  console.log(result.content);
}
```

### `applySkillPatch(content, patch, options?)`

Applies patch operations and returns structured errors when a patch cannot be applied or yields invalid `SKILL.md`.

### `diffSkillContent(oldContent, newContent)`

Returns a line-based diff for display or patch construction.

### `validateSkillPatch(patch)`

Runtime validation for model-provided patch payloads.

## Utilities

| Function               | Description                                                               |
| ---------------------- | ------------------------------------------------------------------------- |
| `normalizeNFKC(str)`   | Matches Python's `unicodedata.normalize("NFKC", ...)` for name validation |
| `estimateTokens(text)` | Conservative heuristic for context budgeting                              |

## Types

### Core types

| Type                          | Description                                           |
| ----------------------------- | ----------------------------------------------------- |
| `SkillProperties`             | CamelCased JS view of skill frontmatter               |
| `SkillFrontmatter`            | Spec-key (`allowed-tools`) frontmatter shape          |
| `SkillParseResult`            | Result of `parseSkillContent`: `{ properties, body }` |
| `SkillFrontmatterParseResult` | Result of `parseFrontmatter`                          |
| `SkillContent`                | Raw skill content string                              |
| `SkillBody`                   | Markdown body after frontmatter removal               |
| `SkillId`                     | Branded string for skill identifiers                  |

### Storage types

| Type                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `SkillFile`         | `{ name: string, content: string }` for in-memory file lists |
| `SkillMetadata`     | Storage-friendly wrapper for persisted skills                |
| `SkillMetadataMap`  | Map of skill ID to metadata                                  |
| `SkillContentEntry` | Entry for prompt generation                                  |
| `ResolvedSkill`     | Fully resolved skill with properties, body, and metadata     |
| `SkillResource`     | A skill resource reference                                   |

### Prompt types

| Type                           | Description                            |
| ------------------------------ | -------------------------------------- |
| `SkillPromptEntry`             | Entry passed to `toPrompt`             |
| `SkillPromptSource`            | Source location for a skill            |
| `DisclosurePromptEntry`        | Entry passed to `toDisclosurePrompt`   |
| `DisclosureInstructionOptions` | Options for `toDisclosureInstructions` |

### Patch types

| Type                         | Description                                    |
| ---------------------------- | ---------------------------------------------- |
| `SkillPatch`                 | A patch object with operations                 |
| `SkillPatchOperation`        | A single add/remove/replace operation          |
| `SkillPatchOperationType`    | `'add' \| 'remove' \| 'replace'`               |
| `SkillPatchApplyResult`      | Result with `ok`, `content`, and `errors`      |
| `SkillPatchValidationResult` | Validation result for model-provided patches   |
| `SkillPatchIssue`            | A specific issue found during patch validation |
| `SkillPatchIssueCode`        | Error code enum for patch issues               |
| `SkillDiffSegment`           | A segment in a line-based diff                 |
| `SkillLineDiff`              | Full line-based diff result                    |

### Read tool types

| Type                    | Description                     |
| ----------------------- | ------------------------------- |
| `ReadToolSchema`        | JSON Schema for a read tool     |
| `ReadToolSchemaOptions` | Options for `toReadToolSchema`  |
| `SkillReadArgs`         | Arguments for `handleSkillRead` |
| `SkillReadResult`       | Successful read result          |
| `SkillReadError`        | Error from a read operation     |
| `SkillReadErrorCode`    | Error code enum                 |

### Error classes

| Class             | Description                  |
| ----------------- | ---------------------------- |
| `ParseError`      | Thrown when parsing fails    |
| `ValidationError` | Thrown when validation fails |

## Specification compliance

This package mirrors the [AgentSkills specification](https://agentskills.io/specification) for content parsing and validation. It aligns with the Python [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference implementation. Directory-level checks are surfaced through `validateSkillEntries` so hosts can supply their own storage model.