WebMCP Documentation

agent-skills-ts-sdk is a TypeScript implementation of the AgentSkills 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

npm install agent-skills-ts-sdk

Minimal example

Parsing

`parseSkillContent(content, options?)`

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

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:

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.

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.

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.

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.

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.

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.

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.

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.

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 for content parsing and validation. It aligns with the Python skills-ref reference implementation. Directory-level checks are surfaced through validateSkillEntries so hosts can supply their own storage model.

​Installation

​Minimal example

​Parsing

​parseSkillContent(content, options?)

​parseFrontmatter(content, options?)

​frontmatterToProperties(frontmatter)

​extractBody(content)

​findSkillMdFile(files)

​readSkillProperties(files, options?)

​extractResourceLinks(body)

​Validation

​validateSkillContent(content)

​validateSkillProperties(properties, options?)

​validateSkillEntries(files, options?)

​Validation rules

​Validation constants

​Prompt utilities

​toPrompt(entries)

​toDisclosurePrompt(entries)

​toDisclosureInstructions(options)

​toReadToolSchema(skills, options?)

​handleSkillRead(args)

​Diff and patch

​createSkillPatch(oldContent, newContent, options?)

​applySkillPatch(content, patch, options?)

​diffSkillContent(oldContent, newContent)

​validateSkillPatch(patch)

​Utilities

​Types

​Core types

​Storage types

​Prompt types

​Patch types

​Read tool types

​Error classes

​Specification compliance