portable-agent-layer 0.58.0 → 0.59.0

package/assets/skills/create-skill/authoring-guide.md

@@ -12,7 +12,9 @@ the single source of truth for skill quality.
 
 3. **Concise and concrete.** Assume the model is already smart — only add what it doesn't already know. Every step has a verb and an object; no "as needed" or "appropriately." Keep the SKILL.md body well under 500 lines; push long reference material into sibling files linked one level deep.
 
-A personal skill **may** contain this user's own context — their paths, project names, preferences, conventions. That is the point of a personal skill.
+4. **Self-contained and portable.** Everything the skill needs lives inside its own folder — `SKILL.md` plus a `tools/` subdir for scripts and any reference files — so it travels intact on export/import. Don't reach into sibling skills or reference files outside the folder. Prefer `$HOME`/`~` or an env var over a hardcoded absolute path like `/Users/you/…` so the skill still works on another machine; `pal cli skill doctor` warns (never errors) on machine-specific absolute paths.
+
+A personal skill **may** contain this user's own context — their paths, project names, preferences, conventions. That is the point of a personal skill; portability (rule 4) is a preference, not a hard rule — a deliberate machine-specific mount is fine.
 
 ## Skill anatomy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/tools/skill-doctor.ts

@@ -10,7 +10,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
+import { basename, extname, relative, resolve } from "node:path";
 import { palHome } from "../hooks/lib/paths";
 
 type Level = "pass" | "warn" | "error";
@@ -41,6 +41,44 @@ const MAX_NAME = 64;
 const MAX_DESCRIPTION = 1024;
 const MAX_BODY_LINES = 500;
 
+/** File extensions worth scanning for hardcoded paths (SKILL.md + its scripts). */
+const SCANNABLE_EXT = new Set([".md", ".ts", ".js", ".mjs", ".cjs", ".sh", ".py"]);
+
+/** Machine/user-specific absolute paths that will not survive an export to
+ * another machine or user: POSIX home dirs and Windows user profiles. Portable
+ * forms ($HOME, ~, %USERPROFILE%, env vars) are deliberately not matched. */
+const ABSOLUTE_PATH_RE =
+  /(?:\/(?:Users|home)\/[A-Za-z0-9._-]+|\/root\/[A-Za-z0-9._-]|[A-Za-z]:\\Users\\[A-Za-z0-9._-]+)/;
+
+/** Collect SKILL.md and sibling script files, skipping vendored/VCS trees. */
+function collectSkillFiles(skillDir: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      const full = resolve(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && SCANNABLE_EXT.has(extname(entry.name))) out.push(full);
+    }
+  };
+  walk(skillDir);
+  return out;
+}
+
+/** Find machine-specific absolute paths across a skill's files. */
+function findAbsolutePaths(skillDir: string): string[] {
+  const hits: string[] = [];
+  for (const file of collectSkillFiles(skillDir)) {
+    const rel = relative(skillDir, file).replaceAll("\\", "/");
+    const lines = readFileSync(file, "utf-8").split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const m = ABSOLUTE_PATH_RE.exec(lines[i]);
+      if (m) hits.push(`${rel}:${i + 1} → ${m[0]}`);
+    }
+  }
+  return hits;
+}
+
 /** Split a SKILL.md into frontmatter fields and body. */
 function parseSkill(content: string): ParsedSkill {
   const parts = content.split(/^---\s*$/m);
@@ -238,6 +276,23 @@ export function lintSkill(skillDir: string): DoctorReport {
     ? add("warn", "paths", "Windows-style backslash path found — use forward slashes")
     : add("pass", "paths", "forward-slash paths");
 
+  // ── machine-specific absolute paths (portability) ──
+  // A personal skill MAY legitimately hardcode a machine-specific path (e.g. a
+  // cloud-mount vault), so this is a warning, never an error — it flags paths
+  // that will not survive being exported to another machine or user.
+  const absHits = findAbsolutePaths(skillDir);
+  if (absHits.length > 0) {
+    const shown = absHits.slice(0, 3).join("; ");
+    const more = absHits.length > 3 ? ` (+${absHits.length - 3} more)` : "";
+    add(
+      "warn",
+      "paths.absolute",
+      `hardcoded absolute path(s) that won't be portable across machines: ${shown}${more} — prefer $HOME/~ or an env var, or ignore if this is an intentional machine-specific mount`
+    );
+  } else {
+    add("pass", "paths.absolute", "no machine-specific absolute paths");
+  }
+
   const errors = findings.filter((f) => f.level === "error").length;
   const warnings = findings.filter((f) => f.level === "warn").length;
   return { dir: skillDir, name, findings, errors, warnings };