skill-tree 0.1.4 → 0.1.5

package/dist/index.d.mts

@@ -14,18 +14,10 @@ interface Skill {
     version: string;
     /** Short description optimized for semantic matching (1-2 sentences) */
     description: string;
-    /** What problem does this skill solve? */
-    problem: string;
-    /** When should this skill be triggered? */
-    triggerConditions: TriggerCondition[];
-    /** Step-by-step solution */
-    solution: string;
-    /** How to verify the skill worked */
-    verification: string;
-    /** Concrete examples of usage */
-    examples: SkillExample[];
-    /** Additional notes, caveats, edge cases */
-    notes?: string;
+    /** Free-form markdown instructions (the SKILL.md body) */
+    instructions: string;
+    /** Related skill IDs */
+    related?: string[];
     author: string;
     tags: string[];
     createdAt: Date;
@@ -84,22 +76,6 @@ interface ExpandTriggerConfig {
     };
 }
 type SkillStatus = 'draft' | 'active' | 'deprecated' | 'experimental';
-interface TriggerCondition {
-    /** Type of trigger */
-    type: 'error' | 'pattern' | 'context' | 'keyword' | 'custom';
-    /** The actual condition (regex, keyword, description) */
-    value: string;
-    /** Optional description of when this triggers */
-    description?: string;
-}
-interface SkillExample {
-    /** Description of the scenario */
-    scenario: string;
-    /** Input/before state */
-    before: string;
-    /** Output/after state */
-    after: string;
-}
 interface SkillMetrics {
     /** Number of times this skill was used */
     usageCount: number;
@@ -257,83 +233,6 @@ interface SkillFork {
     /** When the fork happened */
     forkedAt: Date;
 }
-/**
- * Represents a parsed agent session/trajectory
- */
-interface Trajectory {
-    /** Unique session identifier */
-    sessionId: string;
-    /** When the session started */
-    startedAt: Date;
-    /** When the session ended */
-    endedAt?: Date;
-    /** The messages/turns in this session */
-    turns: Turn[];
-    /** Overall session metadata */
-    metadata: TrajectoryMetadata;
-    /** Session outcome */
-    outcome?: TrajectoryOutcome;
-}
-interface Turn {
-    /** Turn index (0-based) */
-    index: number;
-    /** Role: user, assistant, system, tool */
-    role: 'user' | 'assistant' | 'system' | 'tool';
-    /** Content of the turn */
-    content: string;
-    /** Tool calls made in this turn */
-    toolCalls?: ToolCall[];
-    /** Tool results returned in this turn */
-    toolResults?: ToolResult[];
-    /** Timestamp of this turn */
-    timestamp?: Date;
-    /** Extension data from custom extractors */
-    [key: string]: unknown;
-}
-interface ToolCall {
-    /** Tool name */
-    name: string;
-    /** Tool input/arguments */
-    input: Record<string, unknown>;
-    /** Unique call ID */
-    callId?: string;
-}
-interface ToolResult {
-    /** Corresponding call ID */
-    callId?: string;
-    /** Tool name */
-    name: string;
-    /** Result content */
-    output: string;
-    /** Whether the tool succeeded */
-    success: boolean;
-    /** Error message if failed */
-    error?: string;
-}
-interface TrajectoryMetadata {
-    /** Agent type (claude-code, custom, etc.) */
-    agentType: string;
-    /** Model used */
-    model?: string;
-    /** Working directory */
-    workingDirectory?: string;
-    /** Project/repo name */
-    projectName?: string;
-    /** Custom metadata */
-    custom?: Record<string, unknown>;
-}
-interface TrajectoryOutcome {
-    /** Did the session succeed in its goal? */
-    success: boolean;
-    /** Summary of what was accomplished */
-    summary?: string;
-    /** Files modified */
-    filesModified?: string[];
-    /** Errors encountered */
-    errors?: string[];
-    /** User satisfaction signal if available */
-    userSatisfaction?: 'positive' | 'negative' | 'neutral';
-}
 interface StorageAdapter {
     /** Initialize the storage */
     initialize(): Promise<void>;
@@ -402,6 +301,23 @@ type SkillTreeEvent = {
     skillId: string;
 };
 type SkillTreeEventHandler = (event: SkillTreeEvent) => void | Promise<void>;
+/**
+ * Configuration for materializing skills to agent-discoverable locations
+ */
+interface MaterializationConfig {
+    /** Enable automatic materialization on skill changes (default: false) */
+    enabled: boolean;
+    /** Materialization mode: 'symlink' creates symlinks, 'copy' copies directories (default: 'symlink') */
+    mode?: 'symlink' | 'copy';
+    /** Additional directories to symlink/copy skill dirs into (e.g. ['.claude/skills', '.agent/skills']) */
+    symlinkPaths?: string[];
+    /** Path to write AGENTS.md (e.g. './AGENTS.md'). If set, auto-regenerates on changes */
+    agentsMdPath?: string;
+    /** Format for AGENTS.md generation (default: 'xml') */
+    agentsMdFormat?: 'xml' | 'markdown' | 'json';
+    /** Debounce interval in ms for batch updates (default: 500) */
+    debounceMs?: number;
+}
 
 /**
  * Semantic versioning utilities
@@ -487,10 +403,6 @@ type MergeStrategy = 'source' | 'target' | 'combine' | 'newest' | 'longest' | 'u
 interface MergeConfig {
     /** Default strategy for text fields */
     textStrategy?: MergeStrategy;
-    /** Strategy for trigger conditions */
-    triggerStrategy?: MergeStrategy;
-    /** Strategy for examples */
-    exampleStrategy?: MergeStrategy;
     /** Strategy for tags */
     tagStrategy?: MergeStrategy;
     /** Fields to include in merge (defaults to all) */
@@ -623,8 +535,6 @@ declare class SkillMerger {
     private getStrategyForField;
     private mergeField;
     private mergeArrays;
-    private mergeTriggerConditions;
-    private mergeExamples;
     private mergeStrings;
     private calculateSimilarity;
     private buildMergeSuggestion;
@@ -883,13 +793,17 @@ interface SkillSyncState {
 }
 
 /**
- * Types for the hooks and activation system
+ * Types for the hooks system
+ *
+ * Session lifecycle tracking belongs to sessionlog.
+ * Skill runtime hooks (matched/applied/feedback) belong to cognitive-core.
+ * skill-tree hooks cover storage and CRUD lifecycle only.
  */
 
 /**
  * Events that can trigger hooks
  */
-type HookEvent = 'storage:before-save' | 'storage:after-save' | 'storage:before-delete' | 'storage:after-delete' | 'session:start' | 'session:end' | 'session:message' | 'skill:activated' | 'skill:matched' | 'skill:applied' | 'skill:feedback' | 'skill:created' | 'skill:updated' | 'skill:deprecated' | 'skill:deleted';
+type HookEvent = 'storage:before-save' | 'storage:after-save' | 'storage:before-delete' | 'storage:after-delete' | 'skill:created' | 'skill:updated' | 'skill:deprecated' | 'skill:deleted';
 /**
  * Priority levels for hook execution
  */
@@ -916,39 +830,6 @@ interface StorageHookContext extends BaseHookContext {
     /** Whether the operation was successful */
     success?: boolean;
 }
-/**
- * Context for session hooks
- */
-interface SessionHookContext extends BaseHookContext {
-    event: 'session:start' | 'session:end' | 'session:message';
-    sessionId: string;
-    /** Available on session:end */
-    trajectory?: Trajectory;
-    /** Message content (on session:message) */
-    message?: {
-        role: 'user' | 'assistant';
-        content: string;
-    };
-}
-/**
- * Context for skill runtime hooks (activation/matching/usage)
- */
-interface SkillRuntimeHookContext extends BaseHookContext {
-    event: 'skill:activated' | 'skill:matched' | 'skill:applied' | 'skill:feedback';
-    skill: Skill;
-    /** Match score (on skill:matched) */
-    matchScore?: number;
-    /** Application result (on skill:applied) */
-    applicationResult?: {
-        success: boolean;
-        output?: string;
-    };
-    /** Feedback data (on skill:feedback) */
-    feedback?: {
-        type: 'positive' | 'negative' | 'neutral';
-        comment?: string;
-    };
-}
 /**
  * Context for skill CRUD hooks (create/update/deprecate/delete)
  */
@@ -960,15 +841,10 @@ interface SkillCrudHookContext extends BaseHookContext {
     /** Deprecation reason (on skill:deprecated) */
     deprecationReason?: string;
 }
-/**
- * Legacy alias for backward compatibility
- * @deprecated Use SkillRuntimeHookContext instead
- */
-type SkillHookContext = SkillRuntimeHookContext;
 /**
  * Union of all hook contexts
  */
-type HookContext = StorageHookContext | SessionHookContext | SkillRuntimeHookContext | SkillCrudHookContext;
+type HookContext = StorageHookContext | SkillCrudHookContext;
 /**
  * Result from a hook handler
  */
@@ -2092,22 +1968,10 @@ declare class RemoteManager {
      * Parse YAML frontmatter (simple implementation)
      */
     private parseYamlFrontmatter;
-    /**
-     * Extract a section from markdown body
-     */
-    private extractSection;
-    /**
-     * Parse trigger conditions from metadata
-     */
-    private parseTriggerConditions;
     /**
      * Parse tags from metadata
      */
     private parseTags;
-    /**
-     * Parse examples from body
-     */
-    private parseExamples;
     /**
      * Serialize a skill to SKILL.md format
      */
@@ -2363,8 +2227,6 @@ declare class LineageTracker {
      * Get suggested next version based on changes
      */
     suggestNextVersion(skillId: string, changes: VersionChanges): Promise<string>;
-    private mergeTriggerConditions;
-    private mergeExamples;
     private mergeText;
     private diffSkills;
 }
@@ -2438,6 +2300,8 @@ interface SkillBankConfig {
         /** Pull remote changes on initialize() (default: false) */
         pullOnInit?: boolean;
     };
+    /** Materialization configuration for agent-discoverable skill output */
+    materialization?: MaterializationConfig;
 }
 /**
  * Main SkillBank class
@@ -2459,6 +2323,8 @@ declare class SkillBank {
     private syncManager?;
     /** Whether to pull on initialize */
     private syncPullOnInit;
+    /** Materializer for agent-discoverable output */
+    private materializer?;
     constructor(config?: SkillBankConfig);
     /**
      * Initialize the skill bank (required before use)
@@ -2872,12 +2738,6 @@ interface AgentsGeneratorConfig {
     includeIds?: boolean;
     /** Include version information (default: true) */
     includeVersions?: boolean;
-    /** Include trigger conditions (default: true) */
-    includeTriggers?: boolean;
-    /** Include examples (default: true) */
-    includeExamples?: boolean;
-    /** Maximum examples per skill (default: 3) */
-    maxExamples?: number;
     /** Group skills by tags (default: false) */
     groupByTags?: boolean;
     /** Custom header content */
@@ -2912,26 +2772,20 @@ interface ParsedAgentSkill {
     name: string;
     /** Skill description */
     description: string;
-    /** Problem this skill solves */
+    /** Instructions content */
+    instructions?: string;
+    /** Problem this skill solves (legacy, used during parsing) */
     problem?: string;
-    /** Solution steps */
+    /** Solution steps (legacy, used during parsing) */
     solution?: string;
-    /** Verification steps */
+    /** Verification steps (legacy, used during parsing) */
     verification?: string;
-    /** Additional notes */
+    /** Additional notes (legacy, used during parsing) */
     notes?: string;
-    /** Trigger conditions */
-    triggers?: string[];
     /** Tags extracted from content */
     tags?: string[];
     /** Version (if present) */
     version?: string;
-    /** Examples */
-    examples?: Array<{
-        scenario: string;
-        before?: string;
-        after?: string;
-    }>;
     /** Raw content block */
     rawContent: string;
 }
@@ -3080,10 +2934,6 @@ declare class AgentsParser {
      * Generate ID from skill name
      */
     private generateId;
-    /**
-     * Infer trigger type from content
-     */
-    private inferTriggerType;
     /**
      * Extract header content
      */
@@ -3173,6 +3023,9 @@ declare function importFromAgentsMd(filePath: string, storage: StorageAdapter, o
 
 /**
  * Built-in hooks for common use cases
+ *
+ * Runtime metrics hooks (matched/applied/feedback) have moved to cognitive-core
+ * which handles skill usage tracking via sessionlog integration.
  */
 
 /**
@@ -3191,10 +3044,6 @@ declare function createSaveValidationHook(options: {
     maxDescriptionLength?: number;
     requireTriggers?: boolean;
 }): RegisterHookOptions;
-/**
- * Creates a hook that tracks skill usage metrics
- */
-declare function createMetricsHook(updateMetrics: (skillId: string, event: 'matched' | 'applied' | 'feedback', data?: unknown) => Promise<void>): RegisterHookOptions;
 /**
  * Combines multiple hook handlers into one
  */
@@ -3292,8 +3141,6 @@ interface ViewRendererConfig {
     includeTokenEstimates?: boolean;
     /** Maximum summary length (characters) */
     maxSummaryLength?: number;
-    /** Include examples in expanded content */
-    includeExamples?: boolean;
 }
 /**
  * Renders loadout state for agent consumption
@@ -3325,10 +3172,6 @@ declare class ViewRenderer {
      * Get summary for a skill (short description)
      */
     private getSummary;
-    /**
-     * Render skill content for expanded view
-     */
-    private renderSkillContent;
     /**
      * Escape special XML characters
      */
@@ -3483,6 +3326,93 @@ declare function getBuiltInProfile(name: string): LoadoutCriteria | undefined;
  */
 declare function listBuiltInProfiles(): string[];
 
+/**
+ * Materializer - Keeps agent-discoverable filesystem representations
+ * in sync with the skill bank.
+ *
+ * Supports two modes:
+ * - 'symlink': Creates symlinks from discovery paths into .skilltree/skills/
+ * - 'copy': Copies skill directories to discovery paths
+ *
+ * Also auto-regenerates AGENTS.md on skill changes with marker-based sections.
+ */
+
+declare class Materializer {
+    private storage;
+    private basePath;
+    private config;
+    private debounceTimer;
+    private pendingRegen;
+    private regenerating;
+    private watcher;
+    private watchDebounceTimer;
+    constructor(storage: StorageAdapter, basePath: string, config: MaterializationConfig);
+    private get mode();
+    private get skillsSourceDir();
+    /**
+     * Initial materialization: create all symlinks/copies + generate AGENTS.md
+     */
+    initialize(): Promise<void>;
+    /**
+     * Called when a skill is created or updated
+     */
+    onSkillChanged(skillId: string): Promise<void>;
+    /**
+     * Called when a skill is deleted
+     */
+    onSkillDeleted(skillId: string): Promise<void>;
+    /**
+     * Materialize a skill to all configured paths (symlink or copy)
+     */
+    private ensureMaterialized;
+    /**
+     * Remove a materialized skill from all configured paths
+     */
+    private removeMaterialized;
+    /**
+     * Create or verify a symlink
+     */
+    private ensureSymlink;
+    /**
+     * Copy a skill directory, adding a marker file so we know we manage it
+     */
+    private copyDir;
+    /**
+     * Schedule debounced AGENTS.md regeneration
+     */
+    private scheduleAgentsMdRegen;
+    /**
+     * Regenerate AGENTS.md with marker-based section replacement
+     */
+    regenerateAgentsMd(): Promise<void>;
+    private _doRegenerateAgentsMd;
+    /**
+     * Remove stale entries (symlinks or copies) that point to non-existent skills
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Start watching .skilltree/skills/ for external changes.
+     * Re-materializes when files are added/changed/removed outside the SkillBank API.
+     */
+    watch(): void;
+    /**
+     * Stop watching for file changes
+     */
+    unwatch(): void;
+    /**
+     * Flush any pending debounced operations (useful for testing)
+     */
+    flush(): Promise<void>;
+    /**
+     * Tear down: cancel pending timers and stop watcher
+     */
+    shutdown(): void;
+    /**
+     * Resolve a path relative to basePath, handling ~ expansion
+     */
+    private resolvePath;
+}
+
 /**
  * Git Sync Adapter
  *
@@ -3547,7 +3477,6 @@ declare class GitSyncAdapter {
     private applyStrategy;
     private getConflictingFields;
     private parseSkillContent;
-    private extractSection;
     private writeSkill;
     private buildSkillContent;
     private buildCommitMessage;
@@ -3650,4 +3579,4 @@ declare function createDefaultSyncConfig(remoteUrl: string, agentId: string, opt
  */
 declare const VERSION = "0.1.0";
 
-export { type AgentConfig, AgentsGenerator, type AgentsGeneratorConfig, AgentsParser, AgentsSync, type BaseHookContext, type BumpType, CachedStorageAdapter, type CachedStorageConfig, type ConflictConfig, type ConflictResolution$1 as ConflictResolution, ConflictStore, type ConflictStrategy, DEFAULT_AGENTS_CONFIG, type DiscoveredSkill, type EvictionStrategy, type ExpandTrigger, type ExpandTriggerConfig, type FederatedRemoteConfig, type FederationEvent, type FederationEventHandler, FederationManager, type FederationManagerOptions, type FetchResult, type ForkOptions, GitSyncAdapter, type GitSyncAdapterOptions, type SyncResult$1 as GitSyncResult, type GraphServerConfig, type HookContext, type HookEvent, type HookExecutionResult, type HookHandler, type HookPriority, HookRegistry, type HookResult, type ImportMode, type ImportOptions, type ImportResult, LineageTracker, type LineageTree, LoadoutCompiler, type LoadoutCompilerConfig, type LoadoutCriteria, type LoadoutSource, type LoadoutState, type LoadoutView, MemoryStorageAdapter, type MergeConfig, type MergeConflict, type MergePreview, type MergeResult, type MergeStrategy, type MergeSuggestion, type MigrationOptions, type MigrationProgressItem, type MigrationResult, type NewVersionOptions, type ParsedAgentSkill, type ParsedAgentsFile, type ParsedVersion, type ProjectContext, ProjectDetector, type PullOptions, type PullUpstreamOptions, type PullUpstreamResult, type PushOptions, type RegisterHookOptions, type RegisteredHook, type RemoteConfig, RemoteManager, type RemoteState, RemoteStore, type RollbackOptions, type ServingEvent, type ServingEventHandler, type ShareOptions, type ShareResult, type Skill, type SkillAccessControl, SkillBank, type SkillBankConfig, type SkillBankStats, type SkillChange, type SkillConflict, type SkillDiffChanges, type SkillExample, type SkillFilter, type SkillFork, type SkillFormat, SkillGraphServer, type SkillHookContext, type SkillLineage, type SkillMergeResult, SkillMerger, type SkillMetrics, type SkillNamespace, type SkillScope, type SkillSelector, type SkillServingMetadata, type SkillSource, type SkillState, type SkillStatus, type SkillSummary, type SkillSyncState, type SkillTreeEvent, type SkillTreeEventHandler, type SkillUpstream, type SkillVersion, type SkillVisibility, type StorageAdapter, type StorageConfig, type StorageHookContext, type SyncBehaviorConfig, type SyncConfig, type ConflictResolution as SyncConflictResolution, type SyncError, SyncManager, type SyncManagerOptions, type SyncOptions, type SyncResult, type SyncState, type SyncStatus, type TriggerCondition, type UpstreamUpdate, VERSION, type VersionChanges, type VersionDiff, ViewRenderer, type ViewRendererConfig, builtInProfiles, bumpVersion, codeReviewProfile, combineHandlers, compareVersions, conditionalHook, createAgentsGenerator, createAgentsParser, createAgentsSync, createBackupHook, createConflictStore, createDefaultSyncConfig, createFederationManager, createGitSyncAdapter, createLoggingHook, createMetricsHook, createSaveValidationHook, createSkillBank, createSkillMerger, createSyncManager, debuggingProfile, devopsProfile, discoverSkills, documentationProfile, formatVersion, generateAgentsMd, getBuiltInProfile, getLatestVersion, hasSkilltreeDir, hookRegistry, implementationProfile, importFromAgentsMd, inferBumpType, isValidVersion, listBuiltInProfiles, migrateStorage, parseVersion, refactoringProfile, satisfiesRange, securityProfile, sortVersions, testingProfile, writeAgentsMd };
+export { type AgentConfig, AgentsGenerator, type AgentsGeneratorConfig, AgentsParser, AgentsSync, type BaseHookContext, type BumpType, CachedStorageAdapter, type CachedStorageConfig, type ConflictConfig, type ConflictResolution$1 as ConflictResolution, ConflictStore, type ConflictStrategy, DEFAULT_AGENTS_CONFIG, type DiscoveredSkill, type EvictionStrategy, type ExpandTrigger, type ExpandTriggerConfig, type FederatedRemoteConfig, type FederationEvent, type FederationEventHandler, FederationManager, type FederationManagerOptions, type FetchResult, type ForkOptions, GitSyncAdapter, type GitSyncAdapterOptions, type SyncResult$1 as GitSyncResult, type GraphServerConfig, type HookContext, type HookEvent, type HookExecutionResult, type HookHandler, type HookPriority, HookRegistry, type HookResult, type ImportMode, type ImportOptions, type ImportResult, LineageTracker, type LineageTree, LoadoutCompiler, type LoadoutCompilerConfig, type LoadoutCriteria, type LoadoutSource, type LoadoutState, type LoadoutView, type MaterializationConfig, Materializer, MemoryStorageAdapter, type MergeConfig, type MergeConflict, type MergePreview, type MergeResult, type MergeStrategy, type MergeSuggestion, type MigrationOptions, type MigrationProgressItem, type MigrationResult, type NewVersionOptions, type ParsedAgentSkill, type ParsedAgentsFile, type ParsedVersion, type ProjectContext, ProjectDetector, type PullOptions, type PullUpstreamOptions, type PullUpstreamResult, type PushOptions, type RegisterHookOptions, type RegisteredHook, type RemoteConfig, RemoteManager, type RemoteState, RemoteStore, type RollbackOptions, type ServingEvent, type ServingEventHandler, type ShareOptions, type ShareResult, type Skill, type SkillAccessControl, SkillBank, type SkillBankConfig, type SkillBankStats, type SkillChange, type SkillConflict, type SkillCrudHookContext, type SkillDiffChanges, type SkillFilter, type SkillFork, type SkillFormat, SkillGraphServer, type SkillLineage, type SkillMergeResult, SkillMerger, type SkillMetrics, type SkillNamespace, type SkillScope, type SkillSelector, type SkillServingMetadata, type SkillSource, type SkillState, type SkillStatus, type SkillSummary, type SkillSyncState, type SkillTreeEvent, type SkillTreeEventHandler, type SkillUpstream, type SkillVersion, type SkillVisibility, type StorageAdapter, type StorageConfig, type StorageHookContext, type SyncBehaviorConfig, type SyncConfig, type ConflictResolution as SyncConflictResolution, type SyncError, SyncManager, type SyncManagerOptions, type SyncOptions, type SyncResult, type SyncState, type SyncStatus, type UpstreamUpdate, VERSION, type VersionChanges, type VersionDiff, ViewRenderer, type ViewRendererConfig, builtInProfiles, bumpVersion, codeReviewProfile, combineHandlers, compareVersions, conditionalHook, createAgentsGenerator, createAgentsParser, createAgentsSync, createBackupHook, createConflictStore, createDefaultSyncConfig, createFederationManager, createGitSyncAdapter, createLoggingHook, createSaveValidationHook, createSkillBank, createSkillMerger, createSyncManager, debuggingProfile, devopsProfile, discoverSkills, documentationProfile, formatVersion, generateAgentsMd, getBuiltInProfile, getLatestVersion, hasSkilltreeDir, hookRegistry, implementationProfile, importFromAgentsMd, inferBumpType, isValidVersion, listBuiltInProfiles, migrateStorage, parseVersion, refactoringProfile, satisfiesRange, securityProfile, sortVersions, testingProfile, writeAgentsMd };