@stacksjs/skills 0.70.163 → 0.70.165

package/README.md

@@ -353,7 +353,7 @@ For help, discussion about best practices, or any other conversation that would
 
 For casual chit-chat with others using this package:
 
-[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+[Join the Stacks Discord Server](https://stacksjs.com/discord)
 
 ## Postcardware
 

package/dist/index.d.ts

@@ -1,2 +1,10 @@
-export type { Skill, SkillMetadata, SkillManifest } from './types';
-export { listSkills, getSkill, validateSkill, loadSkillMetadata } from './skills';
+export type { Skill, SkillManifest, SkillMetadata } from './types';
+export {
+  bundledSkillsPath,
+  getSkill,
+  listSkills,
+  loadSkillMetadata,
+  projectSkillsPath,
+  resolveSkillPath,
+  validateSkill,
+} from './skills';

package/dist/index.js

@@ -1 +1,9 @@
-export { listSkills, getSkill, validateSkill, loadSkillMetadata } from "./skills";
+export {
+  bundledSkillsPath,
+  getSkill,
+  listSkills,
+  loadSkillMetadata,
+  projectSkillsPath,
+  resolveSkillPath,
+  validateSkill
+} from "./skills";

package/dist/skills.d.ts

@@ -1,5 +1,28 @@
 import type { Skill, SkillMetadata } from './types';
+/**
+ * Every available skill name, sorted, with project skills shadowing bundled
+ * ones of the same name rather than appearing twice.
+ */
 export declare function listSkills(): string[];
 export declare function getSkill(name: string): Skill | null;
 export declare function loadSkillMetadata(name: string): SkillMetadata | null;
+/**
+ * Checks a skill against the agentskills.io frontmatter rules.
+ */
 export declare function validateSkill(name: string): { valid: boolean, errors: string[] };
+/**
+ * The directory the framework's own skills ship from. `buddy setup:ai` reads it;
+ * nothing should write into it.
+ */
+export declare function bundledSkillsPath(): string;
+/**
+ * The directory a project puts its own skills in. Searched before
+ * {@link bundledSkillsPath}, so a skill here shadows a bundled one of the same
+ * name.
+ */
+export declare function projectSkillsPath(): string;
+/**
+ * Resolves a skill to its directory on disk, or `null` if no source has it.
+ * Exposed so `buddy setup:ai` can link/copy the winning directory per skill.
+ */
+export declare function resolveSkillPath(name: string): string | null;

package/dist/skills.js

@@ -1,6 +1,19 @@
-import { join, resolve } from "@stacksjs/path";
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-const SKILLS_DIR = resolve(join(import.meta.dir, "..", "..", "..", "..", "..", ".claude", "skills"));
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { appPath, frameworkPath, join } from "@stacksjs/path";
+function skillSources() {
+  return [
+    appPath("Skills"),
+    frameworkPath("defaults/ai/skills")
+  ];
+}
+function resolveSkillDir(name) {
+  for (const source of skillSources()) {
+    const dir = join(source, name);
+    if (existsSync(join(dir, "SKILL.md")))
+      return dir;
+  }
+  return null;
+}
 function parseFrontmatter(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
   if (!match)
@@ -20,42 +33,42 @@ function parseFrontmatter(content) {
   return { metadata, body: body ?? "" };
 }
 export function listSkills() {
-  if (!existsSync(SKILLS_DIR))
-    return [];
-  return readdirSync(SKILLS_DIR).filter((entry) => {
-    const entryPath = join(SKILLS_DIR, entry);
-    return statSync(entryPath).isDirectory() && existsSync(join(entryPath, "SKILL.md"));
-  });
+  const names = new Set;
+  for (const source of skillSources()) {
+    if (!existsSync(source))
+      continue;
+    for (const entry of readdirSync(source)) {
+      const entryPath = join(source, entry);
+      if (statSync(entryPath).isDirectory() && existsSync(join(entryPath, "SKILL.md")))
+        names.add(entry);
+    }
+  }
+  return [...names].sort();
 }
 export function getSkill(name) {
-  const skillPath = join(SKILLS_DIR, name, "SKILL.md");
-  if (!existsSync(skillPath))
+  const skillDir = resolveSkillDir(name);
+  if (!skillDir)
     return null;
-  const content = readFileSync(skillPath, "utf-8"), { metadata, body } = parseFrontmatter(content), skillDir = join(SKILLS_DIR, name), scripts = existsSync(join(skillDir, "scripts")) ? readdirSync(join(skillDir, "scripts")) : [], references = existsSync(join(skillDir, "references")) ? readdirSync(join(skillDir, "references")) : [], assets = existsSync(join(skillDir, "assets")) ? readdirSync(join(skillDir, "assets")) : [];
+  const skillPath = join(skillDir, "SKILL.md"), content = readFileSync(skillPath, "utf-8"), { metadata, body } = parseFrontmatter(content), listDir = (dir) => existsSync(join(skillDir, dir)) ? readdirSync(join(skillDir, dir)) : [];
   return {
     metadata,
     instructions: body,
     path: skillPath,
-    scripts,
-    references,
-    assets
+    scripts: listDir("scripts"),
+    references: listDir("references"),
+    assets: listDir("assets")
   };
 }
 export function loadSkillMetadata(name) {
   return getSkill(name)?.metadata ?? null;
 }
 export function validateSkill(name) {
-  const errors = [], skillDir = join(SKILLS_DIR, name);
-  if (!existsSync(skillDir)) {
-    errors.push(`Skill directory not found: ${skillDir}`);
+  const errors = [], skillDir = resolveSkillDir(name);
+  if (!skillDir) {
+    errors.push(`Skill not found in any source: ${skillSources().map((source) => join(source, name)).join(", ")}`);
     return { valid: !1, errors };
   }
-  const skillPath = join(skillDir, "SKILL.md");
-  if (!existsSync(skillPath)) {
-    errors.push(`SKILL.md not found in ${skillDir}`);
-    return { valid: !1, errors };
-  }
-  const content = readFileSync(skillPath, "utf-8"), { metadata } = parseFrontmatter(content);
+  const content = readFileSync(join(skillDir, "SKILL.md"), "utf-8"), { metadata } = parseFrontmatter(content);
   if (!metadata.name)
     errors.push("Missing required field: name");
   else {
@@ -72,3 +85,12 @@ export function validateSkill(name) {
     errors.push("Description must be 1-1024 characters");
   return { valid: errors.length === 0, errors };
 }
+export function bundledSkillsPath() {
+  return frameworkPath("defaults/ai/skills");
+}
+export function projectSkillsPath() {
+  return appPath("Skills");
+}
+export function resolveSkillPath(name) {
+  return resolveSkillDir(name);
+}

package/package.json

@@ -2,8 +2,8 @@
   "name": "@stacksjs/skills",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.163",
-  "description": "Agent skills for the Stacks framework, following the agentskills.io standard.",
+  "version": "0.70.165",
+  "description": "Reads the Stacks framework's agent skills, following the agentskills.io standard. The skills themselves ship in storage/framework/defaults/ai/skills.",
   "author": "Chris Breuer",
   "contributors": [
     "Chris Breuer <chris@stacksjs.com>"
@@ -45,8 +45,7 @@
   "types": "dist/index.d.ts",
   "files": [
     "README.md",
-    "dist",
-    "skills"
+    "dist"
   ],
   "scripts": {
     "build": "bun build.ts",
@@ -54,11 +53,11 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/path": "0.70.163",
-    "@stacksjs/storage": "0.70.163"
+    "@stacksjs/path": "0.70.165",
+    "@stacksjs/storage": "0.70.165"
   },
   "devDependencies": {
     "better-dx": "^0.2.17",
-    "@stacksjs/types": "0.70.163"
+    "@stacksjs/types": "0.70.165"
   }
 }