agent-skills-ts-sdk 2.3.1 → 2.3.3

package/API.md

@@ -0,0 +1,217 @@
+# agent-skills-ts-sdk API
+
+This package is a TypeScript implementation of the Agent Skills specification.
+It follows the public spec and mirrors the Python reference library behavior
+with a storage-agnostic, in-memory API surface.
+
+References:
+
+- Spec: https://agentskills.io/specification
+- Reference implementation: https://github.com/agentskills/agentskills/tree/main/skills-ref
+- Parser reference: https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/parser.py
+- Validator reference: https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/validator.py
+- Models reference: https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/models.py
+- Prompt reference: https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/prompt.py
+
+## Module map (TypeScript → Python reference)
+
+- `src/models.ts` → [`skills_ref/models.py`](https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/models.py)
+- `src/parser.ts` → [`skills_ref/parser.py`](https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/parser.py)
+- `src/validator.ts` → [`skills_ref/validator.py`](https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/validator.py)
+- `src/prompt.ts` → [`skills_ref/prompt.py`](https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/prompt.py)
+- `src/patch.ts` → patch/diff utilities (no Python reference module)
+- `src/errors.ts` → [`skills_ref/errors.py`](https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/errors.py)
+- `src/utils/*` → helper logic used by parsing and validation
+
+## Core types
+
+### SkillFrontmatter
+
+Spec-accurate YAML frontmatter shape. Keys are exactly as they appear in
+`SKILL.md` (`allowed-tools` stays hyphenated). Required fields are
+`name` and `description`.
+
+### SkillProperties
+
+JavaScript-friendly representation of frontmatter. `allowed-tools` becomes
+`allowedTools`, and `metadata` is normalized to string values.
+
+### SkillFile
+
+Full record that a host can store in its own persistence layer. Contains the
+raw content, parsed properties, size, and timestamps.
+
+### SkillMetadata
+
+Lightweight list view for progressive disclosure with token estimates.
+
+### SkillResource / ResolvedSkill
+
+Tier-3 resource models for progressive disclosure hosts:
+
+- `SkillResource`: `{ name, path, content }`
+- `ResolvedSkill`: parsed skill body plus associated resources used by
+  read handlers and tool schema generation.
+
+## Parsing
+
+### parseFrontmatter(content, options?)
+
+Parses YAML frontmatter and returns `{ metadata, body }`.
+Behavior matches the reference parser:
+
+- Requires frontmatter, validates name/description presence and non-empty strings.
+- Preserves metadata scalar formatting by reading YAML source tokens where possible.
+- Returns hyphenated keys in `metadata`.
+
+`options.inputMode`:
+
+- `strict` (default): no preprocessing; requires content to start with `---`.
+- `embedded`: explicit host opt-in for web/embed extraction contexts;
+  strips UTF-8 BOM and leading whitespace before strict parsing.
+
+### parseSkillContent(content, options?)
+
+Returns `{ properties, body }` where `properties` is the camel-cased
+`SkillProperties` representation of the frontmatter.
+Accepts the same optional `ParseFrontmatterOptions` as `parseFrontmatter`.
+
+### extractResourceLinks(body)
+
+Extracts tier-3 resource references from Markdown links and bare relative paths.
+
+- Includes paths under observed skill-local resource directories such as
+  `scripts/*`, `references/*`, `assets/*`, `lib/*`, `rules/*`, or `templates/*`.
+- Includes root-level files when referenced as Markdown links.
+- Ignores URLs, anchors, and traversal-style paths.
+- Accepts and normalizes leading `./`.
+- Returns deduplicated `{ name, path }` pairs.
+
+### extractBody(content)
+
+Strips frontmatter and returns the markdown body.
+
+### frontmatterToProperties(metadata)
+
+Converts `SkillFrontmatter` to `SkillProperties` without re-parsing.
+
+### findSkillMdFile(files)
+
+Finds `SKILL.md` from an in-memory list of files, preferring uppercase and
+falling back to `skill.md`.
+
+### readSkillProperties(files, options)
+
+Reads `SKILL.md` from an in-memory list and returns `SkillProperties`.
+This is the filesystem-free analog of `skills_ref.read_properties`.
+
+## Validation
+
+### validateSkillProperties(properties, options)
+
+Validates name, description, compatibility, and optional frontmatter field
+types. Provide `expectedName` to enforce a name match against a host-provided
+value (e.g., directory slug).
+
+### validateSkillContent(content)
+
+Parses and validates a single `SKILL.md` content string, including unknown
+frontmatter keys.
+
+### validateSkillEntries(entries, options)
+
+Validates a skill represented as an in-memory file list. The host supplies
+storage context via:
+
+- `exists` (missing path),
+- `isDirectory` (path is not a directory),
+- `expectedName` (name-to-location match),
+- `location` (user-facing label in error messages).
+
+This mirrors the reference `validate()` without assuming a filesystem.
+
+## Prompt generation
+
+### toPrompt(entries)
+
+Builds the `<available_skills>` XML block. Accepts either:
+
+- `SkillPromptEntry` objects with `name`, `description`, and optional `location`, or
+- `SkillPromptSource` objects with raw `SKILL.md` content + optional `location`.
+
+### toDisclosurePrompt(entries)
+
+Builds `<available_skills>` XML with optional `<resources>` hints for
+progressive disclosure hosts.
+
+### toDisclosureInstructions(options?)
+
+Generates canonical system-instruction text for the progressive disclosure
+read protocol with configurable tool name.
+
+### handleSkillRead(skills, args)
+
+Pure in-memory 2-level read handler:
+
+- no `resource`: returns skill body (tier 2)
+- with `resource`: returns resource content (tier 3)
+- validates tool-call argument shape at runtime
+- returns structured errors with machine-readable `code`
+  (`INVALID_ARGUMENT`, `SKILL_NOT_FOUND`, `RESOURCE_NOT_FOUND`)
+
+### toReadToolSchema(skills, options?)
+
+Builds strict JSON-schema declaration for a read tool:
+
+- `name` enum derived from runtime skills
+- optional `resource` string
+- `additionalProperties: false`
+
+XML is escaped to preserve safe system prompt formatting.
+
+## Diff + patch
+
+### diffSkillContent(base, updated)
+
+Returns a line-based diff with `equal`, `insert`, and `delete` segments.
+This is suitable for UI diff rendering or model feedback loops.
+
+### createSkillPatch(base, updated, options)
+
+Generates a contextual patch for the delta between two `SKILL.md` strings.
+Each operation is a `replace` hunk that includes a small amount of context
+to keep patches stable across minor edits.
+
+### validateSkillPatch(patch)
+
+Runtime patch validation for model-provided payloads. Returns structured,
+model-friendly errors when a patch is malformed or unsupported.
+
+### applySkillPatch(content, patch, options)
+
+Applies patch operations sequentially and returns a structured result:
+
+- `ok: true` with `content` when the patch applies cleanly.
+- `ok: false` with `errors` when a target cannot be found, is ambiguous,
+  or the resulting content violates the Agent Skills spec.
+
+By default, the resulting `SKILL.md` is validated with `validateSkillContent`
+and can optionally enforce an `expectedName`. `options.expectedMatches` must be
+a positive integer when provided.
+
+## Utilities
+
+### normalizeNFKC(str)
+
+Unicode normalization used by name validation to match Python’s
+`unicodedata.normalize("NFKC", ...)`.
+
+### estimateTokens(text)
+
+Conservative token estimator (~1 token per 4 characters) for context budgeting.
+
+## Error types
+
+- `ParseError`: malformed frontmatter, invalid YAML, missing `SKILL.md`.
+- `ValidationError`: invalid or missing required fields, length violations,
+  unexpected frontmatter keys.

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# agent-skills-ts-sdk
+
+## 2.3.3
+
+### Patch Changes
+
+- Add an AgentSkills reference lock and CI drift check for the upstream specification and Python `skills-ref` package.
+- Align parser, validator, disclosure, and patch behavior with the pinned AgentSkills reference.
+- Document intentional conformance divergences for stricter SDK validation behavior.
+
+## 2.3.1
+
+## 2.3.0
+
+## 2.2.0
+
+## 2.1.0
+
+## 2.0.13
+
+## 2.0.12
+
+## 2.0.11
+
+## 2.0.10
+
+### Patch Changes
+
+- Remove noisy console.warn from toTransportSchema for empty schemas and schemas without root type. The normalization behavior is correct — no need to warn consumers.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to a respectful, harassment-free project environment for everyone.
+
+## Expected Behavior
+
+- Be direct, constructive, and kind.
+- Respect differing experience levels and viewpoints.
+- Focus criticism on ideas, code, and project outcomes.
+- Accept responsibility for mistakes and correct them when possible.
+
+## Unacceptable Behavior
+
+- Harassment, threats, or personal attacks.
+- Sexualized language or attention.
+- Publishing private information without permission.
+- Sustained disruption of project discussions.
+
+## Enforcement
+
+Maintainers may remove comments, close issues, block participants, or take other reasonable action to protect the project community.
+
+Report security-sensitive issues through `SECURITY.md`. For conduct issues, contact a project maintainer through GitHub Issues or the maintainer profile listed in `CODEOWNERS`.

package/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thanks for helping improve `agent-skills-ts-sdk`.
+
+## Development
+
+Install dependencies with Vite+:
+
+```bash
+vp install
+```
+
+Run the main checks before opening a pull request:
+
+```bash
+vp check
+vp test run
+vp run validate:package
+```
+
+## Implementation Notes
+
+- Keep the public package shape compatible with the published package:
+  `dist/index.js` and `dist/index.d.ts`.
+- Keep parser and validator behavior aligned with the AgentSkills
+  specification and the Python reference implementation where applicable.
+- Add focused tests for parser, validator, prompt, disclosure, and patch
+  behavior instead of broad snapshot tests.
+
+## Releases
+
+The release workflow validates the package, versions through Changesets, and
+publishes through npm trusted publishing from
+`WebMCP-org/agent-skills-ts-sdk`. See `docs/release.md`.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 mcp-b contributors
+Copyright (c) 2026 agent-skills-ts-sdk contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/PRIVACY.md

@@ -0,0 +1,15 @@
+# Privacy
+
+`agent-skills-ts-sdk` is an open-source TypeScript library. The library itself
+does not operate a hosted service, collect analytics, or transmit data to the
+package maintainers.
+
+At runtime, the library parses and validates skill content supplied by the
+consuming application. Applications that use this package control where skill
+content is loaded from, how validation results are stored, and whether any
+parsed data is sent to another service.
+
+This repository uses development tools such as package managers and CI
+services. Those tools may have their own telemetry or logs when contributors
+run them or when maintainers run CI. That behavior is outside the runtime
+behavior of the published library.

package/README.md

@@ -21,12 +21,27 @@ Agent Skills are folders of instructions, scripts, and resources that agents can
 pnpm add agent-skills-ts-sdk
 ```
 
+## Playground
+
+This repo includes a small browser-run React playground for trying the SDK
+against editable `SKILL.md` content.
+
+```bash
+pnpm playground:dev
+```
+
+The playground shows live browser-side parsing and validation, prompt metadata,
+token estimates, patch generation, IndexedDB storage, and raw/rendered Markdown
+previews using the same SDK entry points. It also includes a CopilotKit-rendered
+mock agent transcript that simulates a model reading and using the active skill
+without any backend LLM call.
+
 ## Usage
 
 ### Parsing SKILL.md
 
 ```typescript
-import { parseSkillContent, validateSkillContent } from 'agent-skills-ts-sdk';
+import { parseSkillContent, validateSkillContent } from "agent-skills-ts-sdk";
 
 const content = `---
 name: my-skill
@@ -40,7 +55,7 @@ const { properties, body } = parseSkillContent(content);
 
 const errors = validateSkillContent(content);
 if (errors.length > 0) {
-  console.error('Validation errors:', errors);
+  console.error("Validation errors:", errors);
 }
 ```
 
@@ -49,18 +64,18 @@ newline), opt in explicitly:
 
 ```typescript
 const { properties, body } = parseSkillContent(contentFromDom, {
-  inputMode: 'embedded',
+  inputMode: "embedded",
 });
 ```
 
 ### Validation
 
 ```typescript
-import { validateSkillProperties } from 'agent-skills-ts-sdk';
+import { validateSkillProperties } from "agent-skills-ts-sdk";
 
 const properties = {
-  name: 'my-skill',
-  description: 'A test skill',
+  name: "my-skill",
+  description: "A test skill",
 };
 
 const errors = validateSkillProperties(properties);
@@ -69,9 +84,9 @@ const errors = validateSkillProperties(properties);
 ### In-memory file lists (Durable Objects or other non-filesystem hosts)
 
 ```typescript
-import { findSkillMdFile, readSkillProperties, validateSkillEntries } from 'agent-skills-ts-sdk';
+import { findSkillMdFile, readSkillProperties, validateSkillEntries } from "agent-skills-ts-sdk";
 
-const files = [{ name: 'SKILL.md', content: skillMarkdown }];
+const files = [{ name: "SKILL.md", content: skillMarkdown }];
 
 const entry = findSkillMdFile(files);
 const properties = readSkillProperties(files);
@@ -81,9 +96,9 @@ const errors = validateSkillEntries(files, { expectedName: properties.name });
 ### Prompt generation
 
 ```typescript
-import { toPrompt } from 'agent-skills-ts-sdk';
+import { toPrompt } from "agent-skills-ts-sdk";
 
-const promptBlock = toPrompt([{ content: skillMarkdown, location: 'skills/my-skill/SKILL.md' }]);
+const promptBlock = toPrompt([{ content: skillMarkdown, location: "skills/my-skill/SKILL.md" }]);
 ```
 
 ### Progressive disclosure helpers
@@ -94,21 +109,21 @@ import {
   toDisclosureInstructions,
   toDisclosurePrompt,
   toReadToolSchema,
-} from 'agent-skills-ts-sdk';
+} from "agent-skills-ts-sdk";
 
-const instructions = toDisclosureInstructions({ toolName: 'read_site_context' });
+const instructions = toDisclosureInstructions({ toolName: "read_site_context" });
 const skillsXml = toDisclosurePrompt([
-  { name: 'pizza-maker', description: 'Interactive pizza builder', resources: ['build-pizza'] },
+  { name: "pizza-maker", description: "Interactive pizza builder", resources: ["build-pizza"] },
 ]);
-const readTool = toReadToolSchema([{ name: 'pizza-maker' }], {
-  toolName: 'read_site_context',
+const readTool = toReadToolSchema([{ name: "pizza-maker" }], {
+  toolName: "read_site_context",
 });
 ```
 
 ### Diff + patch
 
 ```typescript
-import { createSkillPatch, applySkillPatch } from 'agent-skills-ts-sdk';
+import { createSkillPatch, applySkillPatch } from "agent-skills-ts-sdk";
 
 const patch = createSkillPatch(oldContent, newContent);
 const result = applySkillPatch(oldContent, patch);
@@ -132,7 +147,7 @@ if (!result.ok) {
 
 ### Validation
 
-- `validateSkillProperties` enforces the name/description/compatibility rules and optionally checks an expected name.
+- `validateSkillProperties` enforces field types, name/description/compatibility rules, and optionally checks an expected name.
 - `validateSkillContent` validates a single SKILL.md string, including unknown frontmatter fields.
 - `validateSkillEntries` mirrors `skills-ref validate` for in-memory file lists while letting the host surface path and directory state.
 
@@ -176,8 +191,8 @@ are surfaced through `validateSkillEntries` so hosts can supply their own storag
 ### Optional Fields
 
 - `license`
-- `compatibility` (max 500 chars)
-- `metadata` (key-value pairs)
+- `compatibility` (1-500 chars when present)
+- `metadata` (string key-value pairs)
 - `allowed-tools` (experimental)
 
 ### Validation Rules
@@ -194,13 +209,13 @@ This package follows Test-Driven Development with comprehensive test coverage:
 
 ```bash
 # Run tests
-pnpm test
+vp test
 
-# Run tests in watch mode
-pnpm test:watch
+# Run formatting, linting, and type checks
+vp check
 
 # Generate coverage report
-pnpm test:coverage
+vp run test:coverage
 ```
 
 **Coverage goals:**

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Report suspected vulnerabilities through GitHub private vulnerability reporting for this repository:
+
+https://github.com/WebMCP-org/agent-skills-ts-sdk/security/advisories/new
+
+Do not open a public issue for a vulnerability report. Include the affected version, reproduction details, expected impact, and any known workaround.
+
+## Supported Versions
+
+Security fixes are provided for the latest published major version unless a separate support policy is documented in a release note.