agent-skills-ts-sdk

TypeScript parser, validator, prompt, and patch utilities for Agent Skills SKILL.md files. The package tracks the AgentSkills specification and the Python skills-ref reference behavior.

What It Does

SKILL.md files
  |
  v
parse + validate
  |
  +--> prompt XML + read tool schema --> model system prompt + tools
  |
  +--> diff + patch helpers -----------> model-proposed skill edits

Install

pnpm add agent-skills-ts-sdk

Quick Start

Parse and validate

import { parseSkillContent, validateSkillContent } from "agent-skills-ts-sdk";

const content = `---
name: my-skill
description: A test skill
---
# My Skill

Instructions here.`;

const { properties, body } = parseSkillContent(content);
const errors = validateSkillContent(content);

Use { inputMode: "embedded" } when SKILL.md text comes from a DOM/script tag and may start with a newline.

Validate in-memory files

import { readSkillProperties, validateSkillEntries } from "agent-skills-ts-sdk";

const files = [{ name: "SKILL.md", content }];
const properties = readSkillProperties(files);
const errors = validateSkillEntries(files, { expectedName: properties.name });

Build model-facing prompt content

import { createSkillRegistry, skillSourceFromEntries } from "agent-skills-ts-sdk";

const source = skillSourceFromEntries([
  { name: "SKILL.md", content: skillMarkdown },
  { name: "references/build-pizza.md", content: buildPizzaReference },
]);

const registry = await createSkillRegistry([source]);
const systemPrompt = registry.systemPrompt({ toolName: "read_site_context" });
const readTool = registry.readTool({
  toolName: "read_site_context",
});

Model-facing shape:

system prompt
  +-- disclosure instructions
  +-- <available_skills>
        +-- pizza-maker
              +-- resources: build-pizza

tool
  +-- read_site_context({ name, resource? })

Formatted for readability, the system prompt looks like:

Skills provide context for using tools effectively.
Call read_site_context with a skill name to read its overview and discover available resources.
Then call read_site_context with both a skill name and resource name to read detailed instructions.

<available_skills>
  <skill>
    <name>
      pizza-maker
    </name>
    <description>
      Interactive pizza builder
    </description>
    <resources>
      build-pizza
    </resources>
  </skill>
</available_skills>

readTool is a strict JSON-schema tool declaration: name is required and limited to the current skill names, resource is optional, and extra fields are rejected.

Typical read calls:

{ "name": "pizza-maker" }

{ "name": "pizza-maker", "resource": "build-pizza" }

Handle those calls with the same registry:

const result = await registry.read({ name: "pizza-maker", resource: "build-pizza" });

Apply skill patches

import { applySkillPatch, createSkillPatch } from "agent-skills-ts-sdk";

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

API Shape

• Parsing: parseFrontmatter, parseSkillContent, extractBody, frontmatterToProperties, extractResourceLinks.
• Validation: validateSkillProperties, validateSkillContent, validateSkillEntries.
• In-memory lookup: findSkillMdFile, readSkillProperties.
• Sources/registry: skillSourceFromEntries, createSkillRegistry, SkillRegistry.
• Prompt/disclosure: toPrompt, toDisclosurePrompt, toDisclosureInstructions, toReadToolSchema, handleSkillRead.
• Patch utilities: diffSkillContent, createSkillPatch, applySkillPatch, validateSkillPatch.
• Utilities/types: estimateTokens, normalizeNFKC, SkillFrontmatter, SkillProperties, SkillFile, SkillMetadata.

See API.md for the full module reference.

Spec Notes

Required fields are name and description. Optional fields are license, compatibility, metadata, and experimental allowed-tools.

Directory-level checks are exposed through validateSkillEntries so filesystem, Durable Object, and other storage hosts can use the same validation rules.

Playground

vp run playground:dev

The playground runs parser, validator, prompt, patch, token estimate, storage, and rendered Markdown examples in the browser.

Development

vp test
vp check
vp run test:coverage

References

• AgentSkills specification
• Python reference implementation
• Example skills

License

MIT