@ryanstark24/sfgraph-skills 1.1.0

package/dist/__tests__/cursor-format.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cursor-format.test.d.ts.map

package/dist/__tests__/cursor-format.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-format.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/cursor-format.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/cursor-format.test.js

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { toClaudeFormat, toCursorFormat } from "../installer.js";
+const SAMPLE = `---
+name: foo
+description: bar
+triggers:
+  - "x"
+tools_used:
+  - tool_a
+  - tool_b
+---
+
+# Body
+
+Some content.
+
+- bullet
+`;
+describe("format transforms", () => {
+    it("toCursorFormat rewrites frontmatter into Cursor's contract", () => {
+        const out = toCursorFormat(SAMPLE);
+        // Cursor-shaped frontmatter (the only three keys it understands)
+        expect(out).toMatch(/^description:.*bar/m);
+        // globs now contains the SF file patterns so the rule auto-attaches
+        // whenever the user opens any Salesforce metadata file.
+        expect(out).toMatch(/^globs:.*sfdx-project\.json.*\*\*\/\*\.cls/m);
+        expect(out).toMatch(/^alwaysApply:\s*false$/m);
+        // Trigger phrases folded into the description so the agent matches them
+        expect(out).toMatch(/Triggers:.*"?x"?/);
+        // The agent-requested hint mentions the skill name + sfgraph routing
+        expect(out).toMatch(/sfgraph MCP tools/);
+        // Body preserved verbatim
+        expect(out).toMatch(/^# Body/m);
+        expect(out).toMatch(/^- bullet/m);
+        // Old frontmatter is gone (it would confuse Cursor's parser)
+        expect(out).not.toMatch(/^name: foo/m);
+        expect(out).not.toMatch(/^triggers:/m);
+        expect(out).not.toMatch(/^tools_used:/m);
+    });
+    it("toClaudeFormat is identity", () => {
+        expect(toClaudeFormat(SAMPLE)).toBe(SAMPLE);
+    });
+});
+//# sourceMappingURL=cursor-format.test.js.map

package/dist/__tests__/cursor-format.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-format.test.js","sourceRoot":"","sources":["../../src/__tests__/cursor-format.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjE,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;CAed,CAAC;AAEF,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;QACpE,MAAM,GAAG,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QACnC,iEAAiE;QACjE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;QAC3C,oEAAoE;QACpE,wDAAwD;QACxD,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,6CAA6C,CAAC,CAAC;QACnE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC;QAC/C,wEAAwE;QACxE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QACxC,qEAAqE;QACrE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACzC,0BAA0B;QAC1B,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAClC,6DAA6D;QAC7D,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACvC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACvC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QACpC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/installer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=installer.test.d.ts.map

package/dist/__tests__/installer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/installer.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/installer.test.js

@@ -0,0 +1,64 @@
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { install, listSkillsBundled } from "../installer.js";
+let home;
+beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "sfgraph-home-"));
+});
+afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+});
+describe("skills installer", () => {
+    it("installs all 16 skills to the claude target", async () => {
+        const results = await install("claude", { homeOverride: home });
+        const skillNames = await listSkillsBundled();
+        expect(skillNames.length).toBe(16);
+        expect(results.length).toBe(16);
+        for (const r of results) {
+            expect(r.target).toBe("claude");
+            expect(r.action).toBe("created");
+            expect(existsSync(r.path)).toBe(true);
+            expect(r.path).toContain(join(home, ".claude", "skills"));
+            expect(r.path.endsWith("SKILL.md")).toBe(true);
+        }
+    });
+    it("installs to the cursor target as .mdc files in Cursor's frontmatter shape", async () => {
+        const results = await install("cursor", { homeOverride: home });
+        expect(results.length).toBe(15);
+        const cursorDir = join(home, ".cursor", "rules");
+        const files = readdirSync(cursorDir);
+        expect(files.every((f) => f.endsWith(".mdc"))).toBe(true);
+        expect(files.length).toBe(15);
+        // Cursor-shaped frontmatter (the three keys Cursor's rule loader reads).
+        const sample = readFileSync(join(cursorDir, files[0] ?? ""), "utf8");
+        expect(sample).toMatch(/^description:/m);
+        expect(sample).toMatch(/^globs:.*\*\*\/\*\.cls/m);
+        expect(sample).toMatch(/^alwaysApply:\s*false$/m);
+        // Old frontmatter is rewritten away (would confuse Cursor's parser).
+        expect(sample).not.toMatch(/^name:/m);
+        expect(sample).not.toMatch(/^triggers:/m);
+        expect(sample).not.toMatch(/^tools_used:/m);
+        // Body content preserved.
+        expect(sample).toMatch(/## Playbook/);
+    });
+    it("installs to all targets in one call", async () => {
+        const results = await install("all", { homeOverride: home });
+        const claudeCount = results.filter((r) => r.target === "claude").length;
+        const cursorCount = results.filter((r) => r.target === "cursor").length;
+        const vscodeCount = results.filter((r) => r.target === "vscode").length;
+        expect(claudeCount).toBe(15);
+        expect(cursorCount).toBe(15);
+        expect(vscodeCount).toBe(15);
+        expect(existsSync(join(home, ".claude", "skills"))).toBe(true);
+        expect(existsSync(join(home, ".cursor", "rules"))).toBe(true);
+    });
+    it("dry-run returns would-write actions and writes nothing", async () => {
+        const results = await install("all", { homeOverride: home, dryRun: true });
+        expect(results.every((r) => r.action === "would-write")).toBe(true);
+        expect(existsSync(join(home, ".claude", "skills"))).toBe(false);
+        expect(existsSync(join(home, ".cursor", "rules"))).toBe(false);
+    });
+});
+//# sourceMappingURL=installer.test.js.map

package/dist/__tests__/installer.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.test.js","sourceRoot":"","sources":["../../src/__tests__/installer.test.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { type InstallOptions, type InstallResult, type SkillTarget, findSkillsRoot, install, listSkillsBundled, toClaudeFormat, toCursorFormat, } from "./installer.js";
+export declare const SKILLS: readonly ["sf-impact-from-diff", "sf-what-broke", "sf-cross-layer-trace", "sf-dead-code-audit", "sf-governor-risk-fix", "sf-flow-impact", "sf-security-audit", "sf-cross-org-diff", "sf-deployment-manifest", "sf-omnistudio-migration-audit"];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,cAAc,EACd,OAAO,EACP,iBAAiB,EACjB,cAAc,EACd,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,eAAO,MAAM,MAAM,gPAWT,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+export { findSkillsRoot, install, listSkillsBundled, toClaudeFormat, toCursorFormat, } from "./installer.js";
+export const SKILLS = [
+    "sf-impact-from-diff",
+    "sf-what-broke",
+    "sf-cross-layer-trace",
+    "sf-dead-code-audit",
+    "sf-governor-risk-fix",
+    "sf-flow-impact",
+    "sf-security-audit",
+    "sf-cross-org-diff",
+    "sf-deployment-manifest",
+    "sf-omnistudio-migration-audit",
+];
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,cAAc,EACd,OAAO,EACP,iBAAiB,EACjB,cAAc,EACd,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,qBAAqB;IACrB,eAAe;IACf,sBAAsB;IACtB,oBAAoB;IACpB,sBAAsB;IACtB,gBAAgB;IAChB,mBAAmB;IACnB,mBAAmB;IACnB,wBAAwB;IACxB,+BAA+B;CACvB,CAAC"}

package/dist/installer.d.ts

@@ -0,0 +1,39 @@
+export type SkillTarget = "claude" | "cursor" | "vscode" | "all";
+export interface InstallResult {
+    target: "claude" | "cursor" | "vscode";
+    skill: string;
+    path: string;
+    action: "created" | "updated" | "would-write" | "skipped";
+}
+export interface InstallOptions {
+    dryRun?: boolean;
+    homeOverride?: string;
+}
+/**
+ * Walk up from the current source file (works in dist/ and src/) to locate
+ * the bundled `skills/` directory next to this package's root.
+ */
+export declare function findSkillsRoot(): string;
+export declare function listSkillsBundled(): Promise<string[]>;
+/** Claude consumes the SKILL.md format directly. */
+export declare function toClaudeFormat(md: string): string;
+/**
+ * Cursor expects `.mdc` rule files with a specific frontmatter contract:
+ *   description: <short description the agent matches against>
+ *   globs: <file patterns; can be empty for non-file-scoped rules>
+ *   alwaysApply: <true = always loaded; false = agent-requested>
+ *
+ * Our skill files use a different frontmatter (name/description/triggers/
+ * tools_used). Rewrite the frontmatter into Cursor's shape so rules are
+ * actually picked up. We use 'agent-requested' mode (alwaysApply: false +
+ * rich description) which lets Cursor's agent pull the skill in when the
+ * user's prompt matches the description — without polluting every chat in
+ * unrelated projects.
+ *
+ * The body of the skill markdown (playbook, response shape, visualization,
+ * don't list) is preserved verbatim — that's the actual instructions the
+ * agent reads.
+ */
+export declare function toCursorFormat(md: string): string;
+export declare function install(target: SkillTarget, opts?: InstallOptions): Promise<InstallResult[]>;
+//# sourceMappingURL=installer.d.ts.map

package/dist/installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEjE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAAC;CAC3D;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAYD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAevC;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAU3D;AAED,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAoEjD;AAED,wBAAsB,OAAO,CAC3B,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,aAAa,EAAE,CAAC,CAwD1B"}

package/dist/installer.js

@@ -0,0 +1,187 @@
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function targetDirs(home) {
+    return {
+        claude: join(home, ".claude", "skills"),
+        // Cursor uses ~/.cursor/rules with .mdc extension
+        cursor: join(home, ".cursor", "rules"),
+        // VS Code Claude extension shares ~/.claude
+        vscode: join(home, ".claude", "skills"),
+    };
+}
+/**
+ * Walk up from the current source file (works in dist/ and src/) to locate
+ * the bundled `skills/` directory next to this package's root.
+ */
+export function findSkillsRoot() {
+    // import.meta.url -> /…/packages/skills/{dist,src}/installer.{js,ts}
+    const here = dirname(fileURLToPath(import.meta.url));
+    // candidates: ../skills, ../../skills (when inside dist/ subfolder)
+    const candidates = [
+        join(here, "..", "skills"),
+        join(here, "..", "..", "skills"),
+        join(here, "..", "..", "..", "skills"),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    throw new Error(`@ryanstark24/sfgraph-skills: bundled skills directory not found (looked in ${candidates.join(", ")})`);
+}
+export async function listSkillsBundled() {
+    const root = findSkillsRoot();
+    const entries = await readdir(root, { withFileTypes: true });
+    const names = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const skillPath = join(root, e.name, "SKILL.md");
+        if (existsSync(skillPath))
+            names.push(e.name);
+    }
+    return names.sort();
+}
+/** Claude consumes the SKILL.md format directly. */
+export function toClaudeFormat(md) {
+    return md;
+}
+/**
+ * Cursor expects `.mdc` rule files with a specific frontmatter contract:
+ *   description: <short description the agent matches against>
+ *   globs: <file patterns; can be empty for non-file-scoped rules>
+ *   alwaysApply: <true = always loaded; false = agent-requested>
+ *
+ * Our skill files use a different frontmatter (name/description/triggers/
+ * tools_used). Rewrite the frontmatter into Cursor's shape so rules are
+ * actually picked up. We use 'agent-requested' mode (alwaysApply: false +
+ * rich description) which lets Cursor's agent pull the skill in when the
+ * user's prompt matches the description — without polluting every chat in
+ * unrelated projects.
+ *
+ * The body of the skill markdown (playbook, response shape, visualization,
+ * don't list) is preserved verbatim — that's the actual instructions the
+ * agent reads.
+ */
+export function toCursorFormat(md) {
+    // Parse the leading YAML frontmatter.
+    const fmMatch = md.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!fmMatch)
+        return md; // no frontmatter — leave as-is
+    const frontmatter = fmMatch[1] ?? "";
+    const body = fmMatch[2] ?? "";
+    // Pull out the name, description, and triggers list.
+    const nameMatch = frontmatter.match(/^name:\s*(.+?)\s*$/m);
+    const descMatch = frontmatter.match(/^description:\s*(.+?)\s*$/m);
+    const triggersMatch = frontmatter.match(/^triggers:\s*\n((?:[ \t]+-[^\n]*\n?)+)/m);
+    const name = nameMatch?.[1] ?? "sfgraph-skill";
+    const baseDescription = descMatch?.[1] ?? "";
+    const triggerPhrases = [];
+    if (triggersMatch?.[1]) {
+        for (const line of triggersMatch[1].split("\n")) {
+            const m = line.match(/^\s*-\s*"?(.+?)"?\s*$/);
+            if (m?.[1])
+                triggerPhrases.push(m[1]);
+        }
+    }
+    // Compose a rich description: base + trigger phrases. Cursor's agent
+    // matches the conversation against this string to decide whether to
+    // pull the rule in. Mention sfgraph + Salesforce explicitly so the
+    // match fires on tool-relevant questions.
+    const descriptionParts = [baseDescription];
+    if (triggerPhrases.length > 0) {
+        descriptionParts.push(`Triggers: ${triggerPhrases.join("; ")}.`);
+    }
+    descriptionParts.push(`Use this skill (${name}) for Salesforce questions via the sfgraph MCP tools.`);
+    const description = descriptionParts.filter(Boolean).join(" ");
+    // Salesforce file patterns that should auto-attach the rule when the user
+    // opens any of them. Once any of these are in scope, Cursor's agent gets
+    // the rule loaded into its context automatically — no need for the user
+    // to mention sfgraph or invoke the rule by name.
+    const globs = [
+        "**/sfdx-project.json",
+        "**/force-app/**",
+        "**/*.cls",
+        "**/*.cls-meta.xml",
+        "**/*.trigger",
+        "**/*.trigger-meta.xml",
+        "**/lwc/**",
+        "**/aura/**",
+        "**/*.flow-meta.xml",
+        "**/*.object-meta.xml",
+        "**/*.field-meta.xml",
+        "**/*.permissionset-meta.xml",
+        "**/*.permissionsetgroup-meta.xml",
+        "**/*.profile-meta.xml",
+        "**/*.sharingRules-meta.xml",
+        "**/*.layout-meta.xml",
+        "**/*.flexipage-meta.xml",
+        "**/*.namedCredential-meta.xml",
+        "**/*.workflow-meta.xml",
+    ].join(",");
+    return `---
+description: ${description.replace(/\n/g, " ").replace(/"/g, "'")}
+globs: ${globs}
+alwaysApply: false
+---
+${body}`;
+}
+export async function install(target, opts = {}) {
+    const home = opts.homeOverride ?? homedir();
+    const dirs = targetDirs(home);
+    const targets = target === "all" ? ["claude", "cursor", "vscode"] : [target];
+    const results = [];
+    const root = findSkillsRoot();
+    const skills = await listSkillsBundled();
+    for (const t of targets) {
+        const outDir = dirs[t];
+        if (!opts.dryRun) {
+            await mkdir(outDir, { recursive: true });
+        }
+        for (const skill of skills) {
+            const src = join(root, skill, "SKILL.md");
+            const body = await readFile(src, "utf8");
+            let outPath;
+            let transformed;
+            if (t === "cursor") {
+                outPath = join(outDir, `${skill}.mdc`);
+                transformed = toCursorFormat(body);
+            }
+            else {
+                // claude + vscode: install as a directory with SKILL.md inside
+                const skillDir = join(outDir, skill);
+                outPath = join(skillDir, "SKILL.md");
+                transformed = toClaudeFormat(body);
+                if (!opts.dryRun) {
+                    await mkdir(skillDir, { recursive: true });
+                }
+            }
+            let action;
+            if (opts.dryRun) {
+                action = "would-write";
+            }
+            else {
+                const existed = existsSync(outPath);
+                if (existed) {
+                    const prev = await readFile(outPath, "utf8");
+                    if (prev === transformed) {
+                        action = "skipped";
+                    }
+                    else {
+                        await writeFile(outPath, transformed, "utf8");
+                        action = "updated";
+                    }
+                }
+                else {
+                    await writeFile(outPath, transformed, "utf8");
+                    action = "created";
+                }
+            }
+            results.push({ target: t, skill, path: outPath, action });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=installer.js.map

package/dist/installer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.js","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ryanstark24/sfgraph-skills",
+  "version": "1.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ryanStark24/sfgraph"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "sfgraph SKILL.md playbooks for Cursor and Claude",
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "keywords": [
+    "salesforce",
+    "sfgraph",
+    "mcp",
+    "skills",
+    "playbook"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "lint": "biome check src",
+    "lint:fix": "biome check --write src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/skills/sf-cross-layer-trace/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: sf-cross-layer-trace
+description: Trace a field, component, or method end-to-end across LWC, Apex, Flow, and data layer. PROACTIVELY volunteer this skill whenever the focal artifact is an LWC bundle, Aura component, ApexPage, or a custom field — even on explain-style questions ("explain this LWC", "what does this component do", "where is X used"). After answering the surface question, offer a cross-layer trace so the user sees what the artifact ultimately touches through Apex / Flow / SObject.
+triggers:
+  - "UI to DB"
+  - "trace this LWC"
+  - "end-to-end"
+  - "where is this field used"
+  - "where does this come from"
+  - "explain this LWC"
+  - "explain this component"
+  - "what does this component do"
+  - "what does this LWC do"
+  - "explain this Aura"
+  - "explain this VisualForce"
+  - "explain this ApexPage"
+  - "where is this component used"
+  - "what pages embed"
+  - "which pages use"
+tools_used:
+  - cross_layer_flow_map
+  - analyze_field
+  - staleness_check
+  - explain_code
+---
+
+# sf-cross-layer-trace
+
+Use when the user needs to follow a single artifact (field, LWC, Apex method) across every layer it touches — UI rendering, Apex controller, flow automation, data model.
+
+## When to volunteer this skill
+
+Source-only tools (file grep, repo search, `explain_code`) can answer "where is this used?" inside the sfdx-source repo, but they cannot see:
+- Lightning App Builder page bindings (FlexiPages embedding the component)
+- Quick Action / Lightning Action targets
+- Flow screen components referencing the LWC
+- Apex controllers the LWC `@wire`s into, and what those controllers ultimately read/write
+
+So whenever the focal node is an **LWC bundle, Aura component, ApexPage, custom field, or Apex class/method**, after answering the surface question proactively offer:
+
+> "I answered using the repo. Want me to run `cross_layer_flow_map` on `<node>` against the ingested org graph? That will surface page bindings, controller chains, and the SObject fields it ultimately touches — things the source files alone don't show."
+
+Only skip the offer when the user has explicitly scoped the question to source (e.g. "just look at the repo, don't query the graph") or when the graph staleness check shows the org isn't ingested at all.
+
+## Playbook
+
+1. Resolve the starting node. If the user gave a field, call `analyze_field` first to canonicalise `SObject.Field` and gather direct readers/writers.
+2. Call `cross_layer_flow_map` with the resolved node. Receive ordered paths across layers (UI -> Controller -> Service -> Selector -> SObject and any Flow / Process Builder branches).
+3. For each distinct path, summarise the layer transitions with the edge type that bridges them (`@wire`, `@AuraEnabled`, `READS_FIELD`, `UPDATES_FIELD`, `INVOKES_FLOW`).
+4. Surface anything anomalous: cycles, missing `with sharing`, fields read by multiple LWCs but written only by Flow, etc.
+5. Render the Mermaid layered diagram from `cross_layer_flow_map`. If the graph has more than 30 nodes, ask whether to filter to a single layer pair.
+6. End with a one-line recommendation of which related skill to invoke next (e.g. `sf-security-audit` if FLS gaps appear).
+
+## Visualization
+
+Render a **`flowchart TD`** layered diagram with one subgraph per layer (UI / Controller / Service / Selector / Data). Edges are labelled with the edge type that bridges layers (`@wire`, `@AuraEnabled`, `READS_FIELD`, `UPDATES_FIELD`, `INVOKES_FLOW`).
+
+```
+flowchart TD
+  subgraph UI
+    LWC[accountList.js]
+  end
+  subgraph Apex
+    Ctl[AccountController.getAccounts]
+    Svc[AccountSelector.queryAll]
+  end
+  subgraph Data
+    F[(Account.Name)]
+  end
+  LWC -->|@wire| Ctl --> Svc -->|READS_FIELD| F
+```
+
+If the resolved trace has >30 nodes, ask the user to narrow to a single layer-pair before rendering — a sprawling layered diagram is more misleading than no diagram.
+
+## Staleness check
+
+Before calling `cross_layer_flow_map`, invoke `staleness_check` for the target org. If the report says stale, surface a warning to the user:
+
+> Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **Subject** — the resolved node id and type.
+- **Paths** — numbered list of distinct UI->DB paths with layer transitions.
+- **Anomalies** — bullets calling out anything that looks structurally suspicious.
+- **Mermaid layered diagram** — embedded from tool output.
+- **Suggested next skill** — one line.
+
+## Don't
+
+- Do not collapse layers — the value of this skill is showing the layer boundaries explicitly.
+- Do not include nodes outside the requested traversal depth; defer breadth to a follow-up call.
+- Do not modify anything. Pure read.
+- Do not assume the starting node exists; if `analyze_field` returns empty, ask the user to refine.
+- Do not stop at a source-only answer for LWC / Aura / ApexPage / field / Apex method questions without at least *offering* the cross-layer trace. Repo grep misses FlexiPage bindings, Quick Action targets, and the Apex→SObject tail — say so and offer to fill it in.

package/skills/sf-cross-org-diff/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sf-cross-org-diff
+description: Compare metadata between two orgs (sandbox vs prod, two sandboxes) and summarise drift.
+triggers:
+  - "sandbox vs prod"
+  - "what changed"
+  - "org diff"
+  - "compare orgs"
+  - "drift"
+tools_used:
+  - cross_org_diff
+  - point_in_time_diff
+  - list_orgs
+  - staleness_check
+---
+
+# sf-cross-org-diff
+
+Use when the user wants to understand drift between two orgs — typically pre-deploy verification or post-deploy reconciliation.
+
+## Playbook
+
+1. Call `list_orgs` first. Present the user with the authenticated orgs, each org's `ingested` flag, last sync timestamp, and `stale` flag. Ask the user to pick the two orgs to compare. Refuse to proceed if either selected org has `ingested=false` — instruct them to run `sfgraph ingest --org <alias>` first.
+2. Call `cross_org_diff(orgA, orgB)`. Capture added / removed / modified nodes grouped by metadata category.
+3. For high-churn categories, call `point_in_time_diff` inside each org to confirm the drift originated there (vs being a stale snapshot artifact).
+4. Categorise drift: **structural** (new objects/fields), **logic** (Apex, Flow body changes), **security** (profile / sharing), **config** (custom metadata / settings).
+5. Render the Mermaid drift summary from the tool. For each category, list the top-N items by impact.
+6. Recommend `sf-deployment-manifest` if the user wants to bring orgs into sync.
+
+## Visualization
+
+Render a **`flowchart LR`** drift summary. Two side-by-side subgraphs (one per org) joined by edges that classify drift (added / removed / modified). Use colour to indicate severity by metadata category.
+
+```
+flowchart LR
+  subgraph A[orgA]
+    A1[ApexClass:Foo]
+  end
+  subgraph B[orgB]
+    B1[ApexClass:Foo']
+  end
+  A1 -->|modified| B1
+  A2[Field:Account.X]:::removed -.->|absent| B
+  classDef removed fill:#fdd,stroke:#900
+```
+
+For diffs with >50 nodes, switch to a bucketed table per category and skip the diagram.
+
+## Staleness check
+
+Before calling `cross_org_diff`, invoke `staleness_check` for both orgs. If either is stale, surface a warning to the user:
+
+> Your ingest for `<alias>` is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.
+
+Then continue with the playbook.
+
+## Response Shape
+
+- **Orgs compared** — `orgA -> orgB`.
+- **Drift by category** — structural / logic / security / config, each with a count and top items.
+- **Notable single-side items** — present in A only or B only.
+- **Mermaid drift summary** — embedded.
+- **Next step** — single line, typically pointing at deployment manifest skill.
+
+## Don't
+
+- Do not deploy or copy metadata between orgs from this skill.
+- Do not assume `orgA` is "source of truth"; report drift symmetrically.
+- Do not include freshness drift (last-modified-by user) in the structural bucket — call it out separately.
+- Do not run if either org has not been ingested; instruct the user instead.