@cruxy/cli 0.1.1 → 0.3.0

package/dist/indexing/walker.js

@@ -0,0 +1,166 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { globToRegexBody, isBinary } from "./util.js";
+/** Directories never descended into, regardless of ignore files. */
+const ALWAYS_IGNORE_DIRS = new Set([".git", "node_modules", ".cruxy"]);
+const DEFAULT_IGNORE_FILES = [".gitignore", ".cruxyignore"];
+/**
+ * Hard denylist for secret-bearing files. Applied independently of ignore files
+ * (and of negation rules), so secrets are never indexed even when untracked.
+ * Matched against the project-relative POSIX path.
+ */
+const SECRET_PATTERNS = [
+    /(^|\/)\.env($|\.|rc)/i, // .env, .env.local, .env.production, .envrc
+    /(^|\/)id_(rsa|dsa|ecdsa|ed25519)(\.|$)/, // ssh private keys
+    /\.(pem|key|pfx|p12|p8|keystore|jks|asc|gpg)$/i, // keys / certs / keystores
+    /(^|\/)\.(npmrc|netrc|pgpass)$/i, // credential dotfiles
+    /(^|\/)\.aws\/credentials$/i,
+];
+function isSecretPath(relPath) {
+    return SECRET_PATTERNS.some((re) => re.test(relPath));
+}
+/**
+ * A compiled set of gitignore-style patterns, matched against paths relative to
+ * the file's own directory. Supports comments, blank lines, `!` negation,
+ * leading-`/` anchoring, trailing-`/` directory-only rules, and `*`/`**`/`?`.
+ */
+export class IgnoreMatcher {
+    rules = [];
+    constructor(patterns) {
+        for (const line of patterns)
+            this.add(line);
+    }
+    add(raw) {
+        // Strip a trailing CR and unescaped trailing whitespace.
+        let line = raw.replace(/\r$/, "").replace(/(?<!\\)\s+$/, "");
+        if (line === "" || line.startsWith("#"))
+            return;
+        let negate = false;
+        if (line.startsWith("!")) {
+            negate = true;
+            line = line.slice(1);
+        }
+        // Unescape a leading "\#" / "\!".
+        line = line.replace(/^\\([#!])/, "$1");
+        let dirOnly = false;
+        if (line.endsWith("/")) {
+            dirOnly = true;
+            line = line.slice(0, -1);
+        }
+        const anchored = line.startsWith("/");
+        if (anchored)
+            line = line.slice(1);
+        // A pattern with an internal separator is anchored to this directory;
+        // otherwise it may match at any depth.
+        const hasInternalSlash = line.includes("/");
+        const prefix = anchored || hasInternalSlash ? "" : "(?:.*/)?";
+        // Trailing "(?:/.*)?" lets a directory match also cover its contents.
+        const re = new RegExp(`^${prefix}${globToRegexBody(line)}(?:/.*)?$`);
+        this.rules.push({ re, negate, dirOnly });
+    }
+    /**
+     * Decide whether `relPath` is ignored: `true`/`false` when a rule matches
+     * (last match wins), or `undefined` when no rule applies.
+     */
+    decide(relPath, isDir) {
+        let decision;
+        for (const rule of this.rules) {
+            if (rule.dirOnly && !isDir)
+                continue;
+            if (rule.re.test(relPath))
+                decision = !rule.negate;
+        }
+        return decision;
+    }
+}
+/**
+ * Resolve the ignore decision for a path against the full stack (shallow→deep);
+ * the deepest scope that makes a decision wins, mirroring git's precedence.
+ */
+function isIgnored(stack, absPath, isDir) {
+    let ignored = false;
+    for (const { baseDir, matcher } of stack) {
+        const rel = path.relative(baseDir, absPath).split(path.sep).join("/");
+        const decision = matcher.decide(rel, isDir);
+        if (decision !== undefined)
+            ignored = decision;
+    }
+    return ignored;
+}
+async function loadIgnoreScope(dir, ignoreFileNames) {
+    const patterns = [];
+    for (const name of ignoreFileNames) {
+        try {
+            const text = await fs.readFile(path.join(dir, name), "utf8");
+            patterns.push(...text.split("\n"));
+        }
+        catch {
+            /* no such ignore file in this directory */
+        }
+    }
+    return patterns.length > 0
+        ? { baseDir: dir, matcher: new IgnoreMatcher(patterns) }
+        : null;
+}
+async function isBinaryFile(absPath) {
+    const fh = await fs.open(absPath, "r");
+    try {
+        const buf = Buffer.alloc(4096);
+        const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+        return isBinary(buf.subarray(0, bytesRead));
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * Walk `root` and yield every indexable text file. Directories in the
+ * always-ignore set are skipped wholesale; ignore files accumulate down the
+ * tree; secret-bearing, oversized, and binary files are filtered out.
+ */
+export async function* walkRepo(root, opts) {
+    const absRoot = path.resolve(root);
+    const ignoreFileNames = opts.ignoreFileNames ?? DEFAULT_IGNORE_FILES;
+    yield* walkDir(absRoot, absRoot, [], ignoreFileNames, opts.maxFileBytes);
+}
+async function* walkDir(dir, root, parentStack, ignoreFileNames, maxFileBytes) {
+    const scope = await loadIgnoreScope(dir, ignoreFileNames);
+    const stack = scope ? [...parentStack, scope] : parentStack;
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // unreadable directory — skip
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const absPath = path.join(dir, entry.name);
+        const relPath = path.relative(root, absPath).split(path.sep).join("/");
+        const isDir = entry.isDirectory();
+        if (isDir && ALWAYS_IGNORE_DIRS.has(entry.name))
+            continue;
+        if (!isDir && !entry.isFile())
+            continue; // symlinks, sockets, fifos, etc.
+        if (isSecretPath(relPath))
+            continue;
+        if (isIgnored(stack, absPath, isDir))
+            continue;
+        if (isDir) {
+            yield* walkDir(absPath, root, stack, ignoreFileNames, maxFileBytes);
+            continue;
+        }
+        let size;
+        try {
+            size = (await fs.stat(absPath)).size;
+        }
+        catch {
+            continue;
+        }
+        if (size > maxFileBytes)
+            continue;
+        if (await isBinaryFile(absPath))
+            continue;
+        yield { relPath, absPath, size };
+    }
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./parser.js";
+export * from "./loader.js";
+export * from "./service.js";

package/dist/skills/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./parser.js";
+export * from "./loader.js";
+export * from "./service.js";

package/dist/skills/loader.d.ts

@@ -0,0 +1,42 @@
+import { type Skill, type SkillCatalog, type SkillError, type SkillSource } from "./types.js";
+/** The three source directories the loader scans. */
+export interface LoaderSources {
+    /** `<cwd>/.cruxy/skills` */
+    project: string;
+    /** `~/.cruxy/skills` */
+    user: string;
+    /** `<pkg>/skills` (shipped). */
+    builtin: string;
+}
+/** A valid skill discovered in a source, before precedence is resolved. */
+interface SkillCandidate {
+    name: string;
+    description: string;
+    source: SkillSource;
+    dir: string;
+}
+/** Thrown by `getSkill` when no catalog entry matches the requested name. */
+export declare class SkillNotFoundError extends Error {
+    constructor(message: string);
+}
+/**
+ * Scan all three sources, validate every SKILL.md, and resolve precedence into a
+ * {@link SkillCatalog}. Validation failures become {@link SkillError}s (excluded
+ * from the catalog, surfaced in `cruxy skills --status`) rather than throwing —
+ * one bad skill never breaks the rest.
+ */
+export declare function loadCatalog(sources: LoaderSources): Promise<SkillCatalog>;
+/**
+ * Resolve candidates into a catalog. Pure (no I/O) so precedence and collision
+ * rules are directly testable. `candidates` must arrive in precedence order
+ * (project first); the first occurrence of a name wins across sources, while a
+ * second occurrence *within the same source* is a loud, excluded error.
+ */
+export declare function resolvePrecedence(candidates: SkillCandidate[], baseErrors?: SkillError[]): SkillCatalog;
+/**
+ * Read a skill's full body and resolve its asset paths on demand. The body is
+ * re-read from disk every call (never cached), so edits are always live. Throws
+ * {@link SkillNotFoundError} if `name` isn't in the catalog.
+ */
+export declare function getSkill(catalog: SkillCatalog, name: string): Promise<Skill>;
+export {};

package/dist/skills/parser.d.ts

@@ -0,0 +1,29 @@
+import { type SkillFrontmatter } from "./types.js";
+/**
+ * Thrown when a SKILL.md is malformed or fails validation. The message is
+ * actionable (it names the problem) and is caught by the loader, which records
+ * it as a `SkillError` and excludes the skill — loud, never silently skipped.
+ */
+export declare class SkillValidationError extends Error {
+    constructor(message: string);
+}
+/** The validated frontmatter plus the markdown body that followed it. */
+export interface ParsedSkill {
+    frontmatter: SkillFrontmatter;
+    body: string;
+}
+/**
+ * Parse and validate a SKILL.md.
+ *
+ * The frontmatter is a deliberately small, strict subset of YAML — `key: value`
+ * scalars, optional surrounding quotes, `#` comment lines — which is all the
+ * two-field schema needs. Anything outside that subset (block scalars, nested
+ * maps, a line without a colon, a missing/unterminated block) is a loud error
+ * rather than a best-effort guess, so a skill never loads with a
+ * silently-misread description.
+ *
+ * @param text the raw file contents
+ * @param dirName the skill directory's basename; `name` must equal it
+ * @throws {SkillValidationError} on any malformed or invalid input
+ */
+export declare function parseSkill(text: string, dirName: string): ParsedSkill;

package/dist/skills/parser.js

@@ -0,0 +1,90 @@
+import { SkillFrontmatterSchema } from "./types.js";
+/**
+ * Thrown when a SKILL.md is malformed or fails validation. The message is
+ * actionable (it names the problem) and is caught by the loader, which records
+ * it as a `SkillError` and excludes the skill — loud, never silently skipped.
+ */
+export class SkillValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SkillValidationError";
+    }
+}
+// Opening `---` line, frontmatter content (non-greedy), closing `---` line, body.
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/;
+/**
+ * Parse and validate a SKILL.md.
+ *
+ * The frontmatter is a deliberately small, strict subset of YAML — `key: value`
+ * scalars, optional surrounding quotes, `#` comment lines — which is all the
+ * two-field schema needs. Anything outside that subset (block scalars, nested
+ * maps, a line without a colon, a missing/unterminated block) is a loud error
+ * rather than a best-effort guess, so a skill never loads with a
+ * silently-misread description.
+ *
+ * @param text the raw file contents
+ * @param dirName the skill directory's basename; `name` must equal it
+ * @throws {SkillValidationError} on any malformed or invalid input
+ */
+export function parseSkill(text, dirName) {
+    if (!/^---[ \t]*\r?\n/.test(text)) {
+        throw new SkillValidationError("SKILL.md must begin with a YAML frontmatter block delimited by '---'");
+    }
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match) {
+        throw new SkillValidationError("frontmatter block is not terminated by a closing '---' line");
+    }
+    const raw = parseFrontmatterBlock(match[1]);
+    const body = match[2] ?? "";
+    const result = SkillFrontmatterSchema.safeParse(raw);
+    if (!result.success) {
+        throw new SkillValidationError(`invalid frontmatter: ${formatZodError(result.error)}`);
+    }
+    const frontmatter = result.data;
+    if (frontmatter.name !== dirName) {
+        throw new SkillValidationError(`frontmatter name "${frontmatter.name}" must match the skill directory name "${dirName}"`);
+    }
+    return { frontmatter, body };
+}
+/** Parse the frontmatter block into a flat string map, strictly. */
+function parseFrontmatterBlock(block) {
+    const out = {};
+    for (const rawLine of block.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const colon = line.indexOf(":");
+        if (colon === -1) {
+            throw new SkillValidationError(`invalid frontmatter line (expected "key: value"): ${JSON.stringify(rawLine)}`);
+        }
+        const key = line.slice(0, colon).trim();
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(key)) {
+            throw new SkillValidationError(`invalid frontmatter key: ${JSON.stringify(key)}`);
+        }
+        if (key in out) {
+            throw new SkillValidationError(`duplicate frontmatter key: ${JSON.stringify(key)}`);
+        }
+        out[key] = stripQuotes(line.slice(colon + 1).trim());
+    }
+    return out;
+}
+/** Strip a single pair of matching surrounding quotes, if present. */
+function stripQuotes(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' || first === "'") && first === last) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+/** Render a zod error to a compact, single-line reason. */
+function formatZodError(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}

package/dist/skills/service.d.ts

@@ -0,0 +1,41 @@
+import { type LoaderSources } from "./loader.js";
+import { type Skill, type SkillCatalogEntry, type SkillStatus } from "./types.js";
+/** Logger surface the service reports through. */
+interface SkillServiceLogger {
+    debug(message: string): void;
+}
+/**
+ * A ready-to-use skills catalog for one project root. It resolves the three
+ * sources, caches the catalog, and refreshes lazily when a source directory's
+ * mtime changes (i.e. a skill was added or removed). Bodies are never cached —
+ * {@link SkillService.load} re-reads them on demand, so body edits are always
+ * live. Build one with {@link getSkillService}, which caches per cwd.
+ */
+export interface SkillService {
+    /** Catalog entries (name + description + source), refreshed if stale. */
+    list(): Promise<SkillCatalogEntry[]>;
+    /** Load one skill's body + resolved asset paths. Throws if unknown. */
+    load(name: string): Promise<Skill>;
+    /** Snapshot for `cruxy skills --status`: entries, errors, and source dirs. */
+    status(): Promise<SkillStatus>;
+}
+/**
+ * Explicit dependency overrides for tests — the only way to point the loader at
+ * fixture directories. Production callers never pass this, so they always use
+ * the real project/user/builtin sources.
+ */
+export interface SkillServiceDeps {
+    sources?: Partial<LoaderSources>;
+}
+/** The default source directories for a project root. */
+export declare function defaultSources(cwd: string): LoaderSources;
+/**
+ * Get (or build) the {@link SkillService} for a project root, cached per
+ * resolved cwd. Construction is cheap (just path resolution); the catalog is
+ * built lazily on first use and refreshed on source-mtime change. `deps` is for
+ * explicit test injection only (see {@link SkillServiceDeps}).
+ */
+export declare function getSkillService(cwd: string, logger: SkillServiceLogger, deps?: SkillServiceDeps): SkillService;
+/** Drop all cached services. For tests and process teardown. */
+export declare function resetSkillServices(): void;
+export {};

package/dist/skills/service.js

@@ -0,0 +1,92 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/index.js";
+import { BUILTIN_SKILLS_DIR, GLOBAL_DIR_NAME, SKILLS_DIR_NAME, } from "../constants.js";
+import { getSkill, loadCatalog } from "./loader.js";
+import { SOURCE_PRECEDENCE, } from "./types.js";
+/** The default source directories for a project root. */
+export function defaultSources(cwd) {
+    const root = path.resolve(cwd);
+    return {
+        project: path.join(root, GLOBAL_DIR_NAME, SKILLS_DIR_NAME),
+        user: path.join(globalDir(), SKILLS_DIR_NAME),
+        builtin: BUILTIN_SKILLS_DIR,
+    };
+}
+class SkillServiceImpl {
+    sources;
+    logger;
+    catalog = null;
+    signature = "";
+    constructor(sources, logger) {
+        this.sources = sources;
+        this.logger = logger;
+    }
+    async ensureFresh() {
+        const signature = await computeSignature(this.sources);
+        if (this.catalog === null || signature !== this.signature) {
+            this.logger.debug("(re)building skill catalog");
+            this.catalog = await loadCatalog(this.sources);
+            this.signature = signature;
+        }
+        return this.catalog;
+    }
+    async list() {
+        return (await this.ensureFresh()).entries;
+    }
+    async load(name) {
+        return getSkill(await this.ensureFresh(), name);
+    }
+    async status() {
+        const catalog = await this.ensureFresh();
+        return {
+            entries: catalog.entries,
+            errors: catalog.errors,
+            sources: SOURCE_PRECEDENCE.map((source) => ({
+                source,
+                dir: this.sources[source],
+            })),
+        };
+    }
+}
+// ── per-cwd cache ─────────────────────────────────────────────────────────────
+const cache = new Map();
+/**
+ * Get (or build) the {@link SkillService} for a project root, cached per
+ * resolved cwd. Construction is cheap (just path resolution); the catalog is
+ * built lazily on first use and refreshed on source-mtime change. `deps` is for
+ * explicit test injection only (see {@link SkillServiceDeps}).
+ */
+export function getSkillService(cwd, logger, deps) {
+    const root = path.resolve(cwd);
+    let service = cache.get(root);
+    if (!service) {
+        const sources = { ...defaultSources(root), ...(deps?.sources ?? {}) };
+        service = new SkillServiceImpl(sources, logger);
+        cache.set(root, service);
+    }
+    return service;
+}
+/** Drop all cached services. For tests and process teardown. */
+export function resetSkillServices() {
+    cache.clear();
+}
+/**
+ * A cheap change signature: the mtime of each source directory. A directory's
+ * mtime changes when an entry is added or removed, so this catches new/deleted
+ * skills. (Editing a body in place doesn't change it — but `load` always
+ * re-reads bodies fresh, so only the cached catalog's name/description can lag.)
+ */
+async function computeSignature(sources) {
+    const parts = [];
+    for (const source of SOURCE_PRECEDENCE) {
+        try {
+            const stat = await fs.stat(sources[source]);
+            parts.push(`${source}:${stat.mtimeMs}`);
+        }
+        catch {
+            parts.push(`${source}:absent`);
+        }
+    }
+    return parts.join("|");
+}

package/dist/skills/types.d.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+/**
+ * Shared types for the skills system (C.18). A *skill* is a directory holding a
+ * `SKILL.md` — YAML frontmatter (name + description) plus a markdown
+ * instructions body — and optional `scripts/` and `reference/` asset subdirs.
+ *
+ * Progressive disclosure is the whole point: only `name` + `description` enter
+ * the agent's context by default (the catalog); the full body is read on demand
+ * by `load_skill`. Bodies are never held in the cached catalog.
+ */
+/** Where a skill was discovered, highest precedence first. */
+export type SkillSource = "project" | "user" | "builtin";
+/** Precedence order: project overrides user overrides builtin. */
+export declare const SOURCE_PRECEDENCE: readonly SkillSource[];
+/**
+ * Strict schema for SKILL.md frontmatter. `.strict()` rejects unknown keys, so a
+ * typo'd field is a loud error rather than silently ignored. `name` is
+ * kebab-case and must equal the skill's directory name (enforced by the parser).
+ */
+export declare const SkillFrontmatterSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    description: string;
+}, {
+    name: string;
+    description: string;
+}>;
+export type SkillFrontmatter = z.infer<typeof SkillFrontmatterSchema>;
+/**
+ * The cheap catalog entry the agent sees by default — name, one-line
+ * description, and which source won. No body.
+ */
+export interface SkillCatalogEntry {
+    name: string;
+    description: string;
+    source: SkillSource;
+}
+/**
+ * A fully-loaded skill, returned by `load_skill`/`getSkill`. Carries the
+ * markdown body plus resolved, in-bounds asset paths.
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    source: SkillSource;
+    /** Markdown instructions (everything after the frontmatter block). */
+    body: string;
+    /** Absolute path of the skill directory — the root for its assets. */
+    assetRoot: string;
+    /** Project-relative-to-assetRoot POSIX paths of files under `scripts/`. */
+    scripts: string[];
+    /** Project-relative-to-assetRoot POSIX paths of files under `reference/`. */
+    references: string[];
+}
+/**
+ * A validation failure for one candidate skill. Collected (never thrown past the
+ * loader) so one bad skill can't break the catalog; surfaced loudly in
+ * `cruxy skills --status` and excluded from the catalog.
+ */
+export interface SkillError {
+    source: SkillSource;
+    /** Absolute path of the offending skill directory. */
+    dir: string;
+    /** The directory's basename (the would-be skill name), for display. */
+    name: string;
+    /** Actionable, human-readable reason. */
+    message: string;
+}
+/**
+ * The resolved catalog: valid entries (deduped by precedence), the validation
+ * errors that were excluded, and a name→location index used by `getSkill` to
+ * read a body on demand. Bodies are intentionally absent.
+ */
+export interface SkillCatalog {
+    entries: SkillCatalogEntry[];
+    errors: SkillError[];
+    /** name → winning skill's directory + source (for on-demand body reads). */
+    byName: Map<string, {
+        dir: string;
+        source: SkillSource;
+    }>;
+}
+/** Snapshot for `cruxy skills --status`. */
+export interface SkillStatus {
+    entries: SkillCatalogEntry[];
+    errors: SkillError[];
+    /** The three source directories, in precedence order. */
+    sources: {
+        source: SkillSource;
+        dir: string;
+    }[];
+}

package/dist/skills/types.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+/** Precedence order: project overrides user overrides builtin. */
+export const SOURCE_PRECEDENCE = [
+    "project",
+    "user",
+    "builtin",
+];
+/**
+ * Strict schema for SKILL.md frontmatter. `.strict()` rejects unknown keys, so a
+ * typo'd field is a loud error rather than silently ignored. `name` is
+ * kebab-case and must equal the skill's directory name (enforced by the parser).
+ */
+export const SkillFrontmatterSchema = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .regex(/^[a-z0-9][a-z0-9-]*$/, "must be kebab-case: lowercase letters, digits, and hyphens, starting with a letter or digit"),
+    description: z.string().min(1),
+})
+    .strict();

package/dist/tools/index.d.ts

@@ -2,4 +2,7 @@ export * from "./types.js";
 export * from "./registry.js";
 export * from "./list-files.js";
 export * from "./git-status.js";
+export * from "./search-codebase.js";
+export * from "./list-skills.js";
+export * from "./load-skill.js";
 export * from "./file/index.js";

package/dist/tools/index.js

@@ -2,4 +2,7 @@ export * from "./types.js";
 export * from "./registry.js";
 export * from "./list-files.js";
 export * from "./git-status.js";
+export * from "./search-codebase.js";
+export * from "./list-skills.js";
+export * from "./load-skill.js";
 export * from "./file/index.js";

package/dist/tools/list-skills.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import type { Tool } from "./types.js";
+/**
+ * List the available skills (name + one-line description + source). Read-only —
+ * no approval — like the other discovery tools. This is the cheap half of
+ * progressive disclosure: only the catalog enters context here; the agent calls
+ * `load_skill` to pull a skill's full instructions when a task matches.
+ */
+export declare const listSkillsTool: Tool<z.ZodObject<Record<string, never>>>;

package/dist/tools/list-skills.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { getSkillService } from "../skills/index.js";
+/**
+ * List the available skills (name + one-line description + source). Read-only —
+ * no approval — like the other discovery tools. This is the cheap half of
+ * progressive disclosure: only the catalog enters context here; the agent calls
+ * `load_skill` to pull a skill's full instructions when a task matches.
+ */
+export const listSkillsTool = {
+    name: "list_skills",
+    description: "List the specialized skills available for this project (name, description, and source: project/user/builtin). Call this when a task might match a skill; then call load_skill to load the one that fits. Read-only and requires no approval.",
+    parameters: z.object({}),
+    async execute(_input, ctx) {
+        try {
+            const entries = await getSkillService(ctx.cwd, ctx.logger).list();
+            if (entries.length === 0) {
+                return {
+                    ok: true,
+                    output: "(no skills available — add one under .cruxy/skills/ or ~/.cruxy/skills/)",
+                };
+            }
+            return { ok: true, output: formatCatalog(entries) };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    },
+};
+/** Render the catalog as a compact, model-readable list. */
+function formatCatalog(entries) {
+    return entries
+        .map((e) => `- ${e.name} [${e.source}] — ${e.description}`)
+        .join("\n");
+}