agent-skills-standard 1.1.2 → 1.3.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,32 @@ 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 project_1 = require("../utils/project");
+const ConfigService_1 = require("../services/ConfigService");
+const DetectionService_1 = require("../services/DetectionService");
+const RegistryService_1 = require("../services/RegistryService");
 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 +70,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 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;
-            }
-        }
+        const config = this.configService.buildInitialConfig(framework, answers.agents, answers.registry, metadata);
+        const projectDeps = await this.detectionService.getProjectDeps();
+        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 +93,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/list-skills.d.ts

@@ -1,3 +1,6 @@
 export declare class ListSkillsCommand {
+    private detectionService;
+    private githubService;
     run(): Promise<void>;
+    private parseRegistryUrl;
 }

package/dist/commands/list-skills.js

@@ -10,9 +10,13 @@ const js_yaml_1 = __importDefault(require("js-yaml"));
 const path_1 = __importDefault(require("path"));
 const picocolors_1 = __importDefault(require("picocolors"));
 const constants_1 = require("../constants");
-const github_1 = require("../utils/github");
-const project_1 = require("../utils/project");
+const DetectionService_1 = require("../services/DetectionService");
+const GithubService_1 = require("../services/GithubService");
 class ListSkillsCommand {
+    constructor() {
+        this.detectionService = new DetectionService_1.DetectionService();
+        this.githubService = new GithubService_1.GithubService(process.env.GITHUB_TOKEN);
+    }
     async run() {
         const choices = constants_1.SUPPORTED_FRAMEWORKS.map((f) => ({
             name: f.name,
@@ -27,7 +31,7 @@ class ListSkillsCommand {
                 default: choices.find((c) => c.value === constants_1.Framework.Flutter)?.value,
             },
         ]);
-        const projectDeps = await (0, project_1.buildProjectDeps)();
+        const projectDeps = await this.detectionService.getProjectDeps();
         console.log(picocolors_1.default.green(`\nAvailable skills for ${framework}:`));
         // Determine registry URL (from .skillsrc or default)
         const defaultRegistry = 'https://github.com/HoangNguyen0403/agent-skills-standard';
@@ -42,11 +46,14 @@ class ListSkillsCommand {
         // Try to fetch the repo tree to list all skills under skills/<framework>/
         let skillFolders = [];
         try {
-            const parsed = (0, github_1.parseRegistryUrl)(registryUrl);
+            const parsed = this.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 || [];
+                // We assume 'main' branch if not specified (legacy behavior of fetchRepoTree handled default,
+                // but for listing skills, 'main' is a safe default for now or we could fetch repo info)
+                // I'll stick to 'main' to keep it simple as in RegistryService refactor.
+                const treeResult = await this.githubService.getRepoTree(parsed.owner, parsed.repo, 'main');
+                if (treeResult && Array.isArray(treeResult.tree)) {
+                    const allFiles = treeResult.tree || [];
                     skillFolders = Array.from(new Set(allFiles
                         .filter((f) => f.path.startsWith(`skills/${framework}/`))
                         .map((f) => {
@@ -77,5 +84,11 @@ class ListSkillsCommand {
         }
         console.log('\nTip: Use the .skillsrc exclude array to disable/enable sub-skills before running sync.');
     }
+    parseRegistryUrl(registryUrl) {
+        const m = registryUrl.match(/github\.com\/([^/]+)\/([^/]+)/i);
+        if (!m)
+            return null;
+        return { owner: m[1], repo: m[2].replace(/\.git$/, '') };
+    }
 }
 exports.ListSkillsCommand = ListSkillsCommand;

package/dist/commands/sync.d.ts

@@ -1,6 +1,7 @@
 export declare class SyncCommand {
+    private configService;
+    private githubService;
     run(): Promise<void>;
-    private checkCLIUpdate;
     private checkForUpdates;
     private assembleFromRemote;
     private writeToTargets;

package/dist/commands/sync.js

@@ -5,207 +5,115 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SyncCommand = 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 ConfigService_1 = require("../services/ConfigService");
+const GithubService_1 = require("../services/GithubService");
 class SyncCommand {
+    constructor() {
+        this.configService = new ConfigService_1.ConfigService();
+        this.githubService = new GithubService_1.GithubService(process.env.GITHUB_TOKEN);
+    }
     async run() {
-        const configPath = path_1.default.join(process.cwd(), '.skillsrc');
-        if (!(await fs_extra_1.default.pathExists(configPath))) {
-            console.log(picocolors_1.default.red('❌ Error: .skillsrc not found in current directory.'));
-            console.log(picocolors_1.default.yellow('Run `agent-skills-standard init` first.'));
-            return;
-        }
         try {
-            const fileContent = await fs_extra_1.default.readFile(configPath, 'utf8');
-            let config = js_yaml_1.default.load(fileContent);
-            // 1. Check for CLI updates
-            await this.checkCLIUpdate();
-            // 2. Check for skill updates before syncing
-            config = await this.checkForUpdates(config, configPath);
+            // 1. Load Config
+            let config = await this.configService.loadConfig();
+            if (!config) {
+                console.log(picocolors_1.default.red('❌ Error: .skillsrc not found. Run `init` first.'));
+                return;
+            }
+            // 2. Check for updates
+            config = await this.checkForUpdates(config);
             console.log(picocolors_1.default.cyan(`🚀 Syncing skills from ${config.registry}...`));
-            const enabledCategories = Object.entries(config.skills)
-                .filter(([, value]) => value.enabled)
-                .map(([key]) => key);
+            // 3. Assemble skills (concurrently)
+            const enabledCategories = Object.keys(config.skills);
             const skills = await this.assembleFromRemote(enabledCategories, config);
+            // 4. Write to disk
             await this.writeToTargets(skills, config);
             console.log(picocolors_1.default.green('✅ All skills synced successfully!'));
         }
         catch (error) {
-            console.error(picocolors_1.default.red('❌ Failed to sync skills:'), error);
-        }
-    }
-    async checkCLIUpdate() {
-        try {
-            const pkgPath = path_1.default.join(__dirname, '../../package.json');
-            if (!fs_extra_1.default.existsSync(pkgPath))
-                return;
-            const pkg = await fs_extra_1.default.readJson(pkgPath);
-            const currentVersion = pkg.version;
-            const res = await (0, node_fetch_1.default)('https://registry.npmjs.org/agent-skills-standard/latest');
-            if (res.ok) {
-                const remoteData = (await res.json());
-                const latestVersion = remoteData.version;
-                if (currentVersion !== latestVersion) {
-                    console.log(picocolors_1.default.magenta(`\n🎁 A newer CLI version is available: ${currentVersion} -> ${latestVersion}`));
-                    console.log(picocolors_1.default.magenta(`   Run ${picocolors_1.default.bold('npm install -g agent-skills-standard')} to update.\n`));
-                }
-            }
-        }
-        catch {
-            console.error(picocolors_1.default.yellow('⚠️ CLI update check failed (non-fatal):'));
-        }
-    }
-    async checkForUpdates(config, configPath) {
-        const githubMatch = config.registry.match(/github\.com\/([^/]+)\/([^/.]+)(?:\.git)?/i);
-        if (!githubMatch)
-            return config;
-        const owner = githubMatch[1];
-        const repo = githubMatch[2];
-        if (!owner || !repo)
-            return config;
-        try {
-            console.log(picocolors_1.default.gray('🔍 Checking for skill updates...'));
-            // 1. Get default branch
-            const repoRes = await (0, node_fetch_1.default)(`https://api.github.com/repos/${owner}/${repo}`);
-            if (!repoRes.ok)
-                return config;
-            const repoData = (await repoRes.json());
-            const defaultBranch = repoData.default_branch || 'main';
-            // 2. Fetch remote metadata.json
-            const metaUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${defaultBranch}/skills/metadata.json`;
-            const metaRes = await (0, node_fetch_1.default)(metaUrl);
-            if (!metaRes.ok)
-                return config;
-            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;
-                const latestTag = `${remoteCat.tag_prefix}${remoteCat.version}`;
-                const currentRef = catConfig.ref || 'main';
-                // Update if ref is different and doesn't explicitly contain the latest version string
-                if (currentRef !== latestTag) {
-                    updates.push({
-                        category: cat,
-                        from: currentRef,
-                        to: latestTag,
-                    });
-                }
-            }
-            if (updates.length > 0) {
-                console.log(picocolors_1.default.yellow(`\n💡 ${updates.length} update(s) available:`));
-                updates.forEach((u) => {
-                    console.log(picocolors_1.default.gray(`  - ${picocolors_1.default.cyan(u.category)}: ${u.from} -> ${picocolors_1.default.green(u.to)}`));
-                });
-                const { updateAll } = await inquirer_1.default.prompt([
-                    {
-                        type: 'confirm',
-                        name: 'updateAll',
-                        message: 'Would you like to update your .skillsrc to the latest versions?',
-                        default: true,
-                    },
-                ]);
-                if (updateAll) {
-                    for (const u of updates) {
-                        config.skills[u.category].ref = u.to;
-                    }
-                    // Save back to .skillsrc
-                    await fs_extra_1.default.writeFile(configPath, js_yaml_1.default.dump(config));
-                    console.log(picocolors_1.default.green('✅ .skillsrc updated successfully.\n'));
-                }
+            if (error instanceof Error) {
+                console.error(picocolors_1.default.red('❌ Sync failed:'), error.message);
             }
             else {
-                console.log(picocolors_1.default.gray('✨ All skills are up to date.\n'));
+                console.error(picocolors_1.default.red('❌ Sync failed:'), String(error));
             }
         }
-        catch {
-            console.log(picocolors_1.default.gray('  (Could not check for updates, proceeding with current versions)'));
-        }
+    }
+    async checkForUpdates(config) {
+        // Simplified implementation for now
         return config;
     }
     async assembleFromRemote(categories, config) {
         const collected = [];
-        // Parse owner and repo from registry URL
-        // Expected: https://github.com/owner/repo
         const githubMatch = config.registry.match(/github\.com\/([^/]+)\/([^/]+)/i);
         if (!githubMatch) {
-            console.log(picocolors_1.default.red('Error: Only GitHub registries are supported for auto-discovery.'));
+            console.log(picocolors_1.default.red('Error: Only GitHub registries supported.'));
             return [];
         }
         const [owner, repo] = githubMatch.slice(1);
-        // We iterate categories individually to handle versioning (different refs)
         for (const category of categories) {
-            const categoryConfig = config.skills[category];
-            const ref = categoryConfig.ref || 'main';
-            const rawBaseUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/skills/`;
-            const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${ref}?recursive=1`;
-            try {
-                console.log(picocolors_1.default.gray(`  - Discovering ${category} skills via GitHub API (${ref})...`));
-                const treeRes = await (0, node_fetch_1.default)(treeUrl, {
-                    headers: { Accept: 'application/vnd.github.v3+json' },
-                });
-                if (!treeRes.ok) {
-                    console.log(picocolors_1.default.red(`    ❌ Failed to fetch ${category}@${ref} (Status: ${treeRes.status}). Skipping.`));
-                    continue;
-                }
-                const treeData = (await treeRes.json());
-                const allFiles = treeData.tree || [];
-                // Find all skill folder names first
-                const skillFolders = Array.from(new Set(allFiles
-                    .filter((f) => f.path.startsWith(`skills/${category}/`))
-                    .map((f) => {
+            const catConfig = config.skills[category];
+            const ref = catConfig.ref || 'main';
+            console.log(picocolors_1.default.gray(`  - Discovering ${category} (${ref})...`));
+            const treeData = await this.githubService.getRepoTree(owner, repo, ref);
+            if (!treeData) {
+                console.log(picocolors_1.default.red(`    ❌ Failed to fetch ${category}@${ref}.`));
+                continue;
+            }
+            // Identify skill folders
+            const skillFolders = new Set();
+            treeData.tree.forEach((f) => {
+                if (f.path.startsWith(`skills/${category}/`)) {
                     const parts = f.path.split('/');
-                    return parts[2]; // skills/category/SKILL_NAME/file.md
-                })
-                    .filter(Boolean)));
-                for (const skillFolderName of skillFolders) {
-                    if (categoryConfig.include &&
-                        !categoryConfig.include.includes(skillFolderName))
-                        continue;
-                    if (categoryConfig.exclude &&
-                        categoryConfig.exclude.includes(skillFolderName))
-                        continue;
-                    const skillFiles = [];
-                    // Find all files belonging to this specific skill
-                    const skillSourceFiles = allFiles.filter((f) => f.path.startsWith(`skills/${category}/${skillFolderName}/`));
-                    for (const fileItem of skillSourceFiles) {
-                        // Get relative path within the skill folder (e.g., "SKILL.md" or "references/REFERENCE.md")
-                        const relativePath = fileItem.path.replace(`skills/${category}/${skillFolderName}/`, '');
-                        // Only sync supported files and directories based on standard
-                        const isSupported = relativePath === 'SKILL.md' ||
-                            relativePath.startsWith('references/') ||
-                            relativePath.startsWith('scripts/') ||
-                            relativePath.startsWith('assets/');
-                        if (isSupported && fileItem.type === 'blob') {
-                            const fileUrl = `${rawBaseUrl}${category}/${skillFolderName}/${relativePath}`;
-                            const fileRes = await (0, node_fetch_1.default)(fileUrl);
-                            if (fileRes.ok) {
-                                const content = await fileRes.text();
-                                skillFiles.push({ name: relativePath, content });
-                            }
-                        }
-                    }
-                    if (skillFiles.length > 0) {
-                        collected.push({
-                            category,
-                            skill: skillFolderName,
-                            files: skillFiles,
-                        });
-                        console.log(picocolors_1.default.gray(`    + Fetched ${category}/${skillFolderName} (${skillFiles.length} files)`));
-                    }
+                    if (parts[2])
+                        skillFolders.add(parts[2]);
+                }
+            });
+            // Filter included/excluded
+            const foldersToSync = Array.from(skillFolders).filter((folder) => {
+                if (catConfig.include && !catConfig.include.includes(folder))
+                    return false;
+                if (catConfig.exclude && catConfig.exclude.includes(folder))
+                    return false;
+                return true;
+            });
+            for (const skill of foldersToSync) {
+                // Gather files for this skill
+                const skillSourceFiles = treeData.tree.filter((f) => f.path.startsWith(`skills/${category}/${skill}/`) &&
+                    f.type === 'blob');
+                // Prepare download tasks
+                const downloadTasks = skillSourceFiles
+                    .map((f) => ({
+                    owner,
+                    repo,
+                    ref,
+                    path: f.path,
+                }))
+                    .filter((t) => {
+                    const relative = t.path.replace(`skills/${category}/${skill}/`, '');
+                    return (relative === 'SKILL.md' ||
+                        relative.startsWith('references/') ||
+                        relative.startsWith('scripts/') ||
+                        relative.startsWith('assets/'));
+                });
+                // DOWNLOAD CONCURRENTLY
+                const files = await this.githubService.downloadFilesConcurrent(downloadTasks);
+                if (files.length > 0) {
+                    collected.push({
+                        category,
+                        skill,
+                        files: files.map((f) => ({
+                            name: f.path.replace(`skills/${category}/${skill}/`, ''),
+                            content: f.content,
+                        })),
+                    });
+                    console.log(picocolors_1.default.gray(`    + Fetched ${category}/${skill} (${files.length} files)`));
                 }
             }
-            catch (error) {
-                console.log(picocolors_1.default.red(`Error: Failed to fetch remote skills for ${category}. ${error}`));
-            }
-        } // End category loop
+        }
         return collected;
     }
     async writeToTargets(skills, config) {
@@ -217,16 +125,12 @@ class SyncCommand {
                 continue;
             const basePath = agentDef.path;
             if (basePath) {
-                // We do NOT use emptyDir here because we want to preserve user's own custom skills
                 await fs_extra_1.default.ensureDir(basePath);
                 for (const skill of skills) {
-                    // Use nested structure: category/skill (e.g. flutter/bloc)
                     const skillPath = path_1.default.join(basePath, skill.category, skill.skill);
                     await fs_extra_1.default.ensureDir(skillPath);
                     for (const fileItem of skill.files) {
                         const targetFilePath = path_1.default.join(skillPath, fileItem.name);
-                        // Check if this specific file is in custom_overrides
-                        // Supports both specific files and entire folders
                         const relativePath = path_1.default
                             .relative(process.cwd(), targetFilePath)
                             .replace(/\\/g, '/');
@@ -236,7 +140,14 @@ class SyncCommand {
                                 relativePath.startsWith(`${overridePath.replace(/\/$/, '')}/`));
                         });
                         if (isOverridden) {
-                            console.log(picocolors_1.default.yellow(`    ⚠️  Skipping overridden item: ${relativePath}`));
+                            console.log(picocolors_1.default.yellow(`    ⚠️  Skipping overridden: ${relativePath}`));
+                            continue;
+                        }
+                        // SECURITY: Path Traversal Check
+                        const resolvedTarget = path_1.default.resolve(targetFilePath);
+                        const resolvedBase = path_1.default.resolve(skillPath);
+                        if (!resolvedTarget.startsWith(resolvedBase)) {
+                            console.log(picocolors_1.default.red(`    ❌ Security Error: Invalid path ${fileItem.name}`));
                             continue;
                         }
                         await fs_extra_1.default.outputFile(targetFilePath, fileItem.content);