@agentforge/skills 0.15.0

package/dist/index.d.ts

@@ -0,0 +1,682 @@
+import { z } from 'zod';
+import { Tool } from '@agentforge/core';
+
+/**
+ * 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[];
+
+/**
+ * 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();
+ * ```
+ */
+
+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;
+}>;
+/**
+ * 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 `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>;
+/**
+ * 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>;
+/**
+ * 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>];
+
+/**
+ * Skill Registry
+ *
+ * Central registry for discovering, storing, and querying Agent Skills.
+ * Mirrors ToolRegistry but uses folder-based auto-discovery instead
+ * of programmatic registration.
+ *
+ * @see https://agentskills.io/specification
+ *
+ * @example
+ * ```ts
+ * const registry = new SkillRegistry({
+ *   skillRoots: ['.agentskills', '~/.agentskills'],
+ * });
+ *
+ * // Query discovered skills
+ * const skill = registry.get('code-review');
+ * const allSkills = registry.getAll();
+ *
+ * // Listen for events
+ * registry.on(SkillRegistryEvent.SKILL_DISCOVERED, (skill) => {
+ *   console.log('Found skill:', skill.metadata.name);
+ * });
+ * ```
+ */
+
+/**
+ * Skill Registry — auto-discovers skills from configured folder paths.
+ *
+ * Parallel to ToolRegistry:
+ * | ToolRegistry             | SkillRegistry                            |
+ * |--------------------------|------------------------------------------|
+ * | registry.register(tool)  | new SkillRegistry({ skillRoots })        |
+ * | registry.get('name')     | skillRegistry.get('name')                |
+ * | registry.getAll()        | skillRegistry.getAll()                   |
+ * | registry.has('name')     | skillRegistry.has('name')                |
+ * | registry.size()          | skillRegistry.size()                     |
+ * | registry.generatePrompt()| skillRegistry.generatePrompt()           |
+ * | registry.toLangChainTools()| skillRegistry.toActivationTools()       |
+ */
+declare class SkillRegistry {
+    private skills;
+    private eventHandlers;
+    private readonly config;
+    private scanErrors;
+    /** Maps resolved root paths → trust levels for skill trust assignment */
+    private rootTrustMap;
+    /**
+     * Create a SkillRegistry and immediately scan configured roots for skills.
+     *
+     * @param config - Registry configuration with skill root paths
+     *
+     * @example
+     * ```ts
+     * const registry = new SkillRegistry({
+     *   skillRoots: ['.agentskills', '~/.agentskills', './project-skills'],
+     * });
+     * console.log(`Discovered ${registry.size()} skills`);
+     * ```
+     */
+    constructor(config: SkillRegistryConfig);
+    /**
+     * Scan all configured roots and populate the registry.
+     *
+     * Called automatically during construction. Can be called again
+     * to re-scan (clears existing skills first).
+     */
+    discover(): void;
+    /**
+     * Get a skill by name.
+     *
+     * @param name - The skill name
+     * @returns The skill, or undefined if not found
+     *
+     * @example
+     * ```ts
+     * const skill = registry.get('code-review');
+     * if (skill) {
+     *   console.log(skill.metadata.description);
+     * }
+     * ```
+     */
+    get(name: string): Skill | undefined;
+    /**
+     * Get all discovered skills.
+     *
+     * @returns Array of all skills
+     *
+     * @example
+     * ```ts
+     * const allSkills = registry.getAll();
+     * console.log(`Total skills: ${allSkills.length}`);
+     * ```
+     */
+    getAll(): Skill[];
+    /**
+     * Check if a skill exists in the registry.
+     *
+     * @param name - The skill name
+     * @returns True if the skill exists
+     *
+     * @example
+     * ```ts
+     * if (registry.has('code-review')) {
+     *   console.log('Skill available!');
+     * }
+     * ```
+     */
+    has(name: string): boolean;
+    /**
+     * Get the number of discovered skills.
+     *
+     * @returns Number of skills in the registry
+     *
+     * @example
+     * ```ts
+     * console.log(`Registry has ${registry.size()} skills`);
+     * ```
+     */
+    size(): number;
+    /**
+     * Get all skill names.
+     *
+     * @returns Array of skill names
+     */
+    getNames(): string[];
+    /**
+     * Get errors/warnings from the last scan.
+     *
+     * Useful for diagnostics and observability.
+     *
+     * @returns Array of scan errors with paths
+     */
+    getScanErrors(): ReadonlyArray<{
+        path: string;
+        error: string;
+    }>;
+    /**
+     * Check whether untrusted script access is allowed via config override.
+     *
+     * Used by activation tools to pass the override flag to trust policy checks.
+     *
+     * @returns True if `allowUntrustedScripts` is set in config
+     */
+    getAllowUntrustedScripts(): boolean;
+    /**
+     * Get the `allowed-tools` list for a skill.
+     *
+     * Returns the `allowedTools` array from the skill's frontmatter metadata,
+     * enabling agents to filter their tool set based on what the skill expects.
+     *
+     * @param name - The skill name
+     * @returns Array of allowed tool names, or undefined if skill not found or field not set
+     *
+     * @example
+     * ```ts
+     * const allowed = registry.getAllowedTools('code-review');
+     * if (allowed) {
+     *   const filteredTools = allTools.filter(t => allowed.includes(t.name));
+     * }
+     * ```
+     */
+    getAllowedTools(name: string): string[] | undefined;
+    /**
+     * Generate an `<available_skills>` XML block for system prompt injection.
+     *
+     * Returns an empty string when:
+     * - `config.enabled` is `false` (default) — agents operate with unmodified prompts
+     * - No skills match the filter criteria
+     *
+     * The output composes naturally with `toolRegistry.generatePrompt()` —
+     * simply concatenate both into the system prompt.
+     *
+     * @param options - Optional filtering (subset of skill names)
+     * @returns XML string or empty string
+     *
+     * @example
+     * ```ts
+     * // All skills
+     * const xml = registry.generatePrompt();
+     *
+     * // Subset for a focused agent
+     * const xml = registry.generatePrompt({ skills: ['code-review', 'testing'] });
+     *
+     * // Compose with tool prompt
+     * const systemPrompt = [
+     *   toolRegistry.generatePrompt(),
+     *   skillRegistry.generatePrompt(),
+     * ].filter(Boolean).join('\n\n');
+     * ```
+     */
+    generatePrompt(options?: SkillPromptOptions): string;
+    /**
+     * Register an event handler.
+     *
+     * @param event - The event to listen for
+     * @param handler - The handler function
+     *
+     * @example
+     * ```ts
+     * registry.on(SkillRegistryEvent.SKILL_DISCOVERED, (skill) => {
+     *   console.log('Found skill:', skill.metadata.name);
+     * });
+     * ```
+     */
+    on(event: SkillRegistryEvent, handler: SkillEventHandler): void;
+    /**
+     * Unregister an event handler.
+     *
+     * @param event - The event to stop listening for
+     * @param handler - The handler function to remove
+     */
+    off(event: SkillRegistryEvent, handler: SkillEventHandler): void;
+    /**
+     * Emit an event to all registered handlers.
+     *
+     * @param event - The event to emit
+     * @param data - The event data
+     * @private
+     */
+    private emit;
+    /**
+     * Emit an event (public API for activation tools).
+     *
+     * Used by skill activation tools to emit `skill:activated` and
+     * `skill:resource-loaded` events through the registry's event system.
+     *
+     * @param event - The event to emit
+     * @param data - The event data
+     */
+    emitEvent(event: SkillRegistryEvent, data: unknown): void;
+    /**
+     * Create activation tools pre-wired to this registry instance.
+     *
+     * Returns `activate-skill` and `read-skill-resource` tools that
+     * agents can use to load skill instructions and resources on demand.
+     *
+     * @returns Array of [activate-skill, read-skill-resource] tools
+     *
+     * @example
+     * ```ts
+     * const agent = createReActAgent({
+     *   model: llm,
+     *   tools: [
+     *     ...toolRegistry.toLangChainTools(),
+     *     ...skillRegistry.toActivationTools(),
+     *   ],
+     * });
+     * ```
+     */
+    toActivationTools(): ReturnType<typeof createSkillActivationTools>;
+}
+
+/**
+ * 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 };