@cruxy/cli 0.2.0 → 0.3.0

package/README.md

@@ -25,12 +25,18 @@ cruxy run                           # interactive session
 ## Features
 
 - **Tools** — `read_file`, `write_file`, `edit_file`, `glob`, `list_files`,
-  `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`.
+  `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`,
+  `list_skills`, `load_skill`.
 - **Codebase index** — a local, incremental semantic index (`cruxy index`)
   behind the `search_codebase` tool. Embeddings run on-device via fastembed
   (ONNX, bge-small-en-v1.5) with no network calls; the store is SQLite at
   `.cruxy/index.db`. Only changed files are re-embedded; `.gitignore` /
   `.cruxyignore` are respected and secrets (`.env*`, keys) are never indexed.
+- **Skills** — reusable, task-specific instructions in a `SKILL.md`
+  (frontmatter + markdown), discovered via `list_skills` and pulled on demand
+  with `load_skill` (progressive disclosure: only name + description are in
+  context until a skill is loaded). Layered project > user > builtin, strictly
+  validated, and never auto-executed.
 - **Agent** — streaming output, multi-turn interactive sessions, context
   compaction, and awareness of git state and project instructions (`CRUXY.md`).
 - **Safety** — a single approval gate with diff previews that fails closed;
@@ -53,6 +59,17 @@ The index refreshes itself lazily the first time the agent calls
 `search_codebase`, so it works even without running `cruxy index` first. The
 bge-small embedding model (~130 MB) downloads and caches on first use.
 
+### Skills
+
+```bash
+cruxy skills            # list the resolved skill catalog
+cruxy skills --status   # show source directories and validation errors
+```
+
+Add a skill by creating `<name>/SKILL.md` under `.cruxy/skills/` (project) or
+`~/.cruxy/skills/` (user); shipped builtins are the lowest layer. See the
+built-in `using-skills` skill for the authoring rules.
+
 The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
 provider-agnostic, built over `fetch`, with no vendor SDKs.
 

package/dist/cli/commands/skills.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy skills` — list the skills available to the agent (the same catalog the
+ * `list_skills` tool sees). `--status` additionally shows the three source
+ * directories in precedence order and any validation errors (skills that were
+ * excluded for being malformed).
+ */
+export declare function skillsCommand(): Command;

package/dist/cli/commands/skills.js

@@ -0,0 +1,51 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { getSkillService, resetSkillServices } from "../../skills/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy skills` — list the skills available to the agent (the same catalog the
+ * `list_skills` tool sees). `--status` additionally shows the three source
+ * directories in precedence order and any validation errors (skills that were
+ * excluded for being malformed).
+ */
+export function skillsCommand() {
+    return new Command("skills")
+        .description("list the skills available to the agent")
+        .option("--status", "show source directories and validation errors")
+        .action(async (opts) => {
+        const service = getSkillService(process.cwd(), logger);
+        const status = await service.status();
+        if (status.entries.length === 0) {
+            logger.print(pc.dim("no skills found"));
+        }
+        else {
+            for (const entry of status.entries) {
+                logger.print(`${pc.bold(entry.name)}  ${pc.dim(`[${entry.source}]`)}`);
+                logger.print(`  ${entry.description}`);
+            }
+        }
+        if (!opts.status) {
+            if (status.errors.length > 0) {
+                logger.print(pc.yellow(`\n${status.errors.length} skill(s) failed validation — run ${pc.bold("cruxy skills --status")} for details`));
+            }
+            resetSkillServices();
+            return;
+        }
+        logger.print(`\n${pc.bold("sources")} ${pc.dim("(precedence high → low):")}`);
+        for (const { source, dir } of status.sources) {
+            logger.print(`  ${source.padEnd(8)} ${pc.dim(dir)}`);
+        }
+        logger.print("");
+        if (status.errors.length === 0) {
+            logger.print(pc.green("no validation errors"));
+        }
+        else {
+            logger.print(pc.yellow(`validation errors (${status.errors.length}):`));
+            for (const err of status.errors) {
+                logger.print(`  ${pc.red("✗")} ${pc.bold(err.name)} ${pc.dim(`[${err.source}]`)}: ${err.message}`);
+                logger.print(`    ${pc.dim(err.dir)}`);
+            }
+        }
+        resetSkillServices();
+    });
+}

package/dist/cli/program.js

@@ -5,6 +5,7 @@ import { logger } from "../utils/logger.js";
 import { runCommand } from "./commands/run.js";
 import { configCommand } from "./commands/config.js";
 import { indexCommand } from "./commands/index.js";
+import { skillsCommand } from "./commands/skills.js";
 export function buildProgram() {
     const program = new Command();
     program
@@ -26,6 +27,7 @@ export function buildProgram() {
     program.addCommand(runCommand());
     program.addCommand(configCommand());
     program.addCommand(indexCommand());
+    program.addCommand(skillsCommand());
     // Default action: no subcommand -> interactive entrypoint (stub for now).
     program.action(() => {
         logger.print(pc.cyan(`${APP_NAME} v${APP_VERSION}`));

package/dist/constants.d.ts

@@ -9,3 +9,16 @@ export declare const CONFIG_FILE_NAME = "config.json";
 export declare const PROJECT_CONFIG_FILENAMES: string[];
 /** Project-instruction filenames, checked in order (first match wins). */
 export declare const PROJECT_INSTRUCTION_FILENAMES: string[];
+/**
+ * Name of the skills subdirectory, used under the project dir
+ * (`<cwd>/.cruxy/skills`), the global dir (`~/.cruxy/skills`), and the package
+ * root for shipped builtins.
+ */
+export declare const SKILLS_DIR_NAME = "skills";
+/**
+ * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
+ * Anchored the same way as the package.json lookup above: both `dist/` and
+ * `src/` sit one level below the package root, so `../skills` resolves to the
+ * shipped `skills/` directory in dev, in `dist`, and when published.
+ */
+export declare const BUILTIN_SKILLS_DIR: string;

package/dist/constants.js

@@ -29,3 +29,16 @@ export const PROJECT_CONFIG_FILENAMES = [
 ];
 /** Project-instruction filenames, checked in order (first match wins). */
 export const PROJECT_INSTRUCTION_FILENAMES = ["CRUXY.md", "AGENTS.md"];
+/**
+ * Name of the skills subdirectory, used under the project dir
+ * (`<cwd>/.cruxy/skills`), the global dir (`~/.cruxy/skills`), and the package
+ * root for shipped builtins.
+ */
+export const SKILLS_DIR_NAME = "skills";
+/**
+ * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
+ * Anchored the same way as the package.json lookup above: both `dist/` and
+ * `src/` sit one level below the package root, so `../skills` resolves to the
+ * shipped `skills/` directory in dev, in `dist`, and when published.
+ */
+export const BUILTIN_SKILLS_DIR = join(__dirname, "..", SKILLS_DIR_NAME);

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

@@ -3,4 +3,6 @@ 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

@@ -3,4 +3,6 @@ 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");
+}

package/dist/tools/load-skill.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { Tool } from "./types.js";
+declare const parameters: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+/**
+ * Load a skill's full instructions on demand — the expensive half of
+ * progressive disclosure. Returns the markdown body plus the absolute asset root
+ * and the relative paths of any `scripts/` and `reference/` files, so the agent
+ * can read or run them through the existing read_file / run_command tools.
+ *
+ * Read-only — no approval. Loading a skill never executes anything: scripts are
+ * surfaced as paths only and run, if at all, through run_command (which applies
+ * the normal approval gate).
+ */
+export declare const loadSkillTool: Tool<typeof parameters>;
+export {};

package/dist/tools/load-skill.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { getSkillService } from "../skills/index.js";
+const parameters = z.object({
+    name: z
+        .string()
+        .min(1)
+        .describe("The exact name of the skill to load (from list_skills)."),
+});
+/**
+ * Load a skill's full instructions on demand — the expensive half of
+ * progressive disclosure. Returns the markdown body plus the absolute asset root
+ * and the relative paths of any `scripts/` and `reference/` files, so the agent
+ * can read or run them through the existing read_file / run_command tools.
+ *
+ * Read-only — no approval. Loading a skill never executes anything: scripts are
+ * surfaced as paths only and run, if at all, through run_command (which applies
+ * the normal approval gate).
+ */
+export const loadSkillTool = {
+    name: "load_skill",
+    description: "Load the full instructions for a skill by name (discover names with list_skills). Returns the skill's markdown body plus the paths of any bundled scripts/reference files. Read-only and requires no approval — it never runs anything; use run_command to execute a script the skill describes.",
+    parameters,
+    async execute(input, ctx) {
+        try {
+            const skill = await getSkillService(ctx.cwd, ctx.logger).load(input.name);
+            return { ok: true, output: formatSkill(skill) };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    },
+};
+/** Render a loaded skill: instructions, then an asset reference footer. */
+function formatSkill(skill) {
+    const parts = [
+        `# Skill: ${skill.name} (${skill.source})`,
+        "",
+        skill.body.trim(),
+    ];
+    const footer = [`Asset root: ${skill.assetRoot}`];
+    if (skill.scripts.length > 0) {
+        footer.push(`Scripts (run via run_command — not auto-executed): ${skill.scripts.join(", ")}`);
+    }
+    if (skill.references.length > 0) {
+        footer.push(`References (read via read_file): ${skill.references.join(", ")}`);
+    }
+    parts.push("", "---", footer.join("\n"));
+    return parts.join("\n");
+}

package/dist/tools/registry.js

@@ -4,6 +4,8 @@ import { gitStatusTool } from "./git-status.js";
 import { readFileTool, writeFileTool, editFileTool, applyPatchTool, globTool, grepFilesTool, } from "./file/index.js";
 import { runCommandTool } from "./shell/index.js";
 import { searchCodebaseTool } from "./search-codebase.js";
+import { listSkillsTool } from "./list-skills.js";
+import { loadSkillTool } from "./load-skill.js";
 /**
  * In-memory catalogue of the tools available to the agent. Names are unique;
  * `toToolSpecs()` projects the catalogue into the `@cruxy/sdk` wire format.
@@ -61,5 +63,7 @@ export function buildDefaultRegistry() {
     registry.register(gitStatusTool);
     registry.register(runCommandTool);
     registry.register(searchCodebaseTool);
+    registry.register(listSkillsTool);
+    registry.register(loadSkillTool);
     return registry;
 }

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
     "cruxy": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "engines": {
     "node": ">=20"

package/skills/git-commit/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: git-commit
+description: Write a conventional commit message that passes this repo's commitlint. Use when committing, writing a commit message, or opening a PR in cruxy.
+---
+
+# Writing commit messages for cruxy
+
+This repo enforces [Conventional Commits](https://www.conventionalcommits.org)
+via commitlint (a husky `commit-msg` hook) plus changesets. Follow this to get a
+message that passes on the first try.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+- **type** — one of `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`,
+  `build`, `ci`, `style`, `revert`.
+- **scope** _(optional, but if present must be in the allow-list)_ —
+  `cli`, `sdk`, `ui`, `api`, `auth`, `billing`, `web`, `dashboard`, `docs`,
+  `ide`, `infra`, `pricing`, `repo`, `ci`. The canonical list lives in
+  `commitlint.config.cjs` (`scope-enum`).
+- **subject** — imperative mood, no trailing period.
+
+## The rule people trip on
+
+**The subject must NOT start with a capital letter.** commitlint's
+`subject-case` rejects sentence-case / start-case / pascal-case / upper-case, so
+a subject beginning with an uppercase letter fails the hook (and CI). A tag like
+`C.18` cannot be the first token.
+
+- ✅ `feat(cli): codebase indexing + search_codebase (C.18)`
+- ❌ `feat(cli): C.18 codebase indexing` — capital `C` ⇒ sentence-case ⇒ rejected.
+
+Put any phase/issue tag in a parenthetical at the end, or lowercase the lead.
+
+## Body and footer
+
+- Wrap the body at ~72 columns; explain _what_ and _why_, not _how_.
+- A breaking change uses `!` after the type/scope (`feat(cli)!: …`) and/or a
+  `BREAKING CHANGE:` footer.
+- Co-author trailers go in the footer, e.g.
+  `Co-Authored-By: Name <email>`.
+
+## Don't forget the changeset
+
+User-facing changes need a changeset: run `pnpm changeset` (or add a file under
+`.changeset/`) describing the change and the semver bump for the affected
+package (e.g. `@cruxy/cli` minor).
+
+## Quick check
+
+If a commit is rejected with `subject must not be sentence-case … [subject-case]`,
+lowercase the first word of the subject (or move the capitalized tag into a
+trailing parenthetical) and recommit.

package/skills/using-skills/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: using-skills
+description: How cruxy skills work and how to author a SKILL.md. Use when the user asks about skills or wants to create or edit one.
+---
+
+# Skills in cruxy
+
+A **skill** is a directory containing a `SKILL.md` — YAML frontmatter plus a
+markdown instructions body — that packages reusable, task-specific know-how for
+the agent. Discover skills with the `list_skills` tool and pull a skill's full
+instructions with `load_skill` when a task matches its description.
+
+## Progressive disclosure
+
+Only each skill's `name` and `description` are visible by default (a cheap
+catalog). The full body is loaded **on demand** via `load_skill`, so a large
+library of skills costs almost nothing until one is actually used. Write the
+`description` so the agent can tell, from one line, _when_ to reach for the
+skill.
+
+## Authoring a SKILL.md
+
+Create `skills/<name>/SKILL.md`:
+
+```
+---
+name: <name>
+description: <one line — what it does and when to use it>
+---
+
+# instructions
+…the body the agent reads after load_skill…
+```
+
+Rules (all enforced, fail-loud):
+
+- `name` is kebab-case (`^[a-z0-9][a-z0-9-]*$`) and **must equal the directory
+  name**.
+- `description` is required and non-empty.
+- Frontmatter is strict: unknown keys, missing fields, or malformed YAML are
+  reported in `cruxy skills --status` and the skill is excluded from the
+  catalog.
+
+## Sources and precedence
+
+Skills are discovered from three layers; on a name collision the higher layer
+wins:
+
+1. **project** — `<cwd>/.cruxy/skills/`
+2. **user** — `~/.cruxy/skills/`
+3. **builtin** — shipped with the CLI
+
+Run `cruxy skills` to see the resolved catalog, or `cruxy skills --status` to see
+the source directories and any validation errors.
+
+## Bundled assets
+
+A skill may include `scripts/` and `reference/` subdirectories. `load_skill`
+returns their paths, but **nothing is auto-executed** — the agent runs a script
+through `run_command` (which goes through the normal approval gate) and reads a
+reference through `read_file`. Skills are data, not a privileged execution path,
+and may only reference files inside their own directory.