agent-skills-standard 2.4.7 → 2.5.0

package/README.md

@@ -126,6 +126,7 @@ The CLI **never** modifies user-home files (`~/.cursor/mcp.json`, `~/.gemini/set
 
 | Version | Date | Skills | Avg Tokens | Savings (%) | Report |
 | --- | --- | --- | --- | --- | --- |
+| v2.4.7 | 2026-06-15 | 251 | 551 | 85% | [Report](benchmarks/archive/v2.4.7.md) |
 | v2.4.6 | 2026-06-10 | 251 | 548 | 85% | [Report](benchmarks/archive/v2.4.6.md) |
 | v2.4.1 | 2026-05-18 | 247 | 540 | 85% | [Report](benchmarks/archive/v2.4.1.md) |
 | v2.4.0 | 2026-05-14 | 246 | 540 | 85% | [Report](benchmarks/archive/v2.4.0.md) |
@@ -135,4 +136,3 @@ The CLI **never** modifies user-home files (`~/.cursor/mcp.json`, `~/.gemini/set
 | v2.1.2 | 2026-04-11 | 237 | 516 | 86% | [Report](benchmarks/archive/v2.1.2.md) |
 | v2.1.1 | 2026-04-11 | 237 | 516 | 86% | [Report](benchmarks/archive/v2.1.1.md) |
 | v2.1.0 | 2026-04-04 | 237 | 526 | 86% | [Report](benchmarks/archive/v2.1.0.md) |
-| v2.0.1 | 2026-03-30 | 238 | 527 | 86% | [Report](benchmarks/archive/v2.0.1.md) |

package/dist/index.js

@@ -43,7 +43,7 @@ let child_process = require("child_process");
 let fs = require("fs");
 var package_default = {
 	name: "agent-skills-standard",
-	version: "2.4.7",
+	version: "2.5.0",
 	description: "A CLI to manage and sync AI agent skills standard for Cursor, Claude, Copilot, Windsurf, and more.",
 	main: "dist/index.js",
 	bin: {
@@ -83,7 +83,7 @@ var package_default = {
 		"dotenv": "^17.2.3",
 		"fs-extra": "^11.2.0",
 		"inquirer": "^8.2.5",
-		"js-yaml": "^4.1.0",
+		"js-yaml": "^4.2.0",
 		"picocolors": "^1.0.0",
 		"zod": "^3.22.4"
 	},
@@ -1042,11 +1042,181 @@ var SkillConfigSchema = zod.z.object({
 	mcp: McpConfigSchema.optional()
 });
 var DEFAULT_SDLC_SUPPORT_CATEGORIES = ["quality-engineering"];
+var PRIMARY_CONFIG_FILE = ".skillsrc";
+var LEGACY_YAML_CONFIG_FILE = ".skillsrc.yaml";
 /**
 * Service for managing the `.skillsrc` configuration file.
 * Handles loading, saving, and initial construction of the configuration based on project metadata.
 */
 var ConfigService = class {
+	getPrimaryConfigPath(cwd) {
+		return path.default.join(cwd, PRIMARY_CONFIG_FILE);
+	}
+	getLegacyYamlConfigPath(cwd) {
+		return path.default.join(cwd, LEGACY_YAML_CONFIG_FILE);
+	}
+	async resolveConfigPath(cwd) {
+		const primaryPath = this.getPrimaryConfigPath(cwd);
+		if (await fs_extra.default.pathExists(primaryPath)) return primaryPath;
+		const legacyYamlPath = this.getLegacyYamlConfigPath(cwd);
+		if (await fs_extra.default.pathExists(legacyYamlPath)) return legacyYamlPath;
+		return null;
+	}
+	dumpConfig(config) {
+		return js_yaml.default.dump(config, {
+			noRefs: true,
+			lineWidth: -1
+		});
+	}
+	isRecord(value) {
+		return typeof value === "object" && value !== null && !Array.isArray(value);
+	}
+	stripAngleBrackets(value) {
+		const trimmed = value.trim();
+		if (trimmed.startsWith("<") && trimmed.endsWith(">")) return trimmed.slice(1, -1).trim();
+		return trimmed;
+	}
+	parseLegacyList(value) {
+		const trimmed = value.trim();
+		if (!trimmed || trimmed === "[]") return [];
+		if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed.slice(1, -1).split(",").map((item) => item.trim()).filter(Boolean);
+		if (trimmed.startsWith("- ")) return trimmed.replace(/^-\s+/, "").split(/\s+-\s+/).map((item) => item.trim()).filter(Boolean);
+		return trimmed.split(",").map((item) => item.trim()).filter(Boolean);
+	}
+	parseLegacyBoolean(value) {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "true") return true;
+		if (normalized === "false") return false;
+	}
+	migrateLegacyTextConfig(content) {
+		const lines = content.split(/\r?\n/);
+		const registryLine = lines.find((line) => line.trim().startsWith("registry:"));
+		const agentsIndex = lines.findIndex((line) => line.trim() === "agents:");
+		const skillsIndex = lines.findIndex((line) => line.trim() === "skills:");
+		if (!registryLine || agentsIndex === -1 || skillsIndex === -1) return null;
+		const registryMatch = registryLine.match(/^\s*registry:\s*(.+)$/);
+		if (!registryMatch) return null;
+		const config = {
+			registry: this.stripAngleBrackets(registryMatch[1]),
+			agents: [],
+			skills: {}
+		};
+		const agents = [];
+		for (let index = agentsIndex + 1; index < skillsIndex; index += 1) {
+			const match = lines[index].match(/^\s*-\s+(.+)$/);
+			if (!match) continue;
+			agents.push(match[1].trim());
+		}
+		config.agents = agents;
+		const sectionNames = new Set([
+			"custom_overrides",
+			"workflows",
+			"mcp"
+		]);
+		let currentCategory = null;
+		for (let index = skillsIndex + 1; index < lines.length; index += 1) {
+			const trimmed = lines[index].trim();
+			if (!trimmed) continue;
+			if (trimmed === "workflows:" || trimmed === "mcp:" || trimmed.startsWith("custom_overrides:")) break;
+			const categoryMatch = trimmed.match(/^([A-Za-z0-9-]+):$/);
+			if (categoryMatch && !sectionNames.has(categoryMatch[1])) {
+				currentCategory = categoryMatch[1];
+				config.skills[currentCategory] = {};
+				continue;
+			}
+			if (!currentCategory) continue;
+			const refMatch = trimmed.match(/^ref:\s*(.+)$/);
+			if (refMatch) {
+				config.skills[currentCategory].ref = refMatch[1].trim();
+				continue;
+			}
+			const excludeMatch = trimmed.match(/^exclude:\s*(.+)$/);
+			if (excludeMatch) {
+				config.skills[currentCategory].exclude = this.parseLegacyList(excludeMatch[1]);
+				continue;
+			}
+			const includeMatch = trimmed.match(/^include:\s*(.+)$/);
+			if (includeMatch) config.skills[currentCategory].include = this.parseLegacyList(includeMatch[1]);
+		}
+		const overridesLine = lines.find((line) => line.trim().startsWith("custom_overrides:"));
+		if (overridesLine) {
+			const match = overridesLine.match(/^\s*custom_overrides:\s*(.*)$/);
+			config.custom_overrides = this.parseLegacyList(match?.[1] ?? "");
+		}
+		const workflowsIndex = lines.findIndex((line) => line.trim() === "workflows:");
+		if (workflowsIndex !== -1) {
+			const workflows = [];
+			for (let index = workflowsIndex + 1; index < lines.length; index += 1) {
+				const trimmed = lines[index].trim();
+				if (!trimmed) continue;
+				if (trimmed === "mcp:") break;
+				const match = trimmed.match(/^-\s+(.+)$/);
+				if (match) workflows.push(match[1].trim());
+			}
+			config.workflows = workflows;
+		}
+		const mcpIndex = lines.findIndex((line) => line.trim() === "mcp:");
+		if (mcpIndex !== -1) {
+			const mcp = {};
+			for (let index = mcpIndex + 1; index < lines.length; index += 1) {
+				const trimmed = lines[index].trim();
+				if (!trimmed) continue;
+				const match = trimmed.match(/^([A-Za-z0-9_]+):\s*(.+)$/);
+				if (!match) continue;
+				const [, key, rawValue] = match;
+				if (key === "enabled" || key === "prompted" || key === "snippets") mcp[key] = this.parseLegacyBoolean(rawValue);
+				else mcp[key] = rawValue.trim();
+			}
+			config.mcp = mcp;
+		}
+		return config;
+	}
+	normalizeRawConfig(rawConfig) {
+		if (!this.isRecord(rawConfig)) return {
+			config: {},
+			migrated: false
+		};
+		const normalized = { ...rawConfig };
+		let migrated = false;
+		if (typeof normalized.registry === "string") {
+			const strippedRegistry = this.stripAngleBrackets(normalized.registry);
+			if (strippedRegistry !== normalized.registry) {
+				normalized.registry = strippedRegistry;
+				migrated = true;
+			}
+		}
+		if (Array.isArray(normalized.agents)) normalized.agents = normalized.agents.map((agent) => {
+			if (typeof agent === "string" && agent.toLowerCase() === "openai") {
+				migrated = true;
+				return Agent.Codex;
+			}
+			return agent;
+		});
+		if (this.isRecord(normalized.skills)) {
+			const normalizedSkills = {};
+			for (const [category, value] of Object.entries(normalized.skills)) {
+				if (!this.isRecord(value)) {
+					normalizedSkills[category] = {};
+					migrated = true;
+					continue;
+				}
+				const entry = {};
+				if (typeof value.ref === "string") entry.ref = value.ref;
+				if (Array.isArray(value.include)) entry.include = value.include.filter((item) => typeof item === "string");
+				if (Array.isArray(value.exclude)) entry.exclude = value.exclude.filter((item) => typeof item === "string");
+				else if (typeof value.exclude === "string") {
+					entry.exclude = this.parseLegacyList(value.exclude);
+					migrated = true;
+				}
+				normalizedSkills[category] = entry;
+			}
+			normalized.skills = normalizedSkills;
+		}
+		return {
+			config: normalized,
+			migrated
+		};
+	}
 	getCategoryRef(category, metadata) {
 		const categoryMetadata = metadata.categories?.[category];
 		if (!categoryMetadata?.version) return "main";
@@ -1059,27 +1229,26 @@ var ConfigService = class {
 	* @throws Error if the configuration format is invalid
 	*/
 	async loadConfig(cwd = process.cwd()) {
-		const configPath = path.default.join(cwd, ".skillsrc");
-		if (!await fs_extra.default.pathExists(configPath)) return null;
+		const configPath = await this.resolveConfigPath(cwd);
+		if (!configPath) return null;
+		const primaryConfigPath = this.getPrimaryConfigPath(cwd);
+		const shouldRenameLegacyYamlFile = configPath !== primaryConfigPath;
 		try {
 			const content = await fs_extra.default.readFile(configPath, "utf8");
-			const rawConfig = js_yaml.default.load(content);
-			if (rawConfig && Array.isArray(rawConfig.agents)) {
-				let needsMigration = false;
-				const updatedAgents = rawConfig.agents.map((agent) => {
-					if (typeof agent === "string" && agent.toLowerCase() === "openai") {
-						needsMigration = true;
-						return Agent.Codex;
-					}
-					return agent;
-				});
-				if (needsMigration) {
-					rawConfig.agents = updatedAgents;
-					await fs_extra.default.outputFile(configPath, js_yaml.default.dump(rawConfig));
-				}
+			let rawConfig;
+			let migratedFromText = false;
+			try {
+				rawConfig = js_yaml.default.load(content);
+			} catch (parseError) {
+				rawConfig = this.migrateLegacyTextConfig(content);
+				migratedFromText = rawConfig !== null;
+				if (!migratedFromText) throw parseError;
 			}
-			const parsed = SkillConfigSchema.safeParse(rawConfig);
+			const { config: normalizedConfig, migrated } = this.normalizeRawConfig(rawConfig);
+			const parsed = SkillConfigSchema.safeParse(normalizedConfig);
 			if (!parsed.success) throw new Error(`Invalid .skillsrc format: ${parsed.error.message}`);
+			if (migratedFromText || migrated || shouldRenameLegacyYamlFile) await fs_extra.default.outputFile(primaryConfigPath, this.dumpConfig(parsed.data));
+			if (shouldRenameLegacyYamlFile) await fs_extra.default.remove(configPath);
 			return parsed.data;
 		} catch (error) {
 			throw new Error(`Failed to load config: ${error}`);
@@ -1091,8 +1260,10 @@ var ConfigService = class {
 	* @param cwd Current working directory
 	*/
 	async saveConfig(config, cwd = process.cwd()) {
-		const configPath = path.default.join(cwd, ".skillsrc");
-		await fs_extra.default.outputFile(configPath, js_yaml.default.dump(config));
+		const primaryConfigPath = this.getPrimaryConfigPath(cwd);
+		const legacyYamlPath = this.getLegacyYamlConfigPath(cwd);
+		await fs_extra.default.outputFile(primaryConfigPath, this.dumpConfig(config));
+		if (legacyYamlPath !== primaryConfigPath && await fs_extra.default.pathExists(legacyYamlPath)) await fs_extra.default.remove(legacyYamlPath);
 	}
 	/**
 	* Constructs an initial configuration object based on project analysis.
@@ -1289,7 +1460,9 @@ process.stdin.on('end', () => {
       '[SKILL TRIGGER] Editing: ' + fileName + '\\n' +
       '-> Call load_skills_for_files(files=[ "' + filePath + '" ]) on the ' +
       'agent-skills-standard MCP. It returns applicable SKILL.md rules, ' +
-      'or nothing if no skills match this file type.'
+      'or nothing if no skills match this file type.\\n' +
+      '-> If this work spans a whole framework or migration, also call ' +
+      'get_category_guide(category="...") for the framework-level map.'
     );
     process.exit(0);
   } catch {