agent-skills-ts-sdk 2.0.6

package/dist/index.d.ts

@@ -0,0 +1,1208 @@
+//#region src/models.d.ts
+/**
+ * Data models for Agent Skills
+ *
+ * Reference: https://agentskills.io/specification
+ * Reference Implementation: https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/models.py
+ */
+/**
+ * Stable identifier for a stored skill record.
+ *
+ * @example
+ * ```ts
+ * const id: SkillId = "skill_123"
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillId = string;
+/**
+ * Raw `SKILL.md` file content.
+ *
+ * @example
+ * ```ts
+ * const content: SkillContent = "---\nname: demo\ndescription: Demo\n---\n# Body"
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillContent = string;
+/**
+ * Markdown body content after frontmatter is removed.
+ *
+ * @example
+ * ```ts
+ * const body: SkillBody = "# Instructions"
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillBody = string;
+/**
+ * A single tier-3 resource associated with a skill.
+ *
+ * Resources are loaded on demand by the host and can originate from
+ * `scripts/`, `references/`, or `assets/`.
+ *
+ * @example
+ * ```ts
+ * const resource: SkillResource = {
+ *   name: "build-pizza",
+ *   path: "references/build-pizza",
+ *   content: "# Build Pizza\n..."
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillResource {
+  /** Resource identifier used by read handlers/tool calls. */
+  name: string;
+  /** Relative resource path from skill root. */
+  path: string;
+  /** Raw resource file contents. */
+  content: string;
+}
+/**
+ * Fully resolved in-memory skill used for progressive disclosure reads.
+ *
+ * This model intentionally includes only pure data so it can be shared across
+ * browser, server, and CLI hosts without coupling to storage or transport.
+ *
+ * @example
+ * ```ts
+ * const skill: ResolvedSkill = {
+ *   name: "pizza-maker",
+ *   description: "Interactive pizza builder",
+ *   body: "Use [build-pizza](references/build-pizza)",
+ *   resources: [{ name: "build-pizza", path: "references/build-pizza", content: "..." }]
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface ResolvedSkill {
+  /** Skill identifier from frontmatter. */
+  name: SkillFrontmatter['name'];
+  /** Skill description from frontmatter. */
+  description: SkillFrontmatter['description'];
+  /** Tier-2 instruction body from SKILL.md. */
+  body: SkillBody;
+  /** Tier-3 resources associated with this skill. */
+  resources: SkillResource[];
+  /** Optional host location label (path/URL/etc). */
+  location?: string;
+}
+/**
+ * String key-value metadata map from frontmatter.
+ *
+ * @example
+ * ```ts
+ * const metadata: SkillMetadataMap = { author: "example-org", version: "1.0" }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillMetadataMap = Record<string, string>;
+/**
+ * Space-delimited tool allowlist string (`allowed-tools` in frontmatter).
+ *
+ * @example
+ * ```ts
+ * const allowed: SkillAllowedTools = "Bash(git:*) Read"
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillAllowedTools = string;
+/**
+ * Token count estimate used for progressive disclosure.
+ *
+ * @example
+ * ```ts
+ * const tokens: SkillTokenCount = 120
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillTokenCount = number;
+/**
+ * Unix timestamp in milliseconds.
+ *
+ * @example
+ * ```ts
+ * const updatedAt: UnixMillis = Date.now()
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type UnixMillis = number;
+/**
+ * Byte count for persisted skill content.
+ *
+ * @example
+ * ```ts
+ * const size: ByteCount = 2048
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type ByteCount = number;
+/**
+ * Minimal in-memory representation of a file entry.
+ *
+ * @example
+ * ```ts
+ * const entry: SkillContentEntry = { name: "SKILL.md", content: "---\n...\n---" }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillContentEntry {
+  /** File name (for example `SKILL.md`). */
+  name: string;
+  /** File contents. */
+  content: SkillContent;
+}
+/**
+ * Canonical frontmatter keys accepted by the spec.
+ *
+ * @example
+ * ```ts
+ * for (const key of SKILL_FRONTMATTER_KEYS) {
+ *   console.log(key)
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+declare const SKILL_FRONTMATTER_KEYS: readonly ["name", "description", "license", "compatibility", "allowed-tools", "metadata"];
+/**
+ * Union of allowed frontmatter keys.
+ *
+ * @example
+ * ```ts
+ * const key: SkillFrontmatterKey = "allowed-tools"
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillFrontmatterKey = (typeof SKILL_FRONTMATTER_KEYS)[number];
+/**
+ * Frontmatter shape as defined by the spec.
+ * Required: name, description.
+ * Optional: license, compatibility, allowed-tools, metadata.
+ *
+ * @example
+ * ```ts
+ * const frontmatter: SkillFrontmatter = {
+ *   name: "demo-skill",
+ *   description: "Demonstrates the format",
+ *   "allowed-tools": "Bash(git:*)"
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/models.py
+ */
+interface SkillFrontmatter<TMetadata extends SkillMetadataMap = SkillMetadataMap> {
+  /** Required skill identifier. */
+  name: string;
+  /** Required skill description. */
+  description: string;
+  /** Optional license declaration. */
+  license?: string;
+  /** Optional host/runtime compatibility notes. */
+  compatibility?: string;
+  /** Optional space-delimited allowed-tools declaration. */
+  'allowed-tools'?: SkillAllowedTools;
+  /** Optional string metadata map. */
+  metadata?: TMetadata;
+}
+/**
+ * Result returned by `parseFrontmatter`.
+ *
+ * @example
+ * ```ts
+ * const result: SkillFrontmatterParseResult = {
+ *   metadata: { name: "demo", description: "Demo" },
+ *   body: "# Instructions"
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillFrontmatterParseResult<TMetadata extends SkillMetadataMap = SkillMetadataMap> {
+  /** Parsed spec-keyed frontmatter object. */
+  metadata: SkillFrontmatter<TMetadata>;
+  /** Markdown body after frontmatter removal. */
+  body: SkillBody;
+}
+/**
+ * Result returned by `parseSkillContent`.
+ *
+ * @example
+ * ```ts
+ * const result: SkillParseResult = {
+ *   properties: { name: "demo", description: "Demo" },
+ *   body: "# Instructions"
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillParseResult<TMetadata extends SkillMetadataMap = SkillMetadataMap> {
+  /** Parsed camel-cased properties for JS usage. */
+  properties: SkillProperties<TMetadata>;
+  /** Markdown body after frontmatter removal. */
+  body: SkillBody;
+}
+/**
+ * Frontmatter normalized for JavaScript usage.
+ * Matches the reference implementation semantics with camel-cased keys.
+ *
+ * @example
+ * ```ts
+ * const props: SkillProperties = {
+ *   name: "demo",
+ *   description: "Demo",
+ *   allowedTools: "Read"
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/models.py
+ */
+interface SkillProperties<TMetadata extends SkillMetadataMap = SkillMetadataMap> {
+  /** Required skill identifier. */
+  name: SkillFrontmatter<TMetadata>['name'];
+  /** Required skill description. */
+  description: SkillFrontmatter<TMetadata>['description'];
+  /** Optional license declaration. */
+  license?: SkillFrontmatter<TMetadata>['license'];
+  /** Optional host/runtime compatibility notes. */
+  compatibility?: SkillFrontmatter<TMetadata>['compatibility'];
+  /** Optional space-delimited allowed-tools declaration. */
+  allowedTools?: SkillFrontmatter<TMetadata>['allowed-tools'];
+  /** Optional string metadata map. */
+  metadata?: SkillFrontmatter<TMetadata>['metadata'];
+}
+/**
+ * Convert SkillProperties to dictionary, excluding null/undefined values.
+ * Matches Python reference implementation's to_dict() behavior.
+ *
+ * Note: `allowedTools` becomes `allowed-tools` with hyphen
+ * Empty metadata object is excluded
+ *
+ * @param props - JavaScript-friendly skill properties.
+ * @returns Spec-keyed frontmatter dictionary.
+ * @example
+ * ```ts
+ * const dict = skillPropertiesToDict({
+ *   name: "demo",
+ *   description: "Demo skill",
+ *   allowedTools: "Read"
+ * })
+ * // => { name: "demo", description: "Demo skill", "allowed-tools": "Read" }
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/models.py
+ */
+declare function skillPropertiesToDict<TMetadata extends SkillMetadataMap = SkillMetadataMap>(props: SkillProperties<TMetadata>): SkillFrontmatter<TMetadata>;
+/**
+ * Full skill record suitable for storage in an app-owned persistence layer.
+ *
+ * @example
+ * ```ts
+ * const file: SkillFile = {
+ *   id: "skill_1",
+ *   content: "---\nname: demo\ndescription: Demo\n---",
+ *   properties: { name: "demo", description: "Demo" },
+ *   size: 42,
+ *   createdAt: Date.now(),
+ *   updatedAt: Date.now()
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillFile<TMetadata extends SkillMetadataMap = SkillMetadataMap> {
+  /** Host-owned unique skill id. */
+  id: SkillId;
+  /** Raw SKILL.md content. */
+  content: SkillContent;
+  /** Parsed skill properties. */
+  properties: SkillProperties<TMetadata>;
+  /** Content byte size. */
+  size: ByteCount;
+  /** Record creation timestamp in milliseconds. */
+  createdAt: UnixMillis;
+  /** Record update timestamp in milliseconds. */
+  updatedAt: UnixMillis;
+}
+/**
+ * Lightweight metadata for progressive disclosure.
+ * Used in list views and skill selection UI.
+ *
+ * Progressive disclosure strategy:
+ * 1. Metadata (roughly 50-100 tokens): name + description loaded at startup
+ * 2. Full content (roughly 500-5000 tokens): loaded when activated
+ *
+ * @example
+ * ```ts
+ * const metadata: SkillMetadata = {
+ *   id: "skill_1",
+ *   name: "demo",
+ *   description: "Demo skill",
+ *   metadataTokens: 80,
+ *   fullTokens: 900,
+ *   createdAt: Date.now(),
+ *   updatedAt: Date.now()
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillMetadata<TMetadata extends SkillMetadataMap = SkillMetadataMap> {
+  /** Host-owned unique skill id. */
+  id: SkillId;
+  /** Skill identifier. */
+  name: SkillProperties<TMetadata>['name'];
+  /** Skill description. */
+  description: SkillProperties<TMetadata>['description'];
+  /** Optional license declaration. */
+  license?: SkillProperties<TMetadata>['license'];
+  /** Optional host/runtime compatibility notes. */
+  compatibility?: SkillProperties<TMetadata>['compatibility'];
+  /** Optional space-delimited allowed-tools declaration. */
+  allowedTools?: SkillProperties<TMetadata>['allowedTools'];
+  /** Optional string metadata map. */
+  metadata?: SkillProperties<TMetadata>['metadata'];
+  /** Estimated token size for metadata-only tier. */
+  metadataTokens: SkillTokenCount;
+  /** Estimated token size for full skill content. */
+  fullTokens: SkillTokenCount;
+  /** Record creation timestamp in milliseconds. */
+  createdAt: UnixMillis;
+  /** Record update timestamp in milliseconds. */
+  updatedAt: UnixMillis;
+}
+//#endregion
+//#region src/disclosure.d.ts
+declare const ERROR_CODE_SKILL_NOT_FOUND = "SKILL_NOT_FOUND";
+declare const ERROR_CODE_RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND";
+/**
+ * Stable error codes for progressive disclosure read failures.
+ */
+type SkillReadErrorCode = typeof ERROR_CODE_SKILL_NOT_FOUND | typeof ERROR_CODE_RESOURCE_NOT_FOUND;
+/**
+ * Tool call arguments for skill progressive disclosure reads.
+ */
+interface SkillReadArgs {
+  /** Skill identifier from the current skill set. */
+  name: ResolvedSkill['name'];
+  /** Optional resource identifier within the selected skill. */
+  resource?: SkillResource['name'];
+}
+/**
+ * Successful result from a skill read request.
+ */
+interface SkillReadResult {
+  /** Indicates that the read resolved successfully. */
+  ok: true;
+  /** Skill body or resource content returned by the read. */
+  content: SkillBody | SkillResource['content'];
+}
+/**
+ * Machine-readable read failure for hosts and UIs.
+ */
+interface SkillReadError {
+  /** Indicates that the read failed. */
+  ok: false;
+  /** Machine-readable error code for host-side branching. */
+  code: SkillReadErrorCode;
+  /** Human-readable error message. */
+  error: string;
+}
+/**
+ * Options for building the read tool schema declaration.
+ */
+interface ReadToolSchemaOptions {
+  /** Tool name override (defaults to `read_skill`). */
+  toolName?: string;
+  /** Tool description override. */
+  description?: string;
+}
+/**
+ * Format-agnostic read tool schema declaration.
+ *
+ * This shape maps cleanly to Gemini `functionDeclarations`, OpenAI tools,
+ * and MCP tool metadata.
+ */
+interface ReadToolSchema {
+  /** Tool name for the declaration payload. */
+  name: NonNullable<ReadToolSchemaOptions['toolName']>;
+  /** Human-readable tool description. */
+  description: NonNullable<ReadToolSchemaOptions['description']>;
+  /** JSON Schema object describing accepted arguments. */
+  parametersJsonSchema: object;
+}
+/**
+ * Handles a 2-level progressive disclosure read.
+ *
+ * - `name` only: returns skill body (tier 2)
+ * - `name` + `resource`: returns resource content (tier 3)
+ *
+ * @param skills - Fully resolved in-memory skills.
+ * @param args - Read request arguments.
+ * @returns Structured success or failure payload.
+ */
+declare function handleSkillRead(skills: ReadonlyArray<ResolvedSkill>, args: SkillReadArgs): SkillReadResult | SkillReadError;
+/**
+ * Builds a strict JSON Schema declaration for the skill read tool.
+ *
+ * The `name` enum is derived from current skills. `resource` remains a free-form
+ * string because resources are typically discovered after reading the overview.
+ *
+ * @param skills - Skills available in the current host/session.
+ * @param options - Optional tool naming and description overrides.
+ * @returns Tool declaration object with `parametersJsonSchema`.
+ */
+declare function toReadToolSchema(skills: ReadonlyArray<Pick<ResolvedSkill, 'name'>>, options?: ReadToolSchemaOptions): ReadToolSchema;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error types for AgentSkills parsing and validation
+ *
+ * Reference: https://agentskills.io/specification
+ * Reference Implementation: https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/errors.py
+ */
+/**
+ * Error thrown during SKILL.md parsing (invalid YAML, missing frontmatter, etc.)
+ *
+ * Used for:
+ * - Missing or malformed frontmatter
+ * - Invalid YAML syntax
+ * - Non-mapping YAML structure
+ * - Missing SKILL.md inputs in a host-provided file list
+ *
+ * @param message - Human-readable parse failure detail.
+ * @example
+ * ```ts
+ * throw new ParseError("SKILL.md must start with YAML frontmatter (---)")
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/errors.py
+ */
+declare class ParseError extends Error {
+  constructor(message: string);
+}
+/**
+ * Error thrown during skill validation (invalid name, missing fields, etc.)
+ *
+ * Used for:
+ * - Missing required fields (name, description)
+ * - Invalid field formats (name not lowercase, etc.)
+ * - Field length violations (name > 64 chars, description > 1024 chars, etc.)
+ * - Unexpected frontmatter fields
+ *
+ * @param message - Human-readable validation failure detail.
+ * @example
+ * ```ts
+ * throw new ValidationError("Field 'name' must be a non-empty string")
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/errors.py
+ */
+declare class ValidationError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/parser.d.ts
+declare const INPUT_MODE_STRICT = "strict";
+declare const INPUT_MODE_EMBEDDED = "embedded";
+/**
+ * Finds SKILL.md in a list of file entries, preferring uppercase over lowercase.
+ *
+ * @param files - File entries from any storage backend.
+ * @returns The selected `SKILL.md` entry, or `null` when not found.
+ * @example
+ * ```ts
+ * const entry = findSkillMdFile([
+ *   { name: "skill.md", content: "..." },
+ *   { name: "SKILL.md", content: "..." }
+ * ])
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/parser.py
+ */
+declare function findSkillMdFile<T extends Pick<SkillContentEntry, 'name'>>(files: Iterable<T>): T | null;
+/**
+ * Options for `readSkillProperties`.
+ */
+interface ReadSkillPropertiesOptions {
+  /** Optional label used in parse errors when `SKILL.md` is missing. */
+  location?: string;
+}
+/**
+ * Reads and parses the SKILL.md content from an in-memory file list.
+ * The lookup mirrors the reference behavior by preferring SKILL.md over skill.md.
+ *
+ * @param files - File entries that may contain `SKILL.md`.
+ * @param options - Optional location label for parse errors.
+ * @returns Parsed `SkillProperties`.
+ * @throws {ParseError} If `SKILL.md` cannot be located.
+ * @throws {ValidationError} If required frontmatter fields are missing or invalid.
+ * @example
+ * ```ts
+ * const properties = readSkillProperties([
+ *   { name: "SKILL.md", content: "---\nname: demo\ndescription: Demo\n---" }
+ * ])
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/parser.py
+ */
+declare function readSkillProperties<T extends SkillContentEntry, TMetadata extends SkillMetadataMap = SkillMetadataMap>(files: Iterable<T>, options?: ReadSkillPropertiesOptions): SkillProperties<TMetadata>;
+/**
+ * Converts hyphenated frontmatter keys into a JS-friendly properties shape.
+ *
+ * @param metadata - Parsed frontmatter using spec keys.
+ * @returns Camel-cased `SkillProperties` representation.
+ * @example
+ * ```ts
+ * const properties = frontmatterToProperties({
+ *   name: "demo",
+ *   description: "Demo skill",
+ *   "allowed-tools": "Bash(git:*)"
+ * })
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/models.py
+ */
+declare function frontmatterToProperties<TMetadata extends SkillMetadataMap = SkillMetadataMap>(metadata: SkillFrontmatter<TMetadata>): SkillProperties<TMetadata>;
+/**
+ * Frontmatter parser options.
+ *
+ * `strict` follows the specification and reference parser behavior exactly:
+ * content must start with `---`.
+ *
+ * `embedded` is an explicit host opt-in for web extraction contexts where
+ * content may have a leading BOM or whitespace before frontmatter.
+ */
+interface ParseFrontmatterOptions {
+  /**
+   * Input handling mode.
+   * - `strict` (default): parse exactly as provided.
+   * - `embedded`: remove UTF-8 BOM and leading whitespace before strict parse.
+   */
+  inputMode?: ParseFrontmatterInputMode;
+}
+/**
+ * Supported parse modes for frontmatter input handling.
+ */
+type ParseFrontmatterInputMode = typeof INPUT_MODE_STRICT | typeof INPUT_MODE_EMBEDDED;
+/**
+ * Parsed resource reference discovered in a skill body markdown link.
+ */
+interface ResourceLink {
+  /** Display identifier from markdown link text. */
+  name: SkillResource['name'];
+  /** Canonical resource path under scripts/, references/, or assets/. */
+  path: SkillResource['path'];
+}
+/**
+ * Extracts tier-3 resource links from skill body markdown.
+ *
+ * Only links to `scripts/*`, `references/*`, and `assets/*` are returned.
+ * External URLs, anchors, and path traversal references are ignored.
+ * Leading `./` is accepted and normalized away.
+ *
+ * @param body - Skill markdown body (without frontmatter).
+ * @returns De-duplicated list of resource links.
+ */
+declare function extractResourceLinks(body: SkillBody): ResourceLink[];
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ *
+ * @param content - Raw content of SKILL.md file
+ * @param options - Optional parsing mode. Defaults to strict spec behavior.
+ * @returns Parsed frontmatter metadata and trimmed markdown body.
+ * @throws {ParseError} If frontmatter is missing or invalid
+ * @throws {ValidationError} If required fields are missing or invalid
+ * @example
+ * ```ts
+ * const { metadata, body } = parseFrontmatter(`---
+ * name: demo
+ * description: Demo skill
+ * ---
+ * # Instructions`)
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/parser.py
+ *
+ * Spec: https://agentskills.io/specification
+ * - File must start with `---`
+ * - Frontmatter must be closed with second `---`
+ * - YAML must be valid mapping (object)
+ * - Required fields: name, description
+ * - Required fields must be non-empty strings
+ */
+declare function parseFrontmatter<TMetadata extends SkillMetadataMap = SkillMetadataMap>(content: SkillContent, options?: ParseFrontmatterOptions): SkillFrontmatterParseResult<TMetadata>;
+/**
+ * Extract markdown body from SKILL.md content (strips frontmatter).
+ *
+ * @param content - Raw content of SKILL.md file
+ * @returns Markdown body without frontmatter
+ * @example
+ * ```ts
+ * const body = extractBody(`---\nname: demo\ndescription: Demo\n---\n# Body`)
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/parser.py
+ *
+ * If content doesn't have valid frontmatter, returns the content as-is.
+ */
+declare function extractBody(content: SkillContent): SkillBody;
+/**
+ * Parse SKILL.md content into SkillProperties.
+ *
+ * @param content - Raw content of SKILL.md file
+ * @param options - Optional frontmatter parsing mode.
+ * @returns SkillProperties with parsed metadata and body
+ * @throws {ParseError} If SKILL.md has invalid format
+ * @throws {ValidationError} If required fields are missing
+ * @example
+ * ```ts
+ * const parsed = parseSkillContent(`---
+ * name: demo
+ * description: Demo skill
+ * ---
+ * # Instructions`)
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/parser.py
+ *
+ * Spec: https://agentskills.io/specification
+ */
+declare function parseSkillContent<TMetadata extends SkillMetadataMap = SkillMetadataMap>(content: SkillContent, options?: ParseFrontmatterOptions): SkillParseResult<TMetadata>;
+//#endregion
+//#region src/validator.d.ts
+/**
+ * Maximum allowed skill name length.
+ *
+ * @see https://agentskills.io/specification
+ * @example
+ * ```ts
+ * if (name.length > MAX_SKILL_NAME_LENGTH) {
+ *   // invalid
+ * }
+ * ```
+ */
+declare const MAX_SKILL_NAME_LENGTH = 64;
+/**
+ * Maximum allowed description length.
+ *
+ * @see https://agentskills.io/specification
+ * @example
+ * ```ts
+ * if (description.length > MAX_DESCRIPTION_LENGTH) {
+ *   // invalid
+ * }
+ * ```
+ */
+declare const MAX_DESCRIPTION_LENGTH = 1024;
+/**
+ * Maximum allowed compatibility string length.
+ *
+ * @see https://agentskills.io/specification
+ * @example
+ * ```ts
+ * if (compatibility.length > MAX_COMPATIBILITY_LENGTH) {
+ *   // invalid
+ * }
+ * ```
+ */
+declare const MAX_COMPATIBILITY_LENGTH = 500;
+/**
+ * Allowed frontmatter fields per Agent Skills Spec.
+ * https://agentskills.io/specification
+ *
+ * @example
+ * ```ts
+ * if (!ALLOWED_FIELDS.has("name")) {
+ *   throw new Error("configuration bug")
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/validator.py
+ */
+declare const ALLOWED_FIELDS: Set<string>;
+/**
+ * Optional host-level constraints for `validateSkillProperties`.
+ */
+interface ValidateSkillPropertiesOptions {
+  /** Expected skill name (for example, directory or slug match). */
+  expectedName?: SkillProperties['name'];
+}
+/**
+ * Validate skill properties.
+ *
+ * This is the core validation function that works on parsed properties.
+ * Provide expectedName to enforce a host-level name match (directory, slug, or ID).
+ *
+ * @param properties - Parsed skill properties
+ * @param options - Validation options including optional expected skill name.
+ * @returns List of validation error messages. Empty list means valid.
+ * @example
+ * ```ts
+ * const errors = validateSkillProperties({
+ *   name: "demo-skill",
+ *   description: "Demo skill"
+ * })
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/validator.py
+ *
+ * Spec: https://agentskills.io/specification
+ */
+declare function validateSkillProperties(properties: SkillProperties, options?: ValidateSkillPropertiesOptions): string[];
+/**
+ * Validate complete SKILL.md content.
+ *
+ * Parses the content and validates the resulting properties.
+ *
+ * @param content - Raw SKILL.md content
+ * @returns List of validation error messages. Empty list means valid.
+ * @example
+ * ```ts
+ * const errors = validateSkillContent(`---
+ * name: demo
+ * description: Demo skill
+ * ---
+ * # Body`)
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/validator.py
+ *
+ * Spec: https://agentskills.io/specification
+ */
+declare function validateSkillContent(content: SkillContent): string[];
+/**
+ * Host-provided context for validating in-memory skill entries.
+ *
+ * @example
+ * ```ts
+ * const options: SkillValidationOptions = {
+ *   location: "/skills/demo",
+ *   expectedName: "demo",
+ *   exists: true,
+ *   isDirectory: true
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/validator.py
+ */
+interface SkillValidationOptions {
+  /** Optional location label included in error messages. */
+  location?: string;
+  /** Expected skill name (for example, directory or slug match). */
+  expectedName?: ValidateSkillPropertiesOptions['expectedName'];
+  /** Whether the host path exists. */
+  exists?: boolean;
+  /** Whether the host path is a directory. */
+  isDirectory?: boolean;
+}
+/**
+ * Validates a skill represented as an in-memory file list.
+ * The host can map filesystem concepts (exists, isDirectory, name) into options.
+ *
+ * @param entries - In-memory file entries for one skill directory.
+ * @param options - Host context for path state and expected name checks.
+ * @returns List of validation errors. Empty list means valid.
+ * @example
+ * ```ts
+ * const errors = validateSkillEntries(
+ *   [{ name: "SKILL.md", content: "---\nname: demo\ndescription: Demo\n---" }],
+ *   { expectedName: "demo" }
+ * )
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/validator.py
+ */
+declare function validateSkillEntries(entries: Iterable<SkillContentEntry> | null | undefined, options?: SkillValidationOptions): string[];
+//#endregion
+//#region src/patch.d.ts
+/**
+ * Supported patch operation types.
+ *
+ * @example
+ * ```ts
+ * const type: SkillPatchOperationType = "replace"
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillPatchOperationType = 'replace' | 'insert' | 'delete';
+/**
+ * Replace operation that swaps matched text with new text.
+ *
+ * @example
+ * ```ts
+ * const op: SkillPatchReplaceOperation = {
+ *   type: "replace",
+ *   before: "old",
+ *   after: "new"
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillPatchReplaceOperation {
+  type: 'replace';
+  before: string;
+  after: string;
+  expectedMatches?: number;
+}
+/**
+ * Insert operation that adds text before or after an anchor.
+ *
+ * @example
+ * ```ts
+ * const op: SkillPatchInsertOperation = {
+ *   type: "insert",
+ *   anchor: "## Section",
+ *   text: "\nNew line",
+ *   position: "after"
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillPatchInsertOperation {
+  type: 'insert';
+  anchor: string;
+  text: string;
+  position?: 'before' | 'after';
+  expectedMatches?: number;
+}
+/**
+ * Delete operation that removes occurrences of target text.
+ *
+ * @example
+ * ```ts
+ * const op: SkillPatchDeleteOperation = { type: "delete", before: "obsolete" }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillPatchDeleteOperation {
+  type: 'delete';
+  before: string;
+  expectedMatches?: number;
+}
+/**
+ * Union of all supported patch operations.
+ *
+ * @example
+ * ```ts
+ * const op: SkillPatchOperation = { type: "delete", before: "obsolete" }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillPatchOperation = SkillPatchReplaceOperation | SkillPatchInsertOperation | SkillPatchDeleteOperation;
+/**
+ * Top-level patch payload accepted by `applySkillPatch`.
+ *
+ * @example
+ * ```ts
+ * const patch: SkillPatch = { version: 1, operations: [] }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillPatch {
+  version: 1;
+  operations: SkillPatchOperation[];
+}
+/**
+ * Machine-readable issue codes emitted by patch validation/application.
+ *
+ * @example
+ * ```ts
+ * const code: SkillPatchIssueCode = "OPERATION_TARGET_NOT_FOUND"
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillPatchIssueCode = 'PATCH_NOT_OBJECT' | 'PATCH_INVALID_VERSION' | 'PATCH_MISSING_OPERATIONS' | 'OPERATION_INVALID' | 'OPERATION_TARGET_EMPTY' | 'OPERATION_INVALID_POSITION' | 'OPERATION_INVALID_EXPECTED_MATCHES' | 'OPERATION_TARGET_NOT_FOUND' | 'OPERATION_TARGET_AMBIGUOUS' | 'OPERATION_MATCH_COUNT_MISMATCH' | 'SKILL_INVALID';
+/**
+ * Structured issue detail for patch failures.
+ *
+ * @example
+ * ```ts
+ * const issue: SkillPatchIssue = {
+ *   code: "OPERATION_TARGET_NOT_FOUND",
+ *   message: "Target text not found."
+ * }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillPatchIssue {
+  code: SkillPatchIssueCode;
+  message: string;
+  operationIndex?: number;
+  operationType?: SkillPatchOperationType;
+  field?: string;
+  matchCount?: number;
+  expectedMatches?: number;
+  snippet?: string;
+}
+/**
+ * Result returned by `validateSkillPatch`.
+ *
+ * @example
+ * ```ts
+ * const result: SkillPatchValidationResult = validateSkillPatch(candidate)
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillPatchValidationResult {
+  ok: boolean;
+  patch?: SkillPatch;
+  errors?: SkillPatchIssue[];
+}
+/**
+ * Options for patch application behavior.
+ *
+ * @example
+ * ```ts
+ * const options: SkillPatchApplyOptions = { expectedMatches: 1, validate: true }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillPatchApplyOptions {
+  expectedMatches?: number;
+  validate?: boolean | ValidateSkillPropertiesOptions;
+}
+/**
+ * Result returned by `applySkillPatch`.
+ *
+ * @example
+ * ```ts
+ * const result: SkillPatchApplyResult = applySkillPatch(content, patch)
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillPatchApplyResult {
+  ok: boolean;
+  content?: SkillContent;
+  errors?: SkillPatchIssue[];
+  appliedOperations?: number;
+}
+/**
+ * Options for `createSkillPatch`.
+ *
+ * @example
+ * ```ts
+ * const options: SkillPatchCreateOptions = { contextLines: 2 }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillPatchCreateOptions {
+  contextLines?: number;
+}
+/**
+ * Diff segment type.
+ *
+ * @example
+ * ```ts
+ * const type: SkillDiffSegmentType = "insert"
+ * ```
+ * @see https://agentskills.io/specification
+ */
+type SkillDiffSegmentType = 'equal' | 'insert' | 'delete';
+/**
+ * Consecutive lines sharing the same diff operation type.
+ *
+ * @example
+ * ```ts
+ * const segment: SkillDiffSegment = { type: "equal", lines: ["line"] }
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillDiffSegment {
+  type: SkillDiffSegmentType;
+  lines: string[];
+}
+/**
+ * Line-oriented diff output.
+ *
+ * @example
+ * ```ts
+ * const diff: SkillLineDiff = diffSkillContent("a", "b")
+ * ```
+ * @see https://agentskills.io/specification
+ */
+interface SkillLineDiff {
+  baseLineCount: number;
+  updatedLineCount: number;
+  segments: SkillDiffSegment[];
+}
+/**
+ * Validates and normalizes a candidate patch payload.
+ *
+ * @param patch - Unknown candidate patch object.
+ * @returns Normalized patch when valid, otherwise structured issues.
+ * @example
+ * ```ts
+ * const result = validateSkillPatch({
+ *   version: 1,
+ *   operations: [{ type: "replace", before: "old", after: "new" }]
+ * })
+ * ```
+ * @see https://agentskills.io/specification
+ */
+declare function validateSkillPatch(patch: unknown): SkillPatchValidationResult;
+/**
+ * Applies a patch to SKILL.md content with optional post-validation.
+ *
+ * @param content - Existing SKILL.md content.
+ * @param patch - Candidate patch payload (typed or untyped).
+ * @param options - Apply options for validation and expected match counts.
+ * @returns Structured apply result with updated content or issues.
+ * @example
+ * ```ts
+ * const result = applySkillPatch(content, {
+ *   version: 1,
+ *   operations: [{ type: "replace", before: "old", after: "new" }]
+ * })
+ * ```
+ * @see https://agentskills.io/specification
+ */
+declare function applySkillPatch(content: SkillContent, patch: unknown, options?: SkillPatchApplyOptions): SkillPatchApplyResult;
+/**
+ * Computes a line-based diff between two SKILL.md contents.
+ *
+ * @param base - Original SKILL.md content.
+ * @param updated - Updated SKILL.md content.
+ * @returns Grouped line diff segments.
+ * @example
+ * ```ts
+ * const diff = diffSkillContent(baseContent, updatedContent)
+ * ```
+ * @see https://agentskills.io/specification
+ */
+declare function diffSkillContent(base: SkillContent, updated: SkillContent): SkillLineDiff;
+/**
+ * Creates a contextual replace patch from base and updated content.
+ *
+ * @param base - Original SKILL.md content.
+ * @param updated - Updated SKILL.md content.
+ * @param options - Patch generation options.
+ * @returns Patch payload containing replace operations.
+ * @example
+ * ```ts
+ * const patch = createSkillPatch(baseContent, updatedContent, { contextLines: 2 })
+ * ```
+ * @see https://agentskills.io/specification
+ */
+declare function createSkillPatch(base: SkillContent, updated: SkillContent, options?: SkillPatchCreateOptions): SkillPatch;
+//#endregion
+//#region src/prompt.d.ts
+/**
+ * Prompt-ready skill metadata.
+ *
+ * This shape is storage-agnostic and works for both filesystem hosts
+ * (with `location`) and tool-only hosts (without `location`).
+ *
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/prompt.py
+ */
+interface SkillPromptEntry extends Pick<ResolvedSkill, 'name' | 'description' | 'location'> {}
+/**
+ * SKILL.md source data for prompt generation.
+ *
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/prompt.py
+ */
+interface SkillPromptSource {
+  /** Raw SKILL.md content to parse for prompt metadata. */
+  content: SkillContent;
+  /** Optional source location label for prompt output. */
+  location?: SkillPromptEntry['location'];
+}
+/**
+ * Prompt entry for resource-aware progressive disclosure hosts.
+ */
+interface DisclosurePromptEntry extends SkillPromptEntry {
+  /** Optional tier-3 resource names exposed as prompt hints. */
+  resources?: Array<SkillResource['name']>;
+}
+/**
+ * Options for disclosure protocol instruction text generation.
+ */
+interface DisclosureInstructionOptions {
+  /** Tool name override used in generated instruction text. */
+  toolName?: string;
+}
+/**
+ * Generates the `<available_skills>` XML block for system prompts.
+ *
+ * The base output mirrors the reference XML shape and omits host-specific
+ * protocol instructions.
+ *
+ * @param entries - Prompt entries or raw SKILL.md sources.
+ * @returns XML block describing available skills.
+ */
+declare function toPrompt(entries: SkillPromptEntry[]): string;
+declare function toPrompt(entries: SkillPromptSource[]): string;
+/**
+ * Generates `<available_skills>` XML including optional tier-3 resource hints.
+ *
+ * This is a host extension for progressive disclosure workflows and does not
+ * replace the base `toPrompt` output contract.
+ *
+ * @param entries - Prompt entries with optional resource names.
+ * @returns XML block describing skills and available resources.
+ */
+declare function toDisclosurePrompt(entries: DisclosurePromptEntry[]): string;
+/**
+ * Generates canonical system-instruction text for progressive disclosure reads.
+ *
+ * @param options - Optional tool naming override.
+ * @returns Multi-line guidance text for model system prompts.
+ */
+declare function toDisclosureInstructions(options?: DisclosureInstructionOptions): string;
+//#endregion
+//#region src/utils/token-estimator.d.ts
+/**
+ * Token estimation utilities
+ *
+ * Provides rough token count estimates for context management.
+ */
+/**
+ * Estimate token count for text.
+ * Uses rough approximation: ~1 token per 4 characters.
+ *
+ * This is intentionally simple and conservative. For production,
+ * consider using a proper tokenizer like tiktoken or @anthropic-ai/tokenizer.
+ *
+ * The 4-character heuristic tends to overestimate slightly, which is safer
+ * for context limits than underestimating.
+ *
+ * @param text - Text to estimate tokens for
+ * @returns Estimated token count
+ * @example
+ * ```ts
+ * const tokens = estimateTokens("Hello world")
+ * ```
+ * @see https://agentskills.io/specification
+ */
+declare function estimateTokens(text: string): number;
+//#endregion
+//#region src/utils/unicode.d.ts
+/**
+ * Unicode utilities for Agent Skills
+ *
+ * Reference: https://agentskills.io/specification
+ * Reference Implementation: https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/validator.py
+ */
+/**
+ * Normalize string using NFKC (Normalization Form Compatibility Composition).
+ * Matches Python's unicodedata.normalize("NFKC", str) behavior.
+ *
+ * NFKC normalization:
+ * - Decomposes characters into their base form
+ * - Then recomposes them into the composed form
+ * - Example: "café" with combining accent becomes "café" with precomposed é
+ *
+ * This is critical for i18n support and consistent validation across platforms.
+ *
+ * @param str - Input string to normalize.
+ * @returns NFKC-normalized string.
+ * @example
+ * ```ts
+ * const normalized = normalizeNFKC("cafe\u0301")
+ * ```
+ * @see https://agentskills.io/specification
+ * @see https://github.com/agentskills/agentskills/blob/main/skills-ref/src/skills_ref/validator.py
+ */
+declare function normalizeNFKC(str: string): string;
+//#endregion
+export { ALLOWED_FIELDS, type ByteCount, type DisclosureInstructionOptions, type DisclosurePromptEntry, MAX_COMPATIBILITY_LENGTH, MAX_DESCRIPTION_LENGTH, MAX_SKILL_NAME_LENGTH, ParseError, type ParseFrontmatterInputMode, type ParseFrontmatterOptions, type ReadSkillPropertiesOptions, type ReadToolSchema, type ReadToolSchemaOptions, type ResolvedSkill, type ResourceLink, SKILL_FRONTMATTER_KEYS, type SkillAllowedTools, type SkillBody, type SkillContent, type SkillContentEntry, type SkillDiffSegment, type SkillDiffSegmentType, type SkillFile, type SkillFrontmatter, type SkillFrontmatterKey, type SkillFrontmatterParseResult, type SkillId, type SkillLineDiff, type SkillMetadata, type SkillMetadataMap, type SkillParseResult, type SkillPatch, type SkillPatchApplyOptions, type SkillPatchApplyResult, type SkillPatchCreateOptions, type SkillPatchIssue, type SkillPatchIssueCode, type SkillPatchOperation, type SkillPatchOperationType, type SkillPatchValidationResult, type SkillPromptEntry, type SkillPromptSource, type SkillProperties, type SkillReadArgs, type SkillReadError, type SkillReadErrorCode, type SkillReadResult, type SkillResource, type SkillTokenCount, type SkillValidationOptions, type UnixMillis, type ValidateSkillPropertiesOptions, ValidationError, applySkillPatch, createSkillPatch, diffSkillContent, estimateTokens, extractBody, extractResourceLinks, findSkillMdFile, frontmatterToProperties, handleSkillRead, normalizeNFKC, parseFrontmatter, parseSkillContent, readSkillProperties, skillPropertiesToDict, toDisclosureInstructions, toDisclosurePrompt, toPrompt, toReadToolSchema, validateSkillContent, validateSkillEntries, validateSkillPatch, validateSkillProperties };
+//# sourceMappingURL=index.d.ts.map