@sylphx/flow 2.16.2 → 2.17.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sylphx/flow
 
+## 2.17.0 (2025-12-18)
+
+### ✨ Features
+
+- **skills:** implement skills loading and attach pipeline ([8d720b8](https://github.com/SylphxAI/flow/commit/8d720b8118ffe19e14d50aaacd9282bd5d42e702))
+
 ## 2.16.2 (2025-12-17)
 
 ### 🐛 Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "2.16.2",
+	"version": "2.17.0",
 	"description": "One CLI to rule them all. Unified orchestration layer for Claude Code, OpenCode, Cursor and all AI development tools. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {

package/src/core/attach-manager.ts

@@ -21,6 +21,8 @@ export interface AttachResult {
   agentsOverridden: string[];
   commandsAdded: string[];
   commandsOverridden: string[];
+  skillsAdded: string[];
+  skillsOverridden: string[];
   rulesAppended: boolean;
   mcpServersAdded: string[];
   mcpServersOverridden: string[];
@@ -31,7 +33,7 @@ export interface AttachResult {
 }
 
 export interface ConflictInfo {
-  type: 'agent' | 'command' | 'mcp' | 'hook';
+  type: 'agent' | 'command' | 'skill' | 'mcp' | 'hook';
   name: string;
   action: 'overridden' | 'merged';
   message: string;
@@ -40,6 +42,7 @@ export interface ConflictInfo {
 export interface FlowTemplates {
   agents: Array<{ name: string; content: string }>;
   commands: Array<{ name: string; content: string }>;
+  skills: Array<{ name: string; content: string }>;
   rules?: string;
   mcpServers: Array<{ name: string; config: Record<string, unknown> }>;
   hooks: Array<{ name: string; content: string }>;
@@ -143,6 +146,8 @@ export class AttachManager {
       agentsOverridden: [],
       commandsAdded: [],
       commandsOverridden: [],
+      skillsAdded: [],
+      skillsOverridden: [],
       rulesAppended: false,
       mcpServersAdded: [],
       mcpServersOverridden: [],
@@ -160,12 +165,17 @@ export class AttachManager {
     // 2. Attach commands
     await this.attachCommands(projectPath, target, templates.commands, result, manifest);
 
-    // 3. Attach rules (if applicable)
+    // 3. Attach skills (if target supports them)
+    if (target.config.skillsDir && templates.skills.length > 0) {
+      await this.attachSkills(projectPath, target, templates.skills, result, manifest);
+    }
+
+    // 4. Attach rules (if applicable)
     if (templates.rules) {
       await this.attachRules(projectPath, target, templates.rules, result, manifest);
     }
 
-    // 4. Attach MCP servers (merge global + template servers)
+    // 5. Attach MCP servers (merge global + template servers)
     const globalMCPServers = await this.loadGlobalMCPServers(target);
     const allMCPServers = [...globalMCPServers, ...templates.mcpServers];
 
@@ -173,12 +183,12 @@ export class AttachManager {
       await this.attachMCPServers(projectPath, target, allMCPServers, result, manifest);
     }
 
-    // 5. Attach hooks
+    // 6. Attach hooks
     if (templates.hooks.length > 0) {
       await this.attachHooks(projectPath, target, templates.hooks, result, manifest);
     }
 
-    // 6. Attach single files
+    // 7. Attach single files
     if (templates.singleFiles.length > 0) {
       await this.attachSingleFiles(projectPath, templates.singleFiles, result, manifest);
     }
@@ -238,6 +248,45 @@ export class AttachManager {
     manifest.backup.commands.flow.push(...itemManifest.flow);
   }
 
+  /**
+   * Attach skills (override strategy)
+   * Skills are stored as <domain>/SKILL.md subdirectories
+   */
+  private async attachSkills(
+    projectPath: string,
+    target: Target,
+    skills: Array<{ name: string; content: string }>,
+    result: AttachResult,
+    manifest: BackupManifest
+  ): Promise<void> {
+    const skillsDir = path.join(projectPath, target.config.skillsDir!);
+    await fs.mkdir(skillsDir, { recursive: true });
+
+    for (const skill of skills) {
+      // skill.name is like "auth/SKILL.md" - create subdirectory
+      const skillPath = path.join(skillsDir, skill.name);
+      const skillSubDir = path.dirname(skillPath);
+      await fs.mkdir(skillSubDir, { recursive: true });
+
+      const existed = existsSync(skillPath);
+      if (existed) {
+        result.skillsOverridden.push(skill.name);
+        result.conflicts.push({
+          type: 'skill',
+          name: skill.name,
+          action: 'overridden',
+          message: `Skill '${skill.name}' overridden (will be restored on exit)`,
+        });
+        manifest.backup.skills.user.push(skillPath);
+      } else {
+        result.skillsAdded.push(skill.name);
+      }
+
+      await fs.writeFile(skillPath, skill.content);
+      manifest.backup.skills.flow.push(skillPath);
+    }
+  }
+
   /**
    * Attach rules (append strategy for AGENTS.md)
    * Uses shared attachRulesFile function

package/src/core/backup-manager.ts

@@ -38,6 +38,10 @@ export interface BackupManifest {
       user: string[];
       flow: string[];
     };
+    skills: {
+      user: string[];
+      flow: string[];
+    };
     rules?: {
       path: string;
       originalSize: number;
@@ -114,6 +118,7 @@ export class BackupManager {
       backup: {
         agents: { user: [], flow: [] },
         commands: { user: [], flow: [] },
+        skills: { user: [], flow: [] },
         singleFiles: {},
       },
       secrets: {

package/src/core/flow-executor.ts

@@ -137,6 +137,7 @@ export class FlowExecutor {
       joined: false,
       agents: attachResult.agentsAdded.length,
       commands: attachResult.commandsAdded.length,
+      skills: attachResult.skillsAdded.length,
       mcp: attachResult.mcpServersAdded.length,
     };
   }
@@ -184,7 +185,15 @@ export class FlowExecutor {
       }
     }
 
-    // 3. Clear hooks directory (in configDir)
+    // 3. Clear skills directory (if target supports skills)
+    if (target.config.skillsDir) {
+      const skillsDir = path.join(projectPath, target.config.skillsDir);
+      if (existsSync(skillsDir)) {
+        await fs.rm(skillsDir, { recursive: true, force: true });
+      }
+    }
+
+    // 4. Clear hooks directory (in configDir)
     const hooksDir = path.join(projectPath, target.config.configDir, 'hooks');
     if (existsSync(hooksDir)) {
       const files = await fs.readdir(hooksDir);
@@ -193,7 +202,7 @@ export class FlowExecutor {
       }
     }
 
-    // 4. Clear MCP configuration using target config
+    // 5. Clear MCP configuration using target config
     const configPath = path.join(projectPath, target.config.configFile);
     const mcpPath = target.config.mcpConfigPath;
 
@@ -206,7 +215,7 @@ export class FlowExecutor {
       }
     }
 
-    // 5. Clear rules file if target has one defined (for targets like OpenCode)
+    // 6. Clear rules file if target has one defined (for targets like OpenCode)
     // Claude Code puts AGENTS.md in agents directory, handled above
     if (target.config.rulesFile) {
       const rulesPath = path.join(projectPath, target.config.rulesFile);
@@ -215,7 +224,7 @@ export class FlowExecutor {
       }
     }
 
-    // 6. Clear single files (output styles) - currently none
+    // 7. Clear single files (output styles) - currently none
     // These would be in the configDir if we had any
     const singleFiles: string[] = [];
     for (const fileName of singleFiles) {
@@ -225,7 +234,7 @@ export class FlowExecutor {
       }
     }
 
-    // 7. Clean up any Flow-created files in project root (legacy bug cleanup)
+    // 8. Clean up any Flow-created files in project root (legacy bug cleanup)
     // This handles files that were incorrectly created in project root
     const legacySingleFiles = ['silent.md']; // Keep for cleanup of legacy installations
     for (const fileName of legacySingleFiles) {

package/src/core/template-loader.ts

@@ -29,6 +29,7 @@ export class TemplateLoader {
     const templates: FlowTemplates = {
       agents: [],
       commands: [],
+      skills: [],
       rules: undefined,
       mcpServers: [],
       hooks: [],
@@ -47,6 +48,12 @@ export class TemplateLoader {
       templates.commands = await this.loadCommands(commandsDir);
     }
 
+    // Load skills (skills/<domain>/SKILL.md structure)
+    const skillsDir = path.join(this.assetsDir, 'skills');
+    if (existsSync(skillsDir)) {
+      templates.skills = await this.loadSkills(skillsDir);
+    }
+
     // Load rules (check multiple possible locations)
     const rulesLocations = [
       path.join(this.assetsDir, 'rules', 'AGENTS.md'),
@@ -115,6 +122,34 @@ export class TemplateLoader {
     return commands;
   }
 
+  /**
+   * Load skills from directory
+   * Skills are stored as <domain>/SKILL.md subdirectories
+   */
+  private async loadSkills(skillsDir: string): Promise<Array<{ name: string; content: string }>> {
+    const skills = [];
+    const domains = await fs.readdir(skillsDir);
+
+    for (const domain of domains) {
+      const domainPath = path.join(skillsDir, domain);
+      const stat = await fs.stat(domainPath);
+
+      if (!stat.isDirectory()) {
+        continue;
+      }
+
+      // Look for SKILL.md in each domain directory
+      const skillFile = path.join(domainPath, 'SKILL.md');
+      if (existsSync(skillFile)) {
+        const content = await fs.readFile(skillFile, 'utf-8');
+        // Name includes subdirectory: "auth/SKILL.md"
+        skills.push({ name: `${domain}/SKILL.md`, content });
+      }
+    }
+
+    return skills;
+  }
+
   /**
    * Load MCP servers configuration
    */

package/src/targets/claude-code.ts

@@ -41,6 +41,7 @@ export const claudeCodeTarget: Target = {
     rulesFile: undefined, // Rules are included in agent files
     outputStylesDir: undefined, // Output styles are included in agent files
     slashCommandsDir: '.claude/commands',
+    skillsDir: '.claude/skills',
     installation: {
       createAgentDir: true,
       createConfigFile: true,

package/src/types/target.types.ts

@@ -35,6 +35,8 @@ export interface TargetConfig {
   outputStylesDir?: string;
   /** Slash commands directory (optional, relative to project root) */
   slashCommandsDir?: string;
+  /** Skills directory (optional, relative to project root) */
+  skillsDir?: string;
   /** Installation-specific configuration */
   installation: {
     /** Whether to create the agent directory */
@@ -137,4 +139,7 @@ export interface Target {
 
   /** Setup slash commands for this target (optional - implement if target supports slash commands) */
   setupSlashCommands?(cwd: string, options: CommonOptions): Promise<SetupResult>;
+
+  /** Setup skills for this target (optional - implement if target supports skills) */
+  setupSkills?(cwd: string, options: CommonOptions): Promise<SetupResult>;
 }