@agentforge/skills 0.16.61 → 0.16.63

package/dist/index.d.cts

@@ -0,0 +1,460 @@
+import { Tool } from '@agentforge/core';
+import { z } from 'zod';
+
+/**
+ * Skill System Types
+ *
+ * Core type definitions for the AgentForge Agent Skills system.
+ * These types align with the Agent Skills specification (https://agentskills.io/specification).
+ */
+/**
+ * Trust level for a skill root directory.
+ *
+ * - `workspace` — Skills from the project workspace (highest trust, scripts allowed)
+ * - `trusted`   — Explicitly trusted skill roots (scripts allowed)
+ * - `untrusted` — Untrusted roots like community packs (scripts blocked by default)
+ */
+type TrustLevel = 'workspace' | 'trusted' | 'untrusted';
+/**
+ * Configuration for a skill root with an explicit trust level.
+ *
+ * @example
+ * ```ts
+ * const roots: SkillRootConfig[] = [
+ *   { path: '.agentskills', trust: 'workspace' },
+ *   { path: '~/.agentskills', trust: 'trusted' },
+ *   { path: '/shared/community-skills', trust: 'untrusted' },
+ * ];
+ * ```
+ */
+interface SkillRootConfig {
+    /** Directory path to scan for skills */
+    path: string;
+    /** Trust level assigned to all skills discovered from this root */
+    trust: TrustLevel;
+}
+/**
+ * Policy decision returned by trust enforcement checks.
+ */
+interface TrustPolicyDecision {
+    /** Whether the action is allowed */
+    allowed: boolean;
+    /** Machine-readable reason code for auditing */
+    reason: TrustPolicyReason;
+    /** Human-readable explanation */
+    message: string;
+}
+/**
+ * Reason codes for trust policy decisions.
+ *
+ * Used for structured logging and auditing of guardrail behavior.
+ */
+declare enum TrustPolicyReason {
+    /** Resource is not a script — no trust check needed */
+    NOT_SCRIPT = "not-script",
+    /** Skill root has workspace trust — scripts allowed */
+    WORKSPACE_TRUST = "workspace-trust",
+    /** Skill root has explicit trusted status — scripts allowed */
+    TRUSTED_ROOT = "trusted-root",
+    /** Skill root is untrusted — scripts denied by default */
+    UNTRUSTED_SCRIPT_DENIED = "untrusted-script-denied",
+    /** Untrusted script access was explicitly allowed via config override */
+    UNTRUSTED_SCRIPT_ALLOWED = "untrusted-script-allowed-override",
+    /** Trust level is unknown — treated as untrusted for security */
+    UNKNOWN_TRUST_LEVEL = "unknown-trust-level"
+}
+/**
+ * Parsed metadata from a SKILL.md frontmatter block.
+ *
+ * Required fields: `name`, `description`.
+ * All other fields are optional per the Agent Skills spec.
+ */
+interface SkillMetadata {
+    /** Skill name (1-64 chars, lowercase alphanumeric + hyphens, must match parent dir name) */
+    name: string;
+    /** Human-readable description (1-1024 chars) */
+    description: string;
+    /** SPDX license identifier */
+    license?: string;
+    /** List of compatible agent frameworks / tool hosts */
+    compatibility?: string[];
+    /** Arbitrary key-value metadata (author, version, etc.) */
+    metadata?: Record<string, unknown>;
+    /** Tools that this skill is allowed to use */
+    allowedTools?: string[];
+}
+/**
+ * A fully resolved skill entry in the registry.
+ *
+ * Contains parsed metadata plus internal tracking fields
+ * that are not part of the SKILL.md frontmatter.
+ */
+interface Skill {
+    /** Parsed frontmatter metadata */
+    metadata: SkillMetadata;
+    /** Absolute path to the skill directory */
+    skillPath: string;
+    /** Which configured skill root this was discovered from */
+    rootPath: string;
+    /** Trust level assigned to this skill (inherited from root config) */
+    trustLevel: TrustLevel;
+}
+/**
+ * Configuration for the SkillRegistry.
+ */
+interface SkillRegistryConfig {
+    /**
+     * Array of directory paths to scan for skills.
+     *
+     * Each entry can be a plain string (defaults to `'untrusted'` trust level)
+     * or a `SkillRootConfig` object with an explicit trust level.
+     *
+     * Paths may be absolute or relative (resolved against `cwd`).
+     * The `~` prefix is expanded to `$HOME`.
+     *
+     * @example
+     * ```ts
+     * // Simple string roots (default to 'untrusted')
+     * skillRoots: ['.agentskills', '~/.agentskills']
+     *
+     * // Trust-aware roots
+     * skillRoots: [
+     *   { path: '.agentskills', trust: 'workspace' },
+     *   { path: '~/.agentskills', trust: 'trusted' },
+     *   { path: '/shared/community', trust: 'untrusted' },
+     * ]
+     * ```
+     */
+    skillRoots: Array<string | SkillRootConfig>;
+    /**
+     * Feature flag to enable Agent Skills in system prompts.
+     *
+     * When `false` (default), `generatePrompt()` returns an empty string
+     * so agents operate with unmodified system prompts.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of skills to include in generated prompts.
+     *
+     * Caps prompt token usage when many skills are discovered.
+     * Skills are included in discovery order (first root first).
+     * When undefined, all discovered skills are included.
+     */
+    maxDiscoveredSkills?: number;
+    /**
+     * Allow script resources from untrusted roots.
+     *
+     * When `true`, scripts from `scripts/` directories in untrusted
+     * skill roots are returned instead of being denied. This disables
+     * the default-deny policy for untrusted scripts.
+     *
+     * **Security warning:** Only enable when you have reviewed all
+     * skill packs from untrusted roots.
+     *
+     * @default false
+     */
+    allowUntrustedScripts?: boolean;
+}
+/**
+ * Options for `SkillRegistry.generatePrompt()`.
+ */
+interface SkillPromptOptions {
+    /**
+     * Subset of skill names to include in the generated prompt.
+     *
+     * When provided, only skills matching these names appear in the
+     * `<available_skills>` XML block. This enables creating focused
+     * agents with different skill sets from the same registry.
+     *
+     * When omitted or empty, all discovered skills are included.
+     *
+     * @example ['code-review', 'testing-strategy']
+     */
+    skills?: string[];
+}
+/**
+ * Events emitted by the SkillRegistry during discovery and usage.
+ */
+declare enum SkillRegistryEvent {
+    /** Emitted when a valid skill is discovered during scanning */
+    SKILL_DISCOVERED = "skill:discovered",
+    /** Emitted when a skill parse or validation issue is encountered */
+    SKILL_WARNING = "skill:warning",
+    /** Emitted when a skill is activated (full body loaded) */
+    SKILL_ACTIVATED = "skill:activated",
+    /** Emitted when a skill resource file is loaded */
+    SKILL_RESOURCE_LOADED = "skill:resource-loaded",
+    /** Emitted when a trust policy denies access to a resource */
+    TRUST_POLICY_DENIED = "trust:policy-denied",
+    /** Emitted when a trust policy allows access (for auditing) */
+    TRUST_POLICY_ALLOWED = "trust:policy-allowed"
+}
+/**
+ * Event handler type for skill registry events.
+ */
+type SkillEventHandler = (data: unknown) => void;
+/**
+ * Result of parsing a single SKILL.md file.
+ */
+interface SkillParseResult {
+    /** Whether parsing and validation succeeded */
+    success: boolean;
+    /** Parsed metadata (present when success is true) */
+    metadata?: SkillMetadata;
+    /** The raw markdown body below the frontmatter (present when success is true) */
+    body?: string;
+    /** Error description (present when success is false) */
+    error?: string;
+}
+/**
+ * Validation error detail.
+ */
+interface SkillValidationError {
+    /** Which field failed validation */
+    field: string;
+    /** Human-readable error message */
+    message: string;
+}
+
+/**
+ * SKILL.md Frontmatter Parser
+ *
+ * Parses YAML frontmatter from SKILL.md files and validates
+ * against the Agent Skills specification constraints.
+ *
+ * @see https://agentskills.io/specification
+ */
+
+/**
+ * Validate the `name` field per the Agent Skills spec.
+ *
+ * @param name - The name value from frontmatter
+ * @returns Array of validation errors (empty = valid)
+ */
+declare function validateSkillName(name: unknown): SkillValidationError[];
+/**
+ * Validate the `description` field per the Agent Skills spec.
+ *
+ * @param description - The description value from frontmatter
+ * @returns Array of validation errors (empty = valid)
+ */
+declare function validateSkillDescription(description: unknown): SkillValidationError[];
+/**
+ * Validate that the skill name matches its parent directory name (per spec).
+ *
+ * @param name - The name from frontmatter
+ * @param dirName - The parent directory name
+ * @returns Array of validation errors (empty = valid)
+ */
+declare function validateSkillNameMatchesDir(name: string, dirName: string): SkillValidationError[];
+/**
+ * Parse and validate a SKILL.md file's raw content.
+ *
+ * Extracts YAML frontmatter using gray-matter, then validates
+ * required and optional fields against spec constraints.
+ *
+ * @param content - Raw file content of the SKILL.md
+ * @param dirName - Parent directory name for name-match validation
+ * @returns Parse result with metadata or error
+ */
+declare function parseSkillContent(content: string, dirName: string): SkillParseResult;
+
+/**
+ * Skill Directory Scanner
+ *
+ * Scans configured skill roots for directories containing valid SKILL.md files.
+ * Returns a list of candidate skill paths for the parser to process.
+ */
+/**
+ * Discovered skill candidate — a directory containing a SKILL.md file.
+ */
+interface SkillCandidate {
+    /** Absolute path to the skill directory */
+    skillPath: string;
+    /** The parent directory name (expected to match the skill name) */
+    dirName: string;
+    /** Raw content of the SKILL.md file */
+    content: string;
+    /** Which configured root this came from */
+    rootPath: string;
+}
+/**
+ * Expand `~` prefix to the user's home directory.
+ */
+declare function expandHome(p: string): string;
+/**
+ * Scan a single skill root for directories containing SKILL.md.
+ *
+ * @param rootPath - The root directory to scan (may not exist)
+ * @returns Array of valid skill candidates found under this root
+ */
+declare function scanSkillRoot(rootPath: string): SkillCandidate[];
+/**
+ * Scan multiple skill roots for directories containing SKILL.md.
+ *
+ * @param skillRoots - Array of root paths to scan
+ * @returns Array of all skill candidates found across all roots
+ */
+declare function scanAllSkillRoots(skillRoots: string[]): SkillCandidate[];
+
+declare const activateSkillSchema: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+declare const readSkillResourceSchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    path: string;
+}, {
+    name: string;
+    path: string;
+}>;
+
+/**
+ * Create the `activate-skill` tool bound to a registry instance.
+ *
+ * Resolves the skill by name, reads the full SKILL.md file, and returns
+ * the body content (below frontmatter).
+ *
+ * @param registry - The SkillRegistry to resolve skills from
+ * @returns An AgentForge Tool
+ */
+declare function createActivateSkillTool(registry: SkillRegistry): Tool<z.infer<typeof activateSkillSchema>, string>;
+
+/**
+ * Resolve a resource path within a skill root, blocking path traversal.
+ *
+ * @param skillPath - Absolute path to the skill directory
+ * @param resourcePath - Relative path to the resource file
+ * @returns Absolute path to the resource, or an error string
+ */
+declare function resolveResourcePath(skillPath: string, resourcePath: string): {
+    success: true;
+    resolvedPath: string;
+} | {
+    success: false;
+    error: string;
+};
+
+/**
+ * Create the `read-skill-resource` tool bound to a registry instance.
+ *
+ * Resolves the skill by name, validates the resource path (blocking
+ * traversal), and returns the file content.
+ *
+ * @param registry - The SkillRegistry to resolve skills from
+ * @returns An AgentForge Tool
+ */
+declare function createReadSkillResourceTool(registry: SkillRegistry): Tool<z.infer<typeof readSkillResourceSchema>, string>;
+
+/**
+ * Skill Activation Tools
+ *
+ * Provides `activate-skill` and `read-skill-resource` tools built with
+ * the AgentForge tool builder API. These tools enable agents to load
+ * skill instructions on demand and access skill resources at runtime.
+ *
+ * @see https://agentskills.io/specification
+ *
+ * @example
+ * ```ts
+ * const [activateSkill, readSkillResource] = createSkillActivationTools(registry);
+ * // activateSkill       — load full SKILL.md body
+ * // readSkillResource   — load a resource file from a skill
+ *
+ * // Or use the convenience method:
+ * const [activateSkill, readSkillResource] = registry.toActivationTools();
+ * ```
+ */
+
+/**
+ * Create both skill activation tools bound to a registry instance.
+ *
+ * @param registry - The SkillRegistry to bind tools to
+ * @returns Array of both tools [activate-skill, read-skill-resource]
+ */
+declare function createSkillActivationTools(registry: SkillRegistry): [Tool<z.infer<typeof activateSkillSchema>, string>, Tool<z.infer<typeof readSkillResourceSchema>, string>];
+
+declare class SkillRegistry {
+    private skills;
+    private eventHandlers;
+    private readonly config;
+    private scanErrors;
+    private rootTrustMap;
+    constructor(config: SkillRegistryConfig);
+    discover(): void;
+    get(name: string): Skill | undefined;
+    getAll(): Skill[];
+    has(name: string): boolean;
+    size(): number;
+    getNames(): string[];
+    getScanErrors(): ReadonlyArray<{
+        path: string;
+        error: string;
+    }>;
+    getAllowUntrustedScripts(): boolean;
+    getAllowedTools(name: string): string[] | undefined;
+    generatePrompt(options?: SkillPromptOptions): string;
+    on(event: SkillRegistryEvent, handler: SkillEventHandler): void;
+    off(event: SkillRegistryEvent, handler: SkillEventHandler): void;
+    emitEvent(event: SkillRegistryEvent, data: unknown): void;
+    toActivationTools(): ReturnType<typeof createSkillActivationTools>;
+    private emit;
+}
+
+/**
+ * Skill Trust Policy Engine
+ *
+ * Enforces trust-level-based access control for skill resources.
+ * Scripts from untrusted roots are denied by default unless explicitly allowed.
+ *
+ * Trust levels:
+ * - `workspace` — Project-local skills, highest trust. Scripts always allowed.
+ * - `trusted`   — Explicitly trusted roots. Scripts allowed.
+ * - `untrusted` — Community or third-party skills. Scripts denied by default.
+ *
+ * @see https://agentskills.io/specification
+ */
+
+/**
+ * Normalize a skill root config entry.
+ *
+ * String entries default to `'untrusted'` trust level for safe defaults.
+ *
+ * @param root - A string path or SkillRootConfig object
+ * @returns Normalized SkillRootConfig with explicit trust level
+ */
+declare function normalizeRootConfig(root: string | SkillRootConfig): SkillRootConfig;
+/**
+ * Check whether a resource path refers to a script.
+ *
+ * A resource is considered a script if its relative path starts with
+ * `scripts/` or is exactly `scripts`, after normalizing path separators,
+ * stripping leading "./" segments, and ignoring case.
+ *
+ * @param resourcePath - Relative path within the skill directory
+ * @returns True if the resource is in the scripts/ directory
+ */
+declare function isScriptResource(resourcePath: string): boolean;
+/**
+ * Evaluate the trust policy for a resource access request.
+ *
+ * Non-script resources are always allowed regardless of trust level.
+ * Script resources require `workspace` or `trusted` trust, or the
+ * `allowUntrustedScripts` override to be enabled.
+ *
+ * @param resourcePath - Relative path to the resource within the skill directory
+ * @param trustLevel - Trust level of the skill's root directory
+ * @param allowUntrustedScripts - Override flag to permit untrusted scripts
+ * @returns Policy decision with allow/deny, reason code, and message
+ */
+declare function evaluateTrustPolicy(resourcePath: string, trustLevel: TrustLevel, allowUntrustedScripts?: boolean): TrustPolicyDecision;
+
+export { type Skill, type SkillCandidate, type SkillEventHandler, type SkillMetadata, type SkillParseResult, type SkillPromptOptions, SkillRegistry, type SkillRegistryConfig, SkillRegistryEvent, type SkillRootConfig, type SkillValidationError, type TrustLevel, type TrustPolicyDecision, TrustPolicyReason, createActivateSkillTool, createReadSkillResourceTool, createSkillActivationTools, evaluateTrustPolicy, expandHome, isScriptResource, normalizeRootConfig, parseSkillContent, resolveResourcePath, scanAllSkillRoots, scanSkillRoot, validateSkillDescription, validateSkillName, validateSkillNameMatchesDir };

package/dist/index.d.ts

@@ -0,0 +1,460 @@
+import { Tool } from '@agentforge/core';
+import { z } from 'zod';
+
+/**
+ * Skill System Types
+ *
+ * Core type definitions for the AgentForge Agent Skills system.
+ * These types align with the Agent Skills specification (https://agentskills.io/specification).
+ */
+/**
+ * Trust level for a skill root directory.
+ *
+ * - `workspace` — Skills from the project workspace (highest trust, scripts allowed)
+ * - `trusted`   — Explicitly trusted skill roots (scripts allowed)
+ * - `untrusted` — Untrusted roots like community packs (scripts blocked by default)
+ */
+type TrustLevel = 'workspace' | 'trusted' | 'untrusted';
+/**
+ * Configuration for a skill root with an explicit trust level.
+ *
+ * @example
+ * ```ts
+ * const roots: SkillRootConfig[] = [
+ *   { path: '.agentskills', trust: 'workspace' },
+ *   { path: '~/.agentskills', trust: 'trusted' },
+ *   { path: '/shared/community-skills', trust: 'untrusted' },
+ * ];
+ * ```
+ */
+interface SkillRootConfig {
+    /** Directory path to scan for skills */
+    path: string;
+    /** Trust level assigned to all skills discovered from this root */
+    trust: TrustLevel;
+}
+/**
+ * Policy decision returned by trust enforcement checks.
+ */
+interface TrustPolicyDecision {
+    /** Whether the action is allowed */
+    allowed: boolean;
+    /** Machine-readable reason code for auditing */
+    reason: TrustPolicyReason;
+    /** Human-readable explanation */
+    message: string;
+}
+/**
+ * Reason codes for trust policy decisions.
+ *
+ * Used for structured logging and auditing of guardrail behavior.
+ */
+declare enum TrustPolicyReason {
+    /** Resource is not a script — no trust check needed */
+    NOT_SCRIPT = "not-script",
+    /** Skill root has workspace trust — scripts allowed */
+    WORKSPACE_TRUST = "workspace-trust",
+    /** Skill root has explicit trusted status — scripts allowed */
+    TRUSTED_ROOT = "trusted-root",
+    /** Skill root is untrusted — scripts denied by default */
+    UNTRUSTED_SCRIPT_DENIED = "untrusted-script-denied",
+    /** Untrusted script access was explicitly allowed via config override */
+    UNTRUSTED_SCRIPT_ALLOWED = "untrusted-script-allowed-override",
+    /** Trust level is unknown — treated as untrusted for security */
+    UNKNOWN_TRUST_LEVEL = "unknown-trust-level"
+}
+/**
+ * Parsed metadata from a SKILL.md frontmatter block.
+ *
+ * Required fields: `name`, `description`.
+ * All other fields are optional per the Agent Skills spec.
+ */
+interface SkillMetadata {
+    /** Skill name (1-64 chars, lowercase alphanumeric + hyphens, must match parent dir name) */
+    name: string;
+    /** Human-readable description (1-1024 chars) */
+    description: string;
+    /** SPDX license identifier */
+    license?: string;
+    /** List of compatible agent frameworks / tool hosts */
+    compatibility?: string[];
+    /** Arbitrary key-value metadata (author, version, etc.) */
+    metadata?: Record<string, unknown>;
+    /** Tools that this skill is allowed to use */
+    allowedTools?: string[];
+}
+/**
+ * A fully resolved skill entry in the registry.
+ *
+ * Contains parsed metadata plus internal tracking fields
+ * that are not part of the SKILL.md frontmatter.
+ */
+interface Skill {
+    /** Parsed frontmatter metadata */
+    metadata: SkillMetadata;
+    /** Absolute path to the skill directory */
+    skillPath: string;
+    /** Which configured skill root this was discovered from */
+    rootPath: string;
+    /** Trust level assigned to this skill (inherited from root config) */
+    trustLevel: TrustLevel;
+}
+/**
+ * Configuration for the SkillRegistry.
+ */
+interface SkillRegistryConfig {
+    /**
+     * Array of directory paths to scan for skills.
+     *
+     * Each entry can be a plain string (defaults to `'untrusted'` trust level)
+     * or a `SkillRootConfig` object with an explicit trust level.
+     *
+     * Paths may be absolute or relative (resolved against `cwd`).
+     * The `~` prefix is expanded to `$HOME`.
+     *
+     * @example
+     * ```ts
+     * // Simple string roots (default to 'untrusted')
+     * skillRoots: ['.agentskills', '~/.agentskills']
+     *
+     * // Trust-aware roots
+     * skillRoots: [
+     *   { path: '.agentskills', trust: 'workspace' },
+     *   { path: '~/.agentskills', trust: 'trusted' },
+     *   { path: '/shared/community', trust: 'untrusted' },
+     * ]
+     * ```
+     */
+    skillRoots: Array<string | SkillRootConfig>;
+    /**
+     * Feature flag to enable Agent Skills in system prompts.
+     *
+     * When `false` (default), `generatePrompt()` returns an empty string
+     * so agents operate with unmodified system prompts.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of skills to include in generated prompts.
+     *
+     * Caps prompt token usage when many skills are discovered.
+     * Skills are included in discovery order (first root first).
+     * When undefined, all discovered skills are included.
+     */
+    maxDiscoveredSkills?: number;
+    /**
+     * Allow script resources from untrusted roots.
+     *
+     * When `true`, scripts from `scripts/` directories in untrusted
+     * skill roots are returned instead of being denied. This disables
+     * the default-deny policy for untrusted scripts.
+     *
+     * **Security warning:** Only enable when you have reviewed all
+     * skill packs from untrusted roots.
+     *
+     * @default false
+     */
+    allowUntrustedScripts?: boolean;
+}
+/**
+ * Options for `SkillRegistry.generatePrompt()`.
+ */
+interface SkillPromptOptions {
+    /**
+     * Subset of skill names to include in the generated prompt.
+     *
+     * When provided, only skills matching these names appear in the
+     * `<available_skills>` XML block. This enables creating focused
+     * agents with different skill sets from the same registry.
+     *
+     * When omitted or empty, all discovered skills are included.
+     *
+     * @example ['code-review', 'testing-strategy']
+     */
+    skills?: string[];
+}
+/**
+ * Events emitted by the SkillRegistry during discovery and usage.
+ */
+declare enum SkillRegistryEvent {
+    /** Emitted when a valid skill is discovered during scanning */
+    SKILL_DISCOVERED = "skill:discovered",
+    /** Emitted when a skill parse or validation issue is encountered */
+    SKILL_WARNING = "skill:warning",
+    /** Emitted when a skill is activated (full body loaded) */
+    SKILL_ACTIVATED = "skill:activated",
+    /** Emitted when a skill resource file is loaded */
+    SKILL_RESOURCE_LOADED = "skill:resource-loaded",
+    /** Emitted when a trust policy denies access to a resource */
+    TRUST_POLICY_DENIED = "trust:policy-denied",
+    /** Emitted when a trust policy allows access (for auditing) */
+    TRUST_POLICY_ALLOWED = "trust:policy-allowed"
+}
+/**
+ * Event handler type for skill registry events.
+ */
+type SkillEventHandler = (data: unknown) => void;
+/**
+ * Result of parsing a single SKILL.md file.
+ */
+interface SkillParseResult {
+    /** Whether parsing and validation succeeded */
+    success: boolean;
+    /** Parsed metadata (present when success is true) */
+    metadata?: SkillMetadata;
+    /** The raw markdown body below the frontmatter (present when success is true) */
+    body?: string;
+    /** Error description (present when success is false) */
+    error?: string;
+}
+/**
+ * Validation error detail.
+ */
+interface SkillValidationError {
+    /** Which field failed validation */
+    field: string;
+    /** Human-readable error message */
+    message: string;
+}
+
+/**
+ * SKILL.md Frontmatter Parser
+ *
+ * Parses YAML frontmatter from SKILL.md files and validates
+ * against the Agent Skills specification constraints.
+ *
+ * @see https://agentskills.io/specification
+ */
+
+/**
+ * Validate the `name` field per the Agent Skills spec.
+ *
+ * @param name - The name value from frontmatter
+ * @returns Array of validation errors (empty = valid)
+ */
+declare function validateSkillName(name: unknown): SkillValidationError[];
+/**
+ * Validate the `description` field per the Agent Skills spec.
+ *
+ * @param description - The description value from frontmatter
+ * @returns Array of validation errors (empty = valid)
+ */
+declare function validateSkillDescription(description: unknown): SkillValidationError[];
+/**
+ * Validate that the skill name matches its parent directory name (per spec).
+ *
+ * @param name - The name from frontmatter
+ * @param dirName - The parent directory name
+ * @returns Array of validation errors (empty = valid)
+ */
+declare function validateSkillNameMatchesDir(name: string, dirName: string): SkillValidationError[];
+/**
+ * Parse and validate a SKILL.md file's raw content.
+ *
+ * Extracts YAML frontmatter using gray-matter, then validates
+ * required and optional fields against spec constraints.
+ *
+ * @param content - Raw file content of the SKILL.md
+ * @param dirName - Parent directory name for name-match validation
+ * @returns Parse result with metadata or error
+ */
+declare function parseSkillContent(content: string, dirName: string): SkillParseResult;
+
+/**
+ * Skill Directory Scanner
+ *
+ * Scans configured skill roots for directories containing valid SKILL.md files.
+ * Returns a list of candidate skill paths for the parser to process.
+ */
+/**
+ * Discovered skill candidate — a directory containing a SKILL.md file.
+ */
+interface SkillCandidate {
+    /** Absolute path to the skill directory */
+    skillPath: string;
+    /** The parent directory name (expected to match the skill name) */
+    dirName: string;
+    /** Raw content of the SKILL.md file */
+    content: string;
+    /** Which configured root this came from */
+    rootPath: string;
+}
+/**
+ * Expand `~` prefix to the user's home directory.
+ */
+declare function expandHome(p: string): string;
+/**
+ * Scan a single skill root for directories containing SKILL.md.
+ *
+ * @param rootPath - The root directory to scan (may not exist)
+ * @returns Array of valid skill candidates found under this root
+ */
+declare function scanSkillRoot(rootPath: string): SkillCandidate[];
+/**
+ * Scan multiple skill roots for directories containing SKILL.md.
+ *
+ * @param skillRoots - Array of root paths to scan
+ * @returns Array of all skill candidates found across all roots
+ */
+declare function scanAllSkillRoots(skillRoots: string[]): SkillCandidate[];
+
+declare const activateSkillSchema: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+declare const readSkillResourceSchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    path: string;
+}, {
+    name: string;
+    path: string;
+}>;
+
+/**
+ * Create the `activate-skill` tool bound to a registry instance.
+ *
+ * Resolves the skill by name, reads the full SKILL.md file, and returns
+ * the body content (below frontmatter).
+ *
+ * @param registry - The SkillRegistry to resolve skills from
+ * @returns An AgentForge Tool
+ */
+declare function createActivateSkillTool(registry: SkillRegistry): Tool<z.infer<typeof activateSkillSchema>, string>;
+
+/**
+ * Resolve a resource path within a skill root, blocking path traversal.
+ *
+ * @param skillPath - Absolute path to the skill directory
+ * @param resourcePath - Relative path to the resource file
+ * @returns Absolute path to the resource, or an error string
+ */
+declare function resolveResourcePath(skillPath: string, resourcePath: string): {
+    success: true;
+    resolvedPath: string;
+} | {
+    success: false;
+    error: string;
+};
+
+/**
+ * Create the `read-skill-resource` tool bound to a registry instance.
+ *
+ * Resolves the skill by name, validates the resource path (blocking
+ * traversal), and returns the file content.
+ *
+ * @param registry - The SkillRegistry to resolve skills from
+ * @returns An AgentForge Tool
+ */
+declare function createReadSkillResourceTool(registry: SkillRegistry): Tool<z.infer<typeof readSkillResourceSchema>, string>;
+
+/**
+ * Skill Activation Tools
+ *
+ * Provides `activate-skill` and `read-skill-resource` tools built with
+ * the AgentForge tool builder API. These tools enable agents to load
+ * skill instructions on demand and access skill resources at runtime.
+ *
+ * @see https://agentskills.io/specification
+ *
+ * @example
+ * ```ts
+ * const [activateSkill, readSkillResource] = createSkillActivationTools(registry);
+ * // activateSkill       — load full SKILL.md body
+ * // readSkillResource   — load a resource file from a skill
+ *
+ * // Or use the convenience method:
+ * const [activateSkill, readSkillResource] = registry.toActivationTools();
+ * ```
+ */
+
+/**
+ * Create both skill activation tools bound to a registry instance.
+ *
+ * @param registry - The SkillRegistry to bind tools to
+ * @returns Array of both tools [activate-skill, read-skill-resource]
+ */
+declare function createSkillActivationTools(registry: SkillRegistry): [Tool<z.infer<typeof activateSkillSchema>, string>, Tool<z.infer<typeof readSkillResourceSchema>, string>];
+
+declare class SkillRegistry {
+    private skills;
+    private eventHandlers;
+    private readonly config;
+    private scanErrors;
+    private rootTrustMap;
+    constructor(config: SkillRegistryConfig);
+    discover(): void;
+    get(name: string): Skill | undefined;
+    getAll(): Skill[];
+    has(name: string): boolean;
+    size(): number;
+    getNames(): string[];
+    getScanErrors(): ReadonlyArray<{
+        path: string;
+        error: string;
+    }>;
+    getAllowUntrustedScripts(): boolean;
+    getAllowedTools(name: string): string[] | undefined;
+    generatePrompt(options?: SkillPromptOptions): string;
+    on(event: SkillRegistryEvent, handler: SkillEventHandler): void;
+    off(event: SkillRegistryEvent, handler: SkillEventHandler): void;
+    emitEvent(event: SkillRegistryEvent, data: unknown): void;
+    toActivationTools(): ReturnType<typeof createSkillActivationTools>;
+    private emit;
+}
+
+/**
+ * Skill Trust Policy Engine
+ *
+ * Enforces trust-level-based access control for skill resources.
+ * Scripts from untrusted roots are denied by default unless explicitly allowed.
+ *
+ * Trust levels:
+ * - `workspace` — Project-local skills, highest trust. Scripts always allowed.
+ * - `trusted`   — Explicitly trusted roots. Scripts allowed.
+ * - `untrusted` — Community or third-party skills. Scripts denied by default.
+ *
+ * @see https://agentskills.io/specification
+ */
+
+/**
+ * Normalize a skill root config entry.
+ *
+ * String entries default to `'untrusted'` trust level for safe defaults.
+ *
+ * @param root - A string path or SkillRootConfig object
+ * @returns Normalized SkillRootConfig with explicit trust level
+ */
+declare function normalizeRootConfig(root: string | SkillRootConfig): SkillRootConfig;
+/**
+ * Check whether a resource path refers to a script.
+ *
+ * A resource is considered a script if its relative path starts with
+ * `scripts/` or is exactly `scripts`, after normalizing path separators,
+ * stripping leading "./" segments, and ignoring case.
+ *
+ * @param resourcePath - Relative path within the skill directory
+ * @returns True if the resource is in the scripts/ directory
+ */
+declare function isScriptResource(resourcePath: string): boolean;
+/**
+ * Evaluate the trust policy for a resource access request.
+ *
+ * Non-script resources are always allowed regardless of trust level.
+ * Script resources require `workspace` or `trusted` trust, or the
+ * `allowUntrustedScripts` override to be enabled.
+ *
+ * @param resourcePath - Relative path to the resource within the skill directory
+ * @param trustLevel - Trust level of the skill's root directory
+ * @param allowUntrustedScripts - Override flag to permit untrusted scripts
+ * @returns Policy decision with allow/deny, reason code, and message
+ */
+declare function evaluateTrustPolicy(resourcePath: string, trustLevel: TrustLevel, allowUntrustedScripts?: boolean): TrustPolicyDecision;
+
+export { type Skill, type SkillCandidate, type SkillEventHandler, type SkillMetadata, type SkillParseResult, type SkillPromptOptions, SkillRegistry, type SkillRegistryConfig, SkillRegistryEvent, type SkillRootConfig, type SkillValidationError, type TrustLevel, type TrustPolicyDecision, TrustPolicyReason, createActivateSkillTool, createReadSkillResourceTool, createSkillActivationTools, evaluateTrustPolicy, expandHome, isScriptResource, normalizeRootConfig, parseSkillContent, resolveResourcePath, scanAllSkillRoots, scanSkillRoot, validateSkillDescription, validateSkillName, validateSkillNameMatchesDir };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge/skills",
-  "version": "0.16.61",
+  "version": "0.16.63",
   "description": "Composable skill system for building modular TypeScript AI agents: author skills, register capabilities, and compose behaviors.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@agentforge/core": "0.16.61",
+    "@agentforge/core": "0.16.63",
     "gray-matter": "^4.0.3",
     "zod": "^3.24.1"
   },