agent-skills-standard 1.7.2 → 1.8.0

package/README.md

@@ -82,7 +82,8 @@ Every skill delivered by this CLI is audited for its footprint in the AI's conte
 
 | Version | Date | Skills | Avg Tokens | Savings (%) | Report |
 | --- | --- | --- | --- | --- | --- |
-| v1.7.3 | 2026-02-25 | 220 | 413 | 89% | [Report](benchmarks/archive/v1.7.3.md) |
+| v1.8.0 | 2026-03-02 | 228 | 443 | 88% | [Report](benchmarks/archive/v1.8.0.md) |
+| v1.7.3 | 2026-02-25 | 222 | 418 | 89% | [Report](benchmarks/archive/v1.7.3.md) |
 | v1.7.2 | 2026-02-25 | 220 | 413 | 89% | [Report](benchmarks/archive/v1.7.2.md) |
 
 ## � Token Economy & Optimization

package/dist/index.js

@@ -267,56 +267,68 @@ const SKILL_DETECTION_REGISTRY = {
   [Framework.Android]: [
     {
       id: "compose",
-      packages: ["androidx.compose.ui"]
+      packages: ["androidx.compose.ui"],
+      files: ["android", "build.gradle", "build.gradle.kts"]
     },
     {
       id: "navigation",
-      packages: ["androidx.navigation:navigation-compose"]
+      packages: ["androidx.navigation:navigation-compose"],
+      files: ["android", "build.gradle", "build.gradle.kts"]
     },
     {
       id: "legacy-navigation",
       packages: [
         "androidx.navigation:navigation-fragment",
         "androidx.navigation:navigation-ui"
-      ]
+      ],
+      files: ["android", "build.gradle", "build.gradle.kts"]
     },
     {
       id: "di",
-      packages: ["hilt-android", "dagger-android"]
+      packages: ["hilt-android", "dagger-android"],
+      files: ["android", "build.gradle", "build.gradle.kts"]
     },
     {
       id: "persistence",
-      packages: ["androidx.room:room-runtime"]
+      packages: ["androidx.room:room-runtime"],
+      files: ["android", "build.gradle", "build.gradle.kts"]
     },
     {
       id: "networking",
-      packages: ["retrofit"]
+      packages: ["retrofit"],
+      files: ["android", "build.gradle", "build.gradle.kts"]
     },
     {
       id: "concurrency",
-      packages: ["kotlinx-coroutines-android"]
+      packages: ["kotlinx-coroutines-android"],
+      files: ["android", "build.gradle", "build.gradle.kts"]
     }
   ],
   [Framework.iOS]: [
     {
       id: "networking",
-      packages: ["Alamofire", "Moya"]
+      packages: ["Alamofire", "Moya"],
+      files: ["ios", "Podfile", "Package.swift"]
     },
     {
       id: "dependency-injection",
-      packages: ["Swinject", "Resolver"]
+      packages: ["Swinject", "Resolver"],
+      files: ["ios", "Podfile", "Package.swift"]
     },
     {
       id: "persistence",
-      packages: ["Realm", "CoreData", "SQLite.swift"]
+      packages: ["Realm", "CoreData", "SQLite.swift"],
+      files: ["ios", "Podfile", "Package.swift"]
     },
     {
       id: "state-management",
-      packages: ["ComposableArchitecture", "CombineRuntime"]
+      packages: ["ComposableArchitecture", "CombineRuntime"],
+      files: ["ios", "Podfile", "Package.swift"]
     },
     {
       id: "ui-navigation",
-      packages: ["Coordinator", "Router"]
+      packages: ["Coordinator", "Router"],
+      files: ["ios", "Podfile", "Package.swift"]
     }
   ],
   [Framework.ReactNative]: [
@@ -364,6 +376,65 @@ const SKILL_DETECTION_REGISTRY = {
       // Always present, but used for sub-skill mapping
     }
   ],
+  [Framework.NextJS]: [
+    {
+      id: "pages-router",
+      packages: [],
+      files: ["pages", "src/pages"]
+    },
+    {
+      id: "server-components",
+      packages: [],
+      files: ["app", "src/app"]
+    },
+    {
+      id: "server-actions",
+      packages: [],
+      files: ["app", "src/app"]
+    },
+    {
+      id: "data-fetching",
+      packages: [],
+      files: ["app", "src/app"]
+    },
+    {
+      id: "i18n",
+      packages: ["next-intl", "react-intl", "next-translate", "i18next"],
+      files: [
+        "middleware.ts",
+        "app/[lang]",
+        "pages/[locale]",
+        "next.config.js"
+      ]
+    }
+  ],
+  [Framework.React]: [
+    {
+      id: "styling",
+      packages: ["tailwind", "antd", "sass", "styled-components", "emotion"]
+    },
+    {
+      id: "state-management",
+      packages: [
+        "redux",
+        "@reduxjs/toolkit",
+        "zustand",
+        "mobx",
+        "recoil",
+        "jotai"
+      ]
+    },
+    {
+      id: "testing",
+      packages: [
+        "jest",
+        "vitest",
+        "@testing-library/react",
+        "cypress",
+        "playwright"
+      ]
+    }
+  ],
   database: [
     {
       id: "postgresql",
@@ -385,11 +456,38 @@ const BACKEND_FRAMEWORKS = [
   Framework.SpringBoot,
   Framework.Laravel
 ];
+const FRONTEND_FRAMEWORKS = [
+  Framework.React,
+  Framework.NextJS,
+  Framework.Angular
+];
+const MOBILE_FRAMEWORKS = [
+  Framework.Flutter,
+  Framework.Android,
+  Framework.iOS,
+  Framework.ReactNative
+];
+const FRONTEND_REACT_FRAMEWORKS = [
+  Framework.NextJS,
+  Framework.ReactNative
+];
+const COMMON_SKILL_EXCLUDES = {
+  backend: ["accessibility", "mobile-animation", "mobile-ux-core"],
+  frontend: ["observability", "mobile-animation", "mobile-ux-core"],
+  mobile: ["accessibility", "api-design", "observability"]
+};
+function getFrameworkType(framework) {
+  if (BACKEND_FRAMEWORKS.includes(framework)) return "backend";
+  if (MOBILE_FRAMEWORKS.includes(framework)) return "mobile";
+  if (FRONTEND_FRAMEWORKS.includes(framework)) return "frontend";
+  return null;
+}
 const DEFAULT_REGISTER = "https://github.com/HoangNguyen0403/agent-skills-standard";
 const DEFAULT_WORKFLOWS = [
   "code-review",
   "codebase-review",
-  "plan-feature"
+  "plan-feature",
+  "skill-benchmark"
 ];
 const getAgentDefinition = (id) => {
   switch (id) {
@@ -701,8 +799,10 @@ class ConfigService {
     skills[framework] = {
       ref: metadata.categories?.[framework]?.version ? `${metadata.categories[framework].tag_prefix || ""}${metadata.categories[framework].version}` : "main"
     };
-    if (framework === "react-native" && metadata.categories?.["react"]) {
-      skills[framework].include = ["react/hooks", "react/component-patterns"];
+    if (FRONTEND_REACT_FRAMEWORKS.includes(framework) && metadata.categories?.["react"]) {
+      skills["react"] = {
+        ref: metadata.categories["react"].version ? `${metadata.categories["react"].tag_prefix || ""}${metadata.categories["react"].version}` : "main"
+      };
     }
     for (const lang of languages) {
       if (metadata.categories?.[lang]) {
@@ -712,8 +812,11 @@ class ConfigService {
       }
     }
     if (metadata.categories?.["common"]) {
+      const frameworkType = getFrameworkType(framework);
+      const commonExcludes = frameworkType ? COMMON_SKILL_EXCLUDES[frameworkType] : [];
       skills["common"] = {
-        ref: `${metadata.categories["common"].tag_prefix || ""}${metadata.categories["common"].version}`
+        ref: `${metadata.categories["common"].tag_prefix || ""}${metadata.categories["common"].version}`,
+        ...commonExcludes.length > 0 && { exclude: commonExcludes }
       };
     }
     if (BACKEND_FRAMEWORKS.includes(framework) && metadata.categories?.["database"]) {
@@ -736,7 +839,7 @@ class ConfigService {
    * @param config The current configuration
    * @param projectDeps Current set of project dependencies
    */
-  applyDependencyExclusions(config, projectDeps) {
+  applyDependencyExclusions(config, projectDeps, cwd = process.cwd()) {
     const depsArray = Array.from(projectDeps);
     for (const categoryId in config.skills) {
       const category = config.skills[categoryId];
@@ -744,7 +847,9 @@ class ConfigService {
       if (detections.length === 0) continue;
       const exclusions = new Set(category.exclude || []);
       for (const detection of detections) {
-        if (!this.hasDependency(detection.packages, depsArray)) {
+        const hasDeps = this.hasDependency(detection.packages, depsArray);
+        const hasDirs = this.hasFiles(detection.files, cwd);
+        if (!hasDeps || !hasDirs) {
           exclusions.add(detection.id);
         }
       }
@@ -757,7 +862,7 @@ class ConfigService {
    * Automatically re-enables skills that were previously excluded if their dependencies
    * are now present in the project. Scans all categories.
    */
-  reconcileDependencies(config, projectDeps) {
+  reconcileDependencies(config, projectDeps, cwd = process.cwd()) {
     const totalReenabled = [];
     const allKnownCategories = Object.keys(SKILL_DETECTION_REGISTRY);
     const depsArray = Array.from(projectDeps);
@@ -767,13 +872,25 @@ class ConfigService {
       if (detections.length === 0) continue;
       const isNewCategory = !category;
       if (isNewCategory) {
+        const frameworkDef = SUPPORTED_FRAMEWORKS.find(
+          (f) => f.id === categoryId
+        );
+        if (frameworkDef) {
+          const hasBaseDeps = frameworkDef.detectionDependencies ? this.hasDependency(frameworkDef.detectionDependencies, depsArray) : true;
+          const hasBaseFiles = this.hasFiles(frameworkDef.detectionFiles, cwd);
+          if (!hasBaseDeps && !hasBaseFiles) {
+            continue;
+          }
+        }
         const shouldEnableCategory = detections.some(
-          (detection) => this.hasDependency(detection.packages, depsArray)
+          (detection) => this.hasDependency(detection.packages, depsArray) && this.hasFiles(detection.files, cwd)
         );
         if (shouldEnableCategory) {
           config.skills[categoryId] = { ref: "main" };
           category = config.skills[categoryId];
-          const exclusions = detections.filter((d) => !this.hasDependency(d.packages, depsArray)).map((d) => d.id);
+          const exclusions = detections.filter(
+            (d) => !this.hasDependency(d.packages, depsArray) || !this.hasFiles(d.files, cwd)
+          ).map((d) => d.id);
           if (exclusions.length > 0) {
             category.exclude = exclusions;
           }
@@ -785,7 +902,7 @@ class ConfigService {
       const currentExclusions = new Set(category.exclude);
       const reenabled = [];
       for (const detection of detections) {
-        if (currentExclusions.has(detection.id) && this.hasDependency(detection.packages, depsArray)) {
+        if (currentExclusions.has(detection.id) && this.hasDependency(detection.packages, depsArray) && this.hasFiles(detection.files, cwd)) {
           currentExclusions.delete(detection.id);
           reenabled.push(`${categoryId}/${detection.id}`);
         }
@@ -798,14 +915,32 @@ class ConfigService {
     return totalReenabled;
   }
   /**
-   * Checks if any of the provided packages are present in the project dependencies.
+   * Checks if ANY of the required files exist in the project directory.
+   */
+  hasFiles(files, cwd) {
+    if (!files || files.length === 0) return true;
+    for (const file of files) {
+      if (fs.existsSync(path.join(cwd, file))) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Checks if ANY of the required dependencies are found in the project.
    */
   hasDependency(packages, projectDeps) {
+    if (packages.length === 0) return true;
     return projectDeps.some(
       (d) => packages.some((pkg2) => {
         const depLower = d.toLowerCase();
         const pkgLower = pkg2.toLowerCase();
-        return pkg2.length <= 3 ? depLower === pkgLower : depLower.includes(pkgLower);
+        if (depLower === pkgLower) return true;
+        if (pkg2.length <= 3) return false;
+        if (depLower.includes("/") && depLower.split("/").pop() === pkgLower)
+          return true;
+        const parts = depLower.split(/[-/_]/);
+        return parts.includes(pkgLower);
       })
     );
   }
@@ -1512,7 +1647,11 @@ class AgentBridgeService {
       "> [!IMPORTANT]",
       "> ALWAYS consult the consolidated index in **AGENTS.md** to identify relevant triggers before acting.",
       "",
-      "The `AGENTS.md` file contains mapping between project files and the specific agent skills located in the respective agent-specific folders (e.g., `.cursor/skills`, `.claude/skills`)."
+      "The `AGENTS.md` file contains mapping between project files and the specific agent skills located in the respective agent-specific folders (e.g., `.cursor/skills`, `.claude/skills`).",
+      "",
+      "## Self-Learning Protocol",
+      "",
+      "At the end of any multi-step task with user corrections, load and run **[common/session-retrospective](/skills/common/session-retrospective/SKILL.md)** to capture skill gaps and prevent repeat rework."
     ].join("\n");
     for (const agentId of agents) {
       const config = getAgentDefinition(agentId);
@@ -1557,6 +1696,20 @@ applyTo: "**/*"
   }
 }
 class IndexGeneratorService {
+  /**
+   * Loads foundational composite rules from the registry's metadata.json.
+   * Falls back to an empty map if the file is missing or malformed.
+   */
+  async loadFoundationalRules(baseDir) {
+    try {
+      const metaPath = path.join(baseDir, "metadata.json");
+      const raw = await fs.readFile(metaPath, "utf8");
+      const parsed = JSON.parse(raw);
+      return parsed.foundational_composite_rules ?? {};
+    } catch {
+      return {};
+    }
+  }
   /**
    * Generates a markdown index of available skills across multiple categories.
    * @param baseDir The base directory containing categories and skills
@@ -1566,6 +1719,7 @@ class IndexGeneratorService {
   async generate(baseDir, frameworks) {
     const categories = Array.from(/* @__PURE__ */ new Set(["common", ...frameworks]));
     const entries = /* @__PURE__ */ new Set();
+    const foundationalRules = await this.loadFoundationalRules(baseDir);
     for (const category of categories) {
       const categoryPath = path.join(baseDir, category);
       if (!await fs.pathExists(categoryPath)) continue;
@@ -1575,7 +1729,12 @@ class IndexGeneratorService {
         if (!await fs.pathExists(skillPath)) continue;
         const metadata = await this.parseSkill(skillPath);
         if (metadata) {
-          const entry = this.formatEntry(category, skill, metadata);
+          const entry = this.formatEntry(
+            category,
+            skill,
+            metadata,
+            foundationalRules
+          );
           entries.add(entry);
         }
       }
@@ -1601,6 +1760,13 @@ class IndexGeneratorService {
       "",
       "- **Skill Authority:** Loaded skills always override existing code patterns.",
       "- **Audit Before Write:** Audit every file write against the `common/feedback-reporter` skill.",
+      "",
+      "## **Reading This Index**",
+      "",
+      "Each entry lists `(triggers: ...)` conditions. Three trigger types:",
+      "- **File globs** (`**/*.ts`) — activate when working with matching files.",
+      "- **Keywords** (`auth`, `refactor`) — activate when these appear in the task.",
+      "- **Composite** (`+other/skill`) — activate THIS skill whenever `other/skill` is also active. Used by foundational skills to co-load with their framework peers automatically.",
       ""
     ].join("\n");
     return `${header}
@@ -1628,13 +1794,36 @@ ${entries.join("\n")}
       return null;
     }
   }
-  formatEntry(category, skill, metadata) {
+  /**
+   * Derives foundational composite IDs for a skill based on registry-owned naming rules.
+   * Only applies to non-common skills. Deduplicates against explicit composites.
+   */
+  deriveFoundationalComposites(category, skill, explicitComposites, rules) {
+    if (category === "common") return [];
+    const derived = [];
+    for (const [foundational, patterns] of Object.entries(rules)) {
+      const matches = patterns.some((p) => skill.includes(p));
+      if (matches && !explicitComposites.includes(foundational)) {
+        derived.push(foundational);
+      }
+    }
+    return derived;
+  }
+  formatEntry(category, skill, metadata, foundationalRules = {}) {
     const id = `${category}/${skill}`;
     const prefix = metadata.priority.startsWith("P0") ? "🚨 " : "";
+    const explicitComposites = metadata.triggers.composite || [];
+    const autoComposites = this.deriveFoundationalComposites(
+      category,
+      skill,
+      explicitComposites,
+      foundationalRules
+    );
+    const allComposites = [...explicitComposites, ...autoComposites];
     const triggers = [
       ...metadata.triggers.files || [],
       ...metadata.triggers.keywords || [],
-      ...metadata.triggers.composite ? metadata.triggers.composite.map((c) => `+${c}`) : [],
+      ...allComposites.length ? allComposites.map((c) => `+${c}`) : [],
       ...metadata.triggers.exclude ? metadata.triggers.exclude.map((e) => `!${e}`) : []
     ].join(", ");
     const triggerText = triggers ? ` (triggers: ${triggers})` : "";
@@ -1755,10 +1944,13 @@ class SyncService {
     } else if (config.workflows === void 0 || config.workflows === true) {
       const agents2 = await this.resolveTargetAgents(config);
       if (agents2.includes(Agent.Antigravity)) {
-        config.workflows = availableWorkflows;
+        const defaultWorkflows = availableWorkflows.filter(
+          (wf) => DEFAULT_WORKFLOWS.includes(wf)
+        );
+        config.workflows = defaultWorkflows;
         console.log(
           pc.yellow(
-            `✨ Workflows Initialized: Adding [${availableWorkflows.join(", ")}] to .skillsrc.`
+            `✨ Workflows Initialized: Adding [${defaultWorkflows.join(", ")}] to .skillsrc.`
           )
         );
         changed = true;
@@ -2188,7 +2380,7 @@ class SyncCommand {
     }
   }
 }
-const version = "1.7.2";
+const version = "1.8.0";
 const pkg = {
   version
 };
@@ -2706,7 +2898,7 @@ dotenv.config();
 const program = new commander.Command();
 program.name("agent-skills-standard").description(
   "A CLI to manage and sync AI agent skills for Cursor, Claude, Copilot, Windsurf, and more."
-).version("1.7.2");
+).version("1.8.0");
 program.command("init").description("Initialize a .skillsrc configuration file interactively").action(async () => {
   const init = new InitCommand();
   await init.run();