agent-skills-standard 1.1.2 → 1.2.0

package/README.md

@@ -71,6 +71,30 @@ npx agent-skills-standard sync
 
 ---
 
+## ⚙️ Configuration (`.skillsrc`)
+
+The `.skillsrc` file allows you to customize how skills are synced to your project.
+
+```yaml
+registry: https://github.com/HoangNguyen0403/agent-skills-standard
+agents: [cursor, copilot]
+skills:
+  flutter:
+    ref: flutter-v1.1.0
+    # 🚫 Exclude specific sub-skills from being synced
+    exclude: ['getx-navigation']
+    # 🔒 Protect local modifications from being overwritten
+    custom_overrides: ['bloc-state-management']
+```
+
+### Key Options
+
+- **`exclude`**: A list of skill IDs to skip during synchronization. Useful if you want the main framework guidelines but use a different library for a specific sub-task (e.g., excluding `auto-route` if you use `go_router`).
+- **`custom_overrides`**: A list of skill IDs that the CLI should **never** overwrite. Use this when you have modified a standard skill locally to fit your project's unique needs. The CLI will detect these and preserve your local version.
+- **`ref`**: Specify a specific version or tag of the skills from the registry.
+
+---
+
 ## ✨ Key Features
 
 - **🎯 Efficiency First**: Uses a "Search-on-Demand" pattern that only loads information when the AI needs it, saving its "brain power" for your code.

package/dist/commands/init.d.ts

@@ -1,3 +1,6 @@
 export declare class InitCommand {
+    private detectionService;
+    private registryService;
+    private configService;
     run(): Promise<void>;
 }

package/dist/commands/init.js

@@ -7,103 +7,33 @@ exports.InitCommand = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
-const node_fetch_1 = __importDefault(require("node-fetch"));
 const path_1 = __importDefault(require("path"));
 const picocolors_1 = __importDefault(require("picocolors"));
 const constants_1 = require("../constants");
-const github_1 = require("../utils/github");
+const ConfigService_1 = require("../services/ConfigService");
+const DetectionService_1 = require("../services/DetectionService");
+const RegistryService_1 = require("../services/RegistryService");
 const project_1 = require("../utils/project");
 class InitCommand {
+    constructor() {
+        this.detectionService = new DetectionService_1.DetectionService();
+        this.registryService = new RegistryService_1.RegistryService();
+        this.configService = new ConfigService_1.ConfigService();
+    }
     async run() {
         const configPath = path_1.default.join(process.cwd(), '.skillsrc');
-        // Load package.json for dependency checks (for framework detection)
-        const packageJsonPath = path_1.default.join(process.cwd(), 'package.json');
-        let packageDeps = {};
-        if (await fs_extra_1.default.pathExists(packageJsonPath)) {
-            try {
-                const pkg = await fs_extra_1.default.readJson(packageJsonPath);
-                packageDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-            }
-            catch (e) {
-                console.error(picocolors_1.default.red(`❌ Failed to read package.json: ${e instanceof Error ? e.message : String(e)}`));
-            }
-        }
-        // Project detection
-        const detectionResults = {};
-        for (const framework of constants_1.SUPPORTED_FRAMEWORKS) {
-            let detected = false;
-            // 1. Check characteristic files
-            for (const file of framework.detectionFiles) {
-                if (await fs_extra_1.default.pathExists(file)) {
-                    detected = true;
-                    break;
-                }
-            }
-            // 2. Check dependencies (if not yet detected)
-            if (!detected &&
-                framework.detectionDependencies &&
-                framework.detectionDependencies.length > 0) {
-                detected = framework.detectionDependencies.some((dep) => Object.prototype.hasOwnProperty.call(packageDeps, dep));
-            }
-            detectionResults[framework.id] = detected;
-        }
-        // Agent detection
-        const agentDetection = {};
-        for (const agent of constants_1.SUPPORTED_AGENTS) {
-            let detected = false;
-            for (const file of agent.detectionFiles) {
-                if (await fs_extra_1.default.pathExists(file)) {
-                    detected = true;
-                    break;
-                }
-            }
-            agentDetection[agent.id] = detected;
-        }
+        const detectionResults = await this.detectionService.detectFrameworks();
+        const agentDetection = await this.detectionService.detectAgents();
         const anyAgentDetected = Object.values(agentDetection).some((d) => d);
-        // Helper to determine if an agent should be pre-selected
         const shouldCheck = (id) => anyAgentDetected ? agentDetection[id] : true;
-        // Supported categories are now determined by the registry contents if possible
-        // Default to a sane list if registry is unreachable
-        let supportedCategories = ['flutter', 'dart'];
-        let metadata = {};
-        // Attempt to discover available categories and registry metadata from the canonical registry
-        try {
-            const defaultRegistry = 'https://github.com/HoangNguyen0403/agent-skills-standard';
-            const parsed = (0, github_1.parseRegistryUrl)(defaultRegistry);
-            if (parsed) {
-                const treeResult = await (0, github_1.fetchRepoTree)(parsed.owner, parsed.repo);
-                if (treeResult && Array.isArray(treeResult.data.tree)) {
-                    const allFiles = treeResult.data.tree || [];
-                    const categories = new Set();
-                    allFiles.forEach((f) => {
-                        if (f.path.startsWith('skills/') && f.type === 'tree') {
-                            const parts = f.path.split('/');
-                            if (parts.length === 2)
-                                categories.add(parts[1]);
-                        }
-                    });
-                    if (categories.size > 0)
-                        supportedCategories = Array.from(categories);
-                    // Try to fetch metadata.json at the resolved branch
-                    const metaUrl = `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/${treeResult.branch}/skills/metadata.json`;
-                    const metaRes = await (0, node_fetch_1.default)(metaUrl);
-                    if (metaRes.ok) {
-                        metadata = (await metaRes.json());
-                    }
-                }
-            }
-        }
-        catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            console.error(picocolors_1.default.red(`❌ Failed to fetch registry metadata or tree: ${msg}`));
-        }
-        const choices = constants_1.SUPPORTED_FRAMEWORKS.map((f) => {
-            const isSupported = supportedCategories.includes(f.id);
-            return {
-                name: isSupported ? f.name : `${f.name} (Coming Soon)`,
-                value: f.id,
-            };
-        });
+        const defaultRegistry = 'https://github.com/HoangNguyen0403/agent-skills-standard';
+        const { categories: supportedCategories, metadata } = await this.registryService.discoverRegistry(defaultRegistry);
+        const choices = constants_1.SUPPORTED_FRAMEWORKS.map((f) => ({
+            name: supportedCategories.includes(f.id)
+                ? f.name
+                : `${f.name} (Coming Soon)`,
+            value: f.id,
+        }));
         if (await fs_extra_1.default.pathExists(configPath)) {
             const { overwrite } = await inquirer_1.default.prompt([
                 {
@@ -141,75 +71,20 @@ class InitCommand {
                 type: 'input',
                 name: 'registry',
                 message: 'Skills Registry URL:',
-                default: 'https://github.com/HoangNguyen0403/agent-skills-standard',
+                default: defaultRegistry,
             },
         ]);
         const framework = answers.framework;
-        const selectedFramework = constants_1.SUPPORTED_FRAMEWORKS.find((f) => f.id === framework);
-        const isSupported = supportedCategories.includes(framework);
-        if (!isSupported) {
+        if (!supportedCategories.includes(framework)) {
             console.log(picocolors_1.default.yellow(`\nNotice: Skills for ${framework} are not yet strictly defined and will be added soon.`));
             console.log(picocolors_1.default.gray('The CLI will still generate rule files with global standards.\n'));
         }
-        const neededSkills = new Set();
-        neededSkills.add(framework);
-        if (selectedFramework) {
-            selectedFramework.languages.forEach((l) => neededSkills.add(l));
-        }
-        // Special case: Next.js and React Native imply React
-        if (framework === constants_1.Framework.NextJS || framework === constants_1.Framework.ReactNative) {
-            neededSkills.add(constants_1.Framework.React);
-        }
-        // Add framework-specific skills from the registry to potential skills
-        const frameworkSkills = constants_1.SKILL_DETECTION_REGISTRY[framework] || [];
-        frameworkSkills.forEach((s) => neededSkills.add(s.id));
-        const config = {
-            registry: answers.registry,
-            agents: answers.agents,
-            skills: {},
-            custom_overrides: [],
-        };
-        // Initialize all potential skills from the registry folders we know
-        // This will be expanded as more frameworks are added to the repo
-        const allKnownCategories = [
-            ...constants_1.SUPPORTED_FRAMEWORKS.map((f) => f.id),
-            ...constants_1.SUPPORTED_FRAMEWORKS.flatMap((f) => f.languages),
-            ...Object.values(constants_1.SKILL_DETECTION_REGISTRY).flatMap((skills) => skills.map((s) => s.id)),
-        ];
-        for (const skill of [...new Set(allKnownCategories)]) {
-            if (neededSkills.has(skill)) {
-                const skillMeta = metadata.categories?.[skill];
-                let refStr;
-                if (skillMeta?.version && skillMeta?.tag_prefix) {
-                    refStr = `${skillMeta.tag_prefix}${skillMeta.version}`;
-                }
-                config.skills[skill] = {
-                    enabled: true,
-                    ref: refStr,
-                };
-            }
-        }
-        // Detect common framework skills and disable them if not used
+        const config = this.configService.buildInitialConfig(framework, answers.agents, answers.registry, metadata);
         const projectDeps = await (0, project_1.buildProjectDeps)();
-        for (const skill of frameworkSkills) {
-            const entry = config.skills[skill.id];
-            if (!entry)
-                continue;
-            // Only rely on declared dependencies for detection.
-            const used = skill.packages.some((p) => projectDeps.has(p));
-            // If not used, add to parent framework's exclude list so users
-            // see which sub-skills were disabled by detection and can opt-in.
-            if (!used) {
-                const parent = config.skills[framework] || { enabled: true };
-                const excludes = parent.exclude ? [...parent.exclude] : [];
-                if (!excludes.includes(skill.id))
-                    excludes.push(skill.id);
-                parent.exclude = excludes;
-                config.skills[framework] = parent;
-            }
-        }
+        this.configService.applyDependencyExclusions(config, framework, projectDeps);
         const commentHeader = `# Auto-detected configuration generated by agent-skills-standard init
 #
+# Presence in 'skills' list = Active. To disable a skill, remove it from the list.
 # 'exclude': IDs of sub-skills to skip during sync (auto-populated with undetected skills).
 # 'custom_overrides': IDs of skills to PROTECT. Use this if you have modified a standard 
 # skill locally and don't want the CLI to overwrite it.
@@ -219,9 +94,6 @@ class InitCommand {
         await fs_extra_1.default.writeFile(configPath, commentHeader + js_yaml_1.default.dump(config));
         console.log(picocolors_1.default.green('\n✅ Initialized .skillsrc with your preferences!'));
         console.log(picocolors_1.default.gray(`   Selected framework: ${framework}`));
-        console.log(picocolors_1.default.gray(`   Auto-enabled languages: ${Array.from(neededSkills)
-            .filter((s) => s !== framework)
-            .join(', ') || 'none'}`));
         console.log(picocolors_1.default.cyan('\nNext step: Run `agent-skills-standard sync` to generate rule files.'));
     }
 }

package/dist/commands/sync.js

@@ -27,9 +27,7 @@ class SyncCommand {
             // 2. Check for skill updates before syncing
             config = await this.checkForUpdates(config, configPath);
             console.log(picocolors_1.default.cyan(`🚀 Syncing skills from ${config.registry}...`));
-            const enabledCategories = Object.entries(config.skills)
-                .filter(([, value]) => value.enabled)
-                .map(([key]) => key);
+            const enabledCategories = Object.keys(config.skills);
             const skills = await this.assembleFromRemote(enabledCategories, config);
             await this.writeToTargets(skills, config);
             console.log(picocolors_1.default.green('✅ All skills synced successfully!'));
@@ -83,8 +81,6 @@ class SyncCommand {
             const remoteMeta = (await metaRes.json());
             const updates = [];
             for (const [cat, catConfig] of Object.entries(config.skills)) {
-                if (!catConfig.enabled)
-                    continue;
                 const remoteCat = remoteMeta.categories?.[cat];
                 if (!remoteCat || !remoteCat.version || !remoteCat.tag_prefix)
                     continue;

package/dist/constants/index.d.ts

@@ -7,7 +7,8 @@ export declare enum Agent {
     OpenAI = "openai",
     OpenCode = "opencode",
     Gemini = "gemini",
-    Roo = "roo"
+    Roo = "roo",
+    Windsurf = "windsurf"
 }
 export declare enum Framework {
     Flutter = "flutter",
@@ -18,6 +19,7 @@ export declare enum Framework {
     ReactNative = "react-native",
     Angular = "angular"
 }
+export declare const UNIVERSAL_SKILLS: string[];
 export interface AgentDefinition {
     id: Agent;
     name: string;

package/dist/constants/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SKILL_DETECTION_REGISTRY = exports.SUPPORTED_FRAMEWORKS = exports.SUPPORTED_AGENTS = exports.getFrameworkDefinition = exports.getAgentDefinition = exports.Framework = exports.Agent = void 0;
+exports.SKILL_DETECTION_REGISTRY = exports.SUPPORTED_FRAMEWORKS = exports.SUPPORTED_AGENTS = exports.getFrameworkDefinition = exports.getAgentDefinition = exports.UNIVERSAL_SKILLS = exports.Framework = exports.Agent = void 0;
 var Agent;
 (function (Agent) {
     Agent["Cursor"] = "cursor";
@@ -12,6 +12,7 @@ var Agent;
     Agent["OpenCode"] = "opencode";
     Agent["Gemini"] = "gemini";
     Agent["Roo"] = "roo";
+    Agent["Windsurf"] = "windsurf";
 })(Agent || (exports.Agent = Agent = {}));
 var Framework;
 (function (Framework) {
@@ -23,6 +24,7 @@ var Framework;
     Framework["ReactNative"] = "react-native";
     Framework["Angular"] = "angular";
 })(Framework || (exports.Framework = Framework = {}));
+exports.UNIVERSAL_SKILLS = ['common'];
 const getAgentDefinition = (id) => {
     switch (id) {
         case Agent.Cursor:
@@ -88,6 +90,13 @@ const getAgentDefinition = (id) => {
                 path: '.roo/skills',
                 detectionFiles: ['.roo'],
             };
+        case Agent.Windsurf:
+            return {
+                id,
+                name: 'Windsurf',
+                path: '.windsurf/skills',
+                detectionFiles: ['.windsurf', '.windsurfrules'],
+            };
     }
 };
 exports.getAgentDefinition = getAgentDefinition;

package/dist/index.js

@@ -8,8 +8,8 @@ const sync_1 = require("./commands/sync");
 const program = new commander_1.Command();
 program
     .name('agent-skills-standard')
-    .description('A CLI to manage and sync AI agent skills for Cursor, Claude, Copilot, and more.')
-    .version('1.1.2');
+    .description('A CLI to manage and sync AI agent skills for Cursor, Claude, Copilot, Windsurf, and more.')
+    .version('1.2.0');
 program
     .command('init')
     .description('Initialize a .skillsrc configuration file interactively')

package/dist/models/config.d.ts

@@ -1,13 +1,13 @@
+export interface SkillEntry {
+    ref?: string;
+    exclude?: string[];
+    include?: string[];
+}
 export interface SkillConfig {
     registry: string;
     agents: string[];
     skills: {
-        [key: string]: {
-            enabled: boolean;
-            ref?: string;
-            exclude?: string[];
-            include?: string[];
-        };
+        [key: string]: SkillEntry;
     };
     custom_overrides?: string[];
 }

package/dist/services/ConfigService.d.ts

@@ -0,0 +1,8 @@
+import { SkillConfig } from '../models/config';
+import { RegistryMetadata } from '../models/types';
+export declare class ConfigService {
+    buildInitialConfig(framework: string, agents: string[], registry: string, metadata: Partial<RegistryMetadata>): SkillConfig;
+    private getAllKnownCategories;
+    private createSkillEntry;
+    applyDependencyExclusions(config: SkillConfig, framework: string, projectDeps: Set<string>): void;
+}

package/dist/services/ConfigService.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigService = void 0;
+const constants_1 = require("../constants");
+class ConfigService {
+    buildInitialConfig(framework, agents, registry, metadata) {
+        const selectedFramework = constants_1.SUPPORTED_FRAMEWORKS.find((f) => f.id === framework);
+        const neededSkills = new Set();
+        constants_1.UNIVERSAL_SKILLS.forEach((s) => neededSkills.add(s));
+        neededSkills.add(framework);
+        if (selectedFramework) {
+            selectedFramework.languages.forEach((l) => neededSkills.add(l));
+        }
+        // Special cases
+        if (framework === constants_1.Framework.NextJS || framework === constants_1.Framework.ReactNative) {
+            neededSkills.add(constants_1.Framework.React);
+        }
+        const frameworkSkills = constants_1.SKILL_DETECTION_REGISTRY[framework] || [];
+        frameworkSkills.forEach((s) => neededSkills.add(s.id));
+        const config = {
+            registry,
+            agents,
+            skills: {},
+            custom_overrides: [],
+        };
+        const allKnownCategories = this.getAllKnownCategories();
+        for (const skill of [...new Set(allKnownCategories)]) {
+            if (neededSkills.has(skill)) {
+                config.skills[skill] = this.createSkillEntry(skill, metadata);
+            }
+        }
+        return config;
+    }
+    getAllKnownCategories() {
+        return [
+            ...constants_1.UNIVERSAL_SKILLS,
+            ...constants_1.SUPPORTED_FRAMEWORKS.map((f) => f.id),
+            ...constants_1.SUPPORTED_FRAMEWORKS.flatMap((f) => f.languages),
+            ...Object.values(constants_1.SKILL_DETECTION_REGISTRY).flatMap((skills) => skills.map((s) => s.id)),
+        ];
+    }
+    createSkillEntry(skill, metadata) {
+        const skillMeta = metadata.categories?.[skill];
+        let refStr;
+        if (skillMeta?.version && skillMeta?.tag_prefix) {
+            refStr = `${skillMeta.tag_prefix}${skillMeta.version}`;
+        }
+        return {
+            ref: refStr,
+        };
+    }
+    applyDependencyExclusions(config, framework, projectDeps) {
+        const frameworkSkills = constants_1.SKILL_DETECTION_REGISTRY[framework] || [];
+        for (const skill of frameworkSkills) {
+            const entry = config.skills[skill.id];
+            if (!entry)
+                continue;
+            const used = skill.packages.some((p) => projectDeps.has(p));
+            if (!used) {
+                const parent = config.skills[framework] || {};
+                const excludes = parent.exclude ? [...parent.exclude] : [];
+                if (!excludes.includes(skill.id))
+                    excludes.push(skill.id);
+                parent.exclude = excludes;
+                config.skills[framework] = parent;
+            }
+        }
+    }
+}
+exports.ConfigService = ConfigService;

package/dist/services/DetectionService.d.ts

@@ -0,0 +1,5 @@
+export declare class DetectionService {
+    detectFrameworks(): Promise<Record<string, boolean>>;
+    detectAgents(): Promise<Record<string, boolean>>;
+    private getPackageDeps;
+}

package/dist/services/DetectionService.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DetectionService = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const constants_1 = require("../constants");
+class DetectionService {
+    async detectFrameworks() {
+        const packageDeps = await this.getPackageDeps();
+        const results = {};
+        for (const framework of constants_1.SUPPORTED_FRAMEWORKS) {
+            let detected = false;
+            // 1. Check characteristic files
+            for (const file of framework.detectionFiles) {
+                if (await fs_extra_1.default.pathExists(path_1.default.join(process.cwd(), file))) {
+                    detected = true;
+                    break;
+                }
+            }
+            // 2. Check dependencies (if not yet detected)
+            if (!detected &&
+                framework.detectionDependencies &&
+                framework.detectionDependencies.length > 0) {
+                detected = framework.detectionDependencies.some((dep) => Object.prototype.hasOwnProperty.call(packageDeps, dep));
+            }
+            results[framework.id] = detected;
+        }
+        return results;
+    }
+    async detectAgents() {
+        const results = {};
+        for (const agent of constants_1.SUPPORTED_AGENTS) {
+            let detected = false;
+            for (const file of agent.detectionFiles) {
+                if (await fs_extra_1.default.pathExists(path_1.default.join(process.cwd(), file))) {
+                    detected = true;
+                    break;
+                }
+            }
+            results[agent.id] = detected;
+        }
+        return results;
+    }
+    async getPackageDeps() {
+        const packageJsonPath = path_1.default.join(process.cwd(), 'package.json');
+        if (await fs_extra_1.default.pathExists(packageJsonPath)) {
+            try {
+                const pkg = await fs_extra_1.default.readJson(packageJsonPath);
+                return { ...pkg.dependencies, ...pkg.devDependencies };
+            }
+            catch {
+                return {};
+            }
+        }
+        return {};
+    }
+}
+exports.DetectionService = DetectionService;

package/dist/services/RegistryService.d.ts

@@ -0,0 +1,7 @@
+import { RegistryMetadata } from '../models/types';
+export declare class RegistryService {
+    discoverRegistry(registryUrl: string): Promise<{
+        categories: string[];
+        metadata: Partial<RegistryMetadata>;
+    }>;
+}

package/dist/services/RegistryService.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistryService = void 0;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const github_1 = require("../utils/github");
+class RegistryService {
+    async discoverRegistry(registryUrl) {
+        let categories = ['flutter', 'dart'];
+        let metadata = {};
+        try {
+            const parsed = (0, github_1.parseRegistryUrl)(registryUrl);
+            if (parsed) {
+                const treeResult = await (0, github_1.fetchRepoTree)(parsed.owner, parsed.repo);
+                if (treeResult && Array.isArray(treeResult.data.tree)) {
+                    const allFiles = treeResult.data.tree || [];
+                    const foundCategories = new Set();
+                    allFiles.forEach((f) => {
+                        if (f.path.startsWith('skills/') && f.type === 'tree') {
+                            const parts = f.path.split('/');
+                            if (parts.length === 2)
+                                foundCategories.add(parts[1]);
+                        }
+                    });
+                    if (foundCategories.size > 0)
+                        categories = Array.from(foundCategories);
+                    const metaUrl = `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/${treeResult.branch}/skills/metadata.json`;
+                    const metaRes = await (0, node_fetch_1.default)(metaUrl);
+                    if (metaRes.ok) {
+                        metadata = (await metaRes.json());
+                    }
+                }
+            }
+        }
+        catch {
+            // Return defaults on error
+        }
+        return { categories, metadata };
+    }
+}
+exports.RegistryService = RegistryService;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-skills-standard",
-  "version": "1.1.2",
-  "description": "A CLI to manage and sync AI agent skills standard for Cursor, Claude, Copilot, and more.",
+  "version": "1.2.0",
+  "description": "A CLI to manage and sync AI agent skills standard for Cursor, Claude, Copilot, Windsurf, and more.",
   "main": "dist/index.js",
   "bin": {
     "agent-skills-standard": "dist/index.js",