@malloy-publisher/skills 0.1.34 → 0.1.36

package/README.md

@@ -5,6 +5,31 @@ SPDX-License-Identifier: MIT
 
 # @malloy-publisher/skills
 
+## Start here
+
+1. **Learn.** Read the getting-started skill. Nothing to install, no server:
+
+   <https://unpkg.com/@malloy-publisher/skills@latest/skills/malloy-getting-started/SKILL.md>
+
+   Every skill reads the same way. Put its name in place of `malloy-getting-started`.
+
+2. **Install.** If your agent has a shell, copy every skill to where it loads them:
+
+   ```bash
+   npx -y @malloy-publisher/skills@latest install           # into this project
+   npx -y @malloy-publisher/skills@latest install --global  # into your home directory
+   npx -y @malloy-publisher/skills@latest list              # every skill, with a description
+   ```
+
+   Keep the `@latest`. Without it, npx may reuse an old cached copy and install old skills.
+
+   `install` picks the agent from what it finds. A `CLAUDE.md` means `.claude/skills/`. An
+   `AGENTS.md` or `.cursor/` means `.agents/skills/`. With `--global` it looks for `~/.claude/`,
+   `~/.agents/`, or `~/.cursor/` instead. If it finds none, it stops and asks you to name one:
+   `install claude` or `install agents`.
+
+## What this package is
+
 The agent skills that ship with [Malloy Publisher](https://github.com/malloydata/publisher), as
 files you can install. They are task-specific guides for writing Malloy, building and reviewing
 models, exploring data, and authoring HTML data apps.
@@ -14,7 +39,7 @@ files. This package exists for the cases MCP does not cover: a host that reads s
 (Claude Code and the Publisher plugin), a scaffolder that installs them into a new project, or any
 tool that wants the files themselves rather than prompt text.
 
-## Install
+## Use the files from code
 
 ```bash
 npm install @malloy-publisher/skills
@@ -52,8 +77,7 @@ skill points to for detail it does not inline. Start with `malloy-getting-starte
 `malloy-modeling` to build or change a model, `malloy-analysis` to explore and answer questions, and
 `malloy-review` to check Malloy for correctness.
 
-A few skills (`malloy-modeling`, `malloy-publish`, `malloy-document`, `malloy-getting-started`, and
-the `malloy` index) are written for a Publisher host and name Publisher's MCP tools
+A few skills (`malloy-modeling`, `malloy-publish`, `malloy-document`, and `malloy-getting-started`) are written for a Publisher host and name Publisher's MCP tools
 directly. The rest describe Malloy itself and refer to tools by bare name (`get_context`,
 `execute_query`, `search_malloy_docs`), because the prefix depends on the
 host. `search_database_schema` maps the same way if a shared skill starts using it. On Publisher those are `get_context`, `execute_query`, `search_malloy_docs`, and

package/dist/cli.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/** Where each host looks for skills, relative to a project or to the home dir. */
+declare const TARGETS: Record<string, string>;
+/**
+ * What says a host is set up, per scope. The two differ because the hosts keep
+ * their user-level config in a directory rather than a top-level file: Claude
+ * Code reads `~/.claude/CLAUDE.md`, never `~/CLAUDE.md`, so the project markers
+ * would miss almost everyone who has Claude set up.
+ */
+declare const MARKERS: Record<"project" | "global", Record<string, string[]>>;
+/**
+ * Where a skill can be read with nothing installed. `@latest` rather than this
+ * package's own version, so a link copied from an old cached copy of this CLI
+ * still serves the current skill.
+ */
+declare function skillUrl(name: string): string;
+/**
+ * Which hosts this directory is set up for.
+ *
+ * Detection only ever chooses between hosts the user already has; it never
+ * decides *whether* to write. When it finds nothing, install asks rather than
+ * picking one, because a skills directory in the wrong place is invisible: the
+ * agent simply never loads them and nothing says why.
+ */
+declare function detectTargets(root: string, scope: keyof typeof MARKERS): string[];
+declare function main(argv: string[]): void;
+export { TARGETS, detectTargets, main, skillUrl };

package/dist/cli.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// Copyright (c) Credible Data Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * `malloy-skills` -- list the agent skills, and install them, with nothing
+ * running.
+ *
+ * This exists so an agent meeting Publisher for the first time can get the
+ * skills before it installs or starts anything. Every other route to them is
+ * gated: the MCP prompt channel needs the server up, and the server is a large
+ * install that clones its example packages over the network.
+ *
+ * Reading one skill needs no command at all: the package ships the files, so
+ * unpkg serves each SKILL.md at a stable URL (`skillUrl`). That works in a chat
+ * with no shell, which `npx` cannot. This CLI covers what a URL cannot: listing
+ * what ships, and copying the whole tree, `reference/` files included, onto
+ * disk through the hardened copy in install.ts.
+ *
+ * Which is why this lives in @malloy-publisher/skills and not in the server or a
+ * new package: this one already ships the skill files, has no runtime
+ * dependencies and no native code, so `npx` is fast and cannot fail on a build
+ * step or a platform binary. Adding a CLI framework here would cost that, for
+ * two commands, so the argument parsing below is by hand.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { listSkills } from "./index.js";
+import { installSkills } from "./install.js";
+import { skillsDir } from "./payload.js";
+/** Where each host looks for skills, relative to a project or to the home dir. */
+const TARGETS = {
+    claude: path.join(".claude", "skills"),
+    agents: path.join(".agents", "skills"),
+};
+/**
+ * What says a host is set up, per scope. The two differ because the hosts keep
+ * their user-level config in a directory rather than a top-level file: Claude
+ * Code reads `~/.claude/CLAUDE.md`, never `~/CLAUDE.md`, so the project markers
+ * would miss almost everyone who has Claude set up.
+ */
+const MARKERS = {
+    project: { claude: ["CLAUDE.md"], agents: ["AGENTS.md", ".cursor"] },
+    global: { claude: [".claude"], agents: [".agents", ".cursor"] },
+};
+/**
+ * Where a skill can be read with nothing installed. `@latest` rather than this
+ * package's own version, so a link copied from an old cached copy of this CLI
+ * still serves the current skill.
+ */
+function skillUrl(name) {
+    return `https://unpkg.com/@malloy-publisher/skills@latest/skills/${name}/SKILL.md`;
+}
+const USAGE = `malloy-skills - list and install the Malloy Publisher agent skills
+
+Usage:
+  npx -y @malloy-publisher/skills@latest [list]          List every skill.
+  npx -y @malloy-publisher/skills@latest install [host]  Copy the skills onto disk.
+
+Keep the @latest: without it npx may reuse an old cached copy.
+
+Install targets:
+  claude    .claude/skills/   (detected from a CLAUDE.md)
+  agents    .agents/skills/   (detected from an AGENTS.md or .cursor/)
+  --global  install into your home directory instead of this project
+            (detected from ~/.claude/, ~/.agents/, or ~/.cursor/)
+
+Read one skill without installing anything:
+  ${skillUrl("<name>")}
+
+Nothing here needs a running server or an account.`;
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+/** Print the name and description of every shipped skill. */
+function list() {
+    const skills = listSkills();
+    if (skills.length === 0) {
+        fail(`No skills found in ${skillsDir}. This install of ` +
+            `@malloy-publisher/skills is incomplete; reinstall and try again.`);
+    }
+    for (const skill of skills) {
+        console.log(skill.name);
+        console.log(`  ${skill.description}`);
+    }
+    console.log("");
+    console.log(`Read one: ${skillUrl("<name>")}`);
+    console.log("Install them all: npx -y @malloy-publisher/skills@latest install");
+}
+/**
+ * Which hosts this directory is set up for.
+ *
+ * Detection only ever chooses between hosts the user already has; it never
+ * decides *whether* to write. When it finds nothing, install asks rather than
+ * picking one, because a skills directory in the wrong place is invisible: the
+ * agent simply never loads them and nothing says why.
+ */
+function detectTargets(root, scope) {
+    return Object.entries(MARKERS[scope])
+        .filter(([, markers]) => markers.some((marker) => fs.existsSync(path.join(root, marker))))
+        .map(([host]) => host);
+}
+/** Say what an install did, including what it cost. */
+function report(target, dir, result) {
+    if (result.refused) {
+        fail(`Did not install into ${dir}: ${result.refused}.`);
+    }
+    console.log(`Installed ${result.installed} skills into ${dir}`);
+    if (result.skipped.length > 0) {
+        console.log(`  left alone (symlinked): ${result.skipped.join(", ")}`);
+    }
+    if (result.refreshed.length > 0) {
+        console.log(`  replaced: ${result.refreshed.join(", ")}`);
+    }
+    // Not a footnote: these are files the user put there that no copy puts back.
+    for (const gone of result.removed) {
+        console.log(`  removed (not in the shipped skill): ${target}/${gone}`);
+    }
+}
+function install(hosts, global) {
+    const root = global ? os.homedir() : process.cwd();
+    const scope = global ? "global" : "project";
+    let chosen = hosts;
+    if (chosen.length === 0) {
+        chosen = detectTargets(root, scope);
+        if (chosen.length === 0) {
+            const looked = Object.values(MARKERS[scope]).flat().join(", ");
+            const flag = global ? " --global" : "";
+            fail(`Could not tell which agent to install for: no ${looked} in ${root}.\n` +
+                `Name one: npx -y @malloy-publisher/skills@latest install claude${flag}   (or: install agents${flag})`);
+        }
+    }
+    for (const host of chosen) {
+        const dir = path.join(root, TARGETS[host]);
+        report(host, dir, installSkills(dir, root));
+    }
+}
+function main(argv) {
+    const global = argv.includes("--global");
+    const args = argv.filter((arg) => arg !== "--global");
+    const [command = "list", ...rest] = args;
+    if (command === "--help" || command === "-h" || command === "help") {
+        console.log(USAGE);
+        return;
+    }
+    if (command === "install") {
+        for (const host of rest) {
+            if (!(host in TARGETS)) {
+                fail(`Unknown install target '${host}'. ` +
+                    `Expected one of: ${Object.keys(TARGETS).join(", ")}.`);
+            }
+        }
+        return install(rest, global);
+    }
+    // Anything else is refused rather than skipped: a silently ignored argument
+    // is how a typo turns into a command that looks like it worked.
+    if (command !== "list") {
+        // A skill name is the likeliest mistake, from an agent that expects this
+        // to print one, so it gets the URL that does.
+        const skill = listSkills().find((s) => s.name === command);
+        fail(skill
+            ? `There is no command to print a skill. Read it at ${skillUrl(command)}`
+            : `Unknown command or option '${command}'.\n\n${USAGE}`);
+    }
+    if (rest.length > 0) {
+        fail(`'list' takes no arguments, got: ${rest.join(" ")}.`);
+    }
+    if (global)
+        fail("--global only applies to install.");
+    return list();
+}
+// Only when run as the command, so importing this module for a test does not
+// parse the test runner's own argv and exit the process.
+if (process.argv[1] &&
+    realpath(process.argv[1]) === realpath(fileURLToPath(import.meta.url))) {
+    main(process.argv.slice(2));
+}
+function realpath(target) {
+    try {
+        return fs.realpathSync(target);
+    }
+    catch {
+        return target;
+    }
+}
+export { TARGETS, detectTargets, main, skillUrl };

package/dist/index.d.ts

@@ -5,14 +5,6 @@ export interface Skill {
     /** Absolute path to the skill's directory: SKILL.md and any reference/. */
     dir: string;
 }
-/**
- * Absolute path to the directory holding the skill directories.
- *
- * Resolved from this module's own URL, which works both from dist/ once
- * installed and from src/ in the repo, since both sit one level under the
- * package root.
- */
-export declare const skillsDir: string;
 /**
  * Read every skill's frontmatter from the shipped files.
  *
@@ -20,3 +12,10 @@ export declare const skillsDir: string;
  * second copy of this metadata to regenerate or to drift.
  */
 export declare function listSkills(): Skill[];
+/**
+ * The installer is re-exported here so `@malloy-publisher/skills` has one entry
+ * point: consumers get `skillsDir` to read from and `installSkills` to write
+ * with, without reaching into a subpath.
+ */
+export { skillsDir } from "./payload.js";
+export { countSkills, installSkills, isWithinDirectory, type SkillInstall, } from "./install.js";

package/dist/index.js

@@ -6,15 +6,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-/**
- * Absolute path to the directory holding the skill directories.
- *
- * Resolved from this module's own URL, which works both from dist/ once
- * installed and from src/ in the repo, since both sit one level under the
- * package root.
- */
-export const skillsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "skills");
+import { skillsDir } from "./payload.js";
 function unquote(value) {
     return value.trim().replace(/^["']|["']$/g, "");
 }
@@ -47,3 +39,10 @@ export function listSkills() {
     // platforms and must not depend on the runtime's locale.
     return skills.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
 }
+/**
+ * The installer is re-exported here so `@malloy-publisher/skills` has one entry
+ * point: consumers get `skillsDir` to read from and `installSkills` to write
+ * with, without reaching into a subpath.
+ */
+export { skillsDir } from "./payload.js";
+export { countSkills, installSkills, isWithinDirectory, } from "./install.js";

package/dist/install.d.ts

@@ -0,0 +1,68 @@
+export interface SkillInstall {
+    /** How many skills were copied in. */
+    installed: number;
+    /** Skill names left alone because the target is a symlink. */
+    skipped: string[];
+    /** Skill names whose existing files the bundled copies replaced. */
+    refreshed: string[];
+    /**
+     * Paths that were inside a skill directory, are not in the bundled copy of
+     * that skill, and so were removed and not written back. Relative to the
+     * skills directory (`malloy-review/NOTES.md`), directories with a trailing
+     * separator.
+     *
+     * Reported separately from `refreshed` because they are a different loss.
+     * "Refreshed" is read as "my edits to the skill files were reverted", which
+     * is recoverable knowledge; a file the user put in the directory themselves
+     * is simply gone, and nothing named it.
+     */
+    removed: string[];
+    /** Why nothing at all was installed, when nothing was. */
+    refused?: string;
+}
+/**
+ * Copy every agent skill into targetDir as real files. The generated project is
+ * standalone and the user may move or commit it, so this is a recursive copy, not
+ * a symlink: a symlink into node_modules would dangle the moment the project is
+ * moved or its dependencies pruned. skillsDir already excludes non-shipping skills
+ * and the internal README, so a straight copy is clean.
+ *
+ * A skill directory in the target that is itself a symlink is left alone. That is
+ * how this repo's own contributors wire skills into their agent (skills/README.md
+ * tells them to), and copying through the link would overwrite the source of truth
+ * rather than the workspace.
+ *
+ * targetDir has to resolve inside workspaceRoot. A `.claude` that is itself a
+ * symlink elsewhere is not caught by the per-skill check above, and used to write
+ * every skill outside the workspace while reporting them installed.
+ *
+ * An existing skill directory is removed before the copy rather than copied over.
+ * fs.cpSync follows a symlink it finds at the destination, so checking only the
+ * skill directory itself left every path inside it writable through a link: a
+ * `.claude/skills/malloy-review/SKILL.md` linked elsewhere had the file it points
+ * at replaced, and a linked `reference/` (four shipped skills have one) had files
+ * written into whatever directory it named, all under a green
+ * "Installed N Malloy skills". `.claude/skills/` is shared agent territory where
+ * links are an expected state, so the check has to cover the whole subtree, and
+ * removing first is the only form of that which cannot be one level short.
+ *
+ * The copy is unconditional, so an edited skill is replaced on every run. That is
+ * deliberate (an existing workspace picks up skill updates), but it is reported:
+ * `refreshed` names what was overwritten. Because the directory is removed and
+ * not merged, that goes further than reverting an edit: a file the user added
+ * inside a skill directory is gone, and no bundled copy puts it back. Those paths
+ * are collected into `removed` so the caller can name them, rather than leaving
+ * them under a word ("refreshed") that reads as "your edits were reverted". Note
+ * the copy never prunes whole skills, so one dropped from a later release stays in
+ * the workspace until deleted by hand.
+ */
+export declare function installSkills(targetDir: string, workspaceRoot: string): SkillInstall;
+/** Count directories under dir that contain a SKILL.md, i.e. real skills. */
+export declare function countSkills(dir: string): number;
+/**
+ * Whether target, which need not exist yet, names a path inside root once every
+ * symlink on the way has been followed. A path utility rather than a skills
+ * concept, but it lives beside the only call that needs it, and exporting it
+ * keeps the scaffolder's own path checks on the same implementation.
+ */
+export declare function isWithinDirectory(target: string, root: string): boolean;

package/dist/install.js

@@ -0,0 +1,182 @@
+// Copyright (c) Credible Data Inc.
+// SPDX-License-Identifier: MIT
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { skillsDir } from "./payload.js";
+/**
+ * Copy every agent skill into targetDir as real files. The generated project is
+ * standalone and the user may move or commit it, so this is a recursive copy, not
+ * a symlink: a symlink into node_modules would dangle the moment the project is
+ * moved or its dependencies pruned. skillsDir already excludes non-shipping skills
+ * and the internal README, so a straight copy is clean.
+ *
+ * A skill directory in the target that is itself a symlink is left alone. That is
+ * how this repo's own contributors wire skills into their agent (skills/README.md
+ * tells them to), and copying through the link would overwrite the source of truth
+ * rather than the workspace.
+ *
+ * targetDir has to resolve inside workspaceRoot. A `.claude` that is itself a
+ * symlink elsewhere is not caught by the per-skill check above, and used to write
+ * every skill outside the workspace while reporting them installed.
+ *
+ * An existing skill directory is removed before the copy rather than copied over.
+ * fs.cpSync follows a symlink it finds at the destination, so checking only the
+ * skill directory itself left every path inside it writable through a link: a
+ * `.claude/skills/malloy-review/SKILL.md` linked elsewhere had the file it points
+ * at replaced, and a linked `reference/` (four shipped skills have one) had files
+ * written into whatever directory it named, all under a green
+ * "Installed N Malloy skills". `.claude/skills/` is shared agent territory where
+ * links are an expected state, so the check has to cover the whole subtree, and
+ * removing first is the only form of that which cannot be one level short.
+ *
+ * The copy is unconditional, so an edited skill is replaced on every run. That is
+ * deliberate (an existing workspace picks up skill updates), but it is reported:
+ * `refreshed` names what was overwritten. Because the directory is removed and
+ * not merged, that goes further than reverting an edit: a file the user added
+ * inside a skill directory is gone, and no bundled copy puts it back. Those paths
+ * are collected into `removed` so the caller can name them, rather than leaving
+ * them under a word ("refreshed") that reads as "your edits were reverted". Note
+ * the copy never prunes whole skills, so one dropped from a later release stays in
+ * the workspace until deleted by hand.
+ */
+export function installSkills(targetDir, workspaceRoot) {
+    const empty = { installed: 0, skipped: [], refreshed: [], removed: [] };
+    if (isSymlink(targetDir)) {
+        return {
+            ...empty,
+            refused: "it is a symlink, so writing into it would edit whatever it points at",
+        };
+    }
+    if (!isWithinDirectory(targetDir, workspaceRoot)) {
+        return {
+            ...empty,
+            refused: "it resolves outside the workspace, so writing into it would put " +
+                "files somewhere else on this machine",
+        };
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    const skipped = [];
+    const refreshed = [];
+    const removed = [];
+    let installed = 0;
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const source = path.join(skillsDir, entry.name);
+        if (!fs.existsSync(path.join(source, "SKILL.md"))) {
+            continue;
+        }
+        const target = path.join(targetDir, entry.name);
+        if (isSymlink(target)) {
+            skipped.push(entry.name);
+            continue;
+        }
+        if (fs.existsSync(target)) {
+            refreshed.push(entry.name);
+            // Read before the removal, because after it there is nothing to read:
+            // these are the paths the copy below does not put back.
+            for (const relative of pathsNotIn(target, source)) {
+                removed.push(path.join(entry.name, relative));
+            }
+        }
+        // target is not a symlink (checked above) and sits directly under a
+        // targetDir that resolves inside the workspace, so this removes files in
+        // the workspace and, for any symlink further down, the link itself rather
+        // than what it points at.
+        fs.rmSync(target, { recursive: true, force: true });
+        fs.cpSync(source, target, { recursive: true });
+        installed += 1;
+    }
+    return { installed, skipped, refreshed, removed };
+}
+/**
+ * Every path under target that source does not also hold, relative to target.
+ *
+ * A directory that source does not hold is named once and not walked: what the
+ * user has to look for is the directory, and walking it would turn one dropped
+ * folder into a hundred lines. Nothing here follows a link out of target either,
+ * because a symlink is compared by its own path, never by what it points at.
+ */
+function pathsNotIn(target, source, prefix = "") {
+    let entries;
+    try {
+        entries = fs.readdirSync(path.join(target, prefix), {
+            withFileTypes: true,
+        });
+    }
+    catch {
+        // Unreadable: nothing can be said about what is in it.
+        return [];
+    }
+    const missing = [];
+    for (const entry of entries) {
+        const relative = path.join(prefix, entry.name);
+        if (!fs.existsSync(path.join(source, relative))) {
+            missing.push(entry.isDirectory() ? relative + path.sep : relative);
+            continue;
+        }
+        if (entry.isDirectory()) {
+            missing.push(...pathsNotIn(target, source, relative));
+        }
+    }
+    return missing;
+}
+/** Count directories under dir that contain a SKILL.md, i.e. real skills. */
+export function countSkills(dir) {
+    if (!fs.existsSync(dir)) {
+        return 0;
+    }
+    return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() &&
+        fs.existsSync(path.join(dir, entry.name, "SKILL.md"))).length;
+}
+/**
+ * Whether target, which need not exist yet, names a path inside root once every
+ * symlink on the way has been followed. A path utility rather than a skills
+ * concept, but it lives beside the only call that needs it, and exporting it
+ * keeps the scaffolder's own path checks on the same implementation.
+ */
+export function isWithinDirectory(target, root) {
+    const realRoot = realPathOf(root);
+    const realTarget = realPathOf(target);
+    return realTarget === realRoot || realTarget.startsWith(realRoot + path.sep);
+}
+/**
+ * The path target really names. fs.realpathSync cannot be used: it throws on a
+ * path that does not exist yet (every file we are about to create) and on a
+ * dangling symlink, which is precisely the case that matters, because
+ * fs.writeFileSync follows a dangling link and creates the file wherever it
+ * points. So resolve the parent first, then follow one link at a time.
+ */
+function realPathOf(target, hops = 0) {
+    const resolved = path.resolve(target);
+    const parent = path.dirname(resolved);
+    if (parent === resolved) {
+        return resolved;
+    }
+    const here = path.join(realPathOf(parent, hops), path.basename(resolved));
+    if (hops >= 40) {
+        // A symlink cycle. Stop following and judge the path as it stands.
+        return here;
+    }
+    try {
+        if (!fs.lstatSync(here).isSymbolicLink()) {
+            return here;
+        }
+        return realPathOf(path.resolve(path.dirname(here), fs.readlinkSync(here)), hops + 1);
+    }
+    catch {
+        // Does not exist yet, or is unreadable: it is the path it looks like.
+        return here;
+    }
+}
+function isSymlink(target) {
+    try {
+        return fs.lstatSync(target).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/payload.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Absolute path to the directory holding the skill directories.
+ *
+ * Resolved from this module's own URL, which works both from dist/ once
+ * installed and from src/ in the repo, since both sit one level under the
+ * package root.
+ */
+export declare const skillsDir: string;

package/dist/payload.js

@@ -0,0 +1,19 @@
+// Copyright (c) Credible Data Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Where the shipped skill files are.
+ *
+ * Its own module, rather than a constant in index.ts, because both the reader
+ * (`listSkills`) and the writer (`installSkills`) need it and index.ts re-exports
+ * the writer: importing it from there would make the two modules a cycle.
+ */
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Absolute path to the directory holding the skill directories.
+ *
+ * Resolved from this module's own URL, which works both from dist/ once
+ * installed and from src/ in the repo, since both sit one level under the
+ * package root.
+ */
+export const skillsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "skills");

package/package.json

@@ -1,11 +1,14 @@
 {
    "name": "@malloy-publisher/skills",
    "description": "Agent skills for Malloy and the Malloy Publisher",
-   "version": "0.1.34",
+   "version": "0.1.36",
    "license": "MIT",
    "type": "module",
    "main": "dist/index.js",
    "types": "dist/index.d.ts",
+   "bin": {
+      "malloy-skills": "dist/cli.js"
+   },
    "exports": {
       ".": {
          "types": "./dist/index.d.ts",

package/skills/eval-answer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-answer
 description: 'Score one analytical answer against a verified golden, and score which of the entities the golden depends on retrieval delivered to the answerer. Run the contamination checklist, re-execute the submitted query yourself, then spawn a judge subagent per skill:eval-judge. Append attempt, tool_call, score, and retrieval_score events to the file ledger (reference/ledger-schema.md). Never explain the failure (eval-diagnose) or edit the model (eval-improve). Use when asked whether an answer was correct, to score a run, or to baseline a model.'
-version: 0.1.34
+version: 0.1.36
 ---
 
 # Evaluate One Answer
@@ -290,5 +290,4 @@ original answerer to "try again" with the new key in context.
 
 - `skill:eval-diagnose`: why it failed, after this record exists.
 - `skill:eval-improve`: smallest model edit, model-owned issues only.
-- The `malloy-analysis-pitfalls` skill: checks before you trust a result you ran.
-  The judge loads it by name; it is not part of the `eval` group.
+- Step 5 of the `malloy-analysis` skill: checks before you trust a result you ran.