@dsh-cc/skill-loader 0.5.0

package/lib/bundled/index.js

@@ -0,0 +1,47 @@
+/**
+ * Bundled skills shipped with this compatible provider.
+ *
+ * A portable subset of Claude Code's own bundled skills (`~/workspace/github.com/claude-code/skills/bundled/`),
+ * authored as `SKILL.md` documents and served directly from this package — no
+ * disk extraction. They are provided with `source: 'bundled'` and the registry's
+ * `BUNDLED_SKILL_RANK`, so any project, user, managed, or additional skill of the
+ * same name wins the name conflict — matching Claude Code's precedence where
+ * local skills override built-ins.
+ *
+ * Only self-contained, harness-portable skills are included; ant-only skills
+ * (`verify`, `stuck`) and claude.ai/vendor-bound skills are excluded.
+ *
+ * @module
+ */
+import { isSkillName } from '@deepseek-ai/dsh-skill';
+import { parseCcFrontmatter, parseCcFrontmatterDocument, } from "../frontmatter.js";
+import { SKILL_MD as BATCH_MD, name as batchName } from "./batch.js";
+import { SKILL_MD as DEBUG_MD, name as debugName } from "./debug.js";
+import { SKILL_MD as SIMPLIFY_MD, name as simplifyName } from "./simplify.js";
+const ENTRIES = [
+    { name: debugName, md: DEBUG_MD },
+    { name: simplifyName, md: SIMPLIFY_MD },
+    { name: batchName, md: BATCH_MD },
+];
+/** Parse the in-package bundled skill set once. Skills with missing or invalid names are skipped. */
+export function discoverBundledSkills() {
+    const result = [];
+    for (const { name, md } of ENTRIES) {
+        const parsed = parseCcFrontmatter(md);
+        if (parsed === undefined || parsed.name === undefined || !isSkillName(parsed.name))
+            continue;
+        if (parsed.name !== name)
+            continue;
+        const body = parseCcFrontmatterDocument(md)?.body ?? '';
+        result.push({
+            kind: 'bundled',
+            name,
+            directory: `bundled:${name}`,
+            path: `bundled:${name}/SKILL.md`,
+            body,
+            parsed: { ...parsed, name },
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/lib/bundled/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bundled/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACpD,OAAO,EACL,kBAAkB,EAClB,0BAA0B,GAE3B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,QAAQ,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,YAAY,CAAA;AACpE,OAAO,EAAE,QAAQ,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,YAAY,CAAA;AACpE,OAAO,EAAE,QAAQ,IAAI,WAAW,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,eAAe,CAAA;AAkB7E,MAAM,OAAO,GAA8D;IACzE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE;IACjC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,WAAW,EAAE;IACvC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE;CAClC,CAAA;AAED,qGAAqG;AACrG,MAAM,UAAU,qBAAqB;IACnC,MAAM,MAAM,GAAuB,EAAE,CAAA;IACrC,KAAK,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,OAAO,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAA;QACrC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,SAAQ;QAC5F,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI;YAAE,SAAQ;QAClC,MAAM,IAAI,GAAG,0BAA0B,CAAC,EAAE,CAAC,EAAE,IAAI,IAAI,EAAE,CAAA;QACvD,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,SAAS;YACf,IAAI;YACJ,SAAS,EAAE,WAAW,IAAI,EAAE;YAC5B,IAAI,EAAE,WAAW,IAAI,WAAW;YAChC,IAAI;YACJ,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE;SAC5B,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/lib/bundled/simplify.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Ported Claude Code bundled `simplify` skill.
+ *
+ * Source: `~/workspace/github.com/claude-code/skills/bundled/simplify.ts`. The
+ * original author tool reference (`${AGENT_TOOL_NAME}`, the `Agent` tool) is
+ * kept as a literal template placeholder; the body is otherwise verbatim.
+ *
+ * @module
+ */
+export declare const name = "simplify";
+export declare const SKILL_MD = "---\nname: simplify\ndescription: Review changed code for reuse, quality, and efficiency, then fix any issues found.\nuser-invocable: true\n---\n\n# Simplify: Code Review and Cleanup\n\nReview all changed files for reuse, quality, and efficiency. Fix any issues found.\n\n## Phase 1: Identify Changes\n\nRun `git diff` (or `git diff HEAD` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.\n\n## Phase 2: Launch Three Review Agents in Parallel\n\nUse the ${AGENT_TOOL_NAME} tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.\n\n### Agent 1: Code Reuse Review\n\nFor each change:\n\n1. **Search for existing utilities and helpers** that could replace newly written code. Look for similar patterns elsewhere in the codebase \u2014 common locations are utility directories, shared modules, and files adjacent to the changed ones.\n2. **Flag any new function that duplicates existing functionality.** Suggest the existing function to use instead.\n3. **Flag any inline logic that could use an existing utility** \u2014 hand-rolled string manipulation, manual path handling, custom environment checks, ad-hoc type guards, and similar patterns are common candidates.\n\n### Agent 2: Code Quality Review\n\nReview the same changes for hacky patterns:\n\n1. **Redundant state**: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls\n2. **Parameter sprawl**: adding new parameters to a function instead of generalizing or restructuring existing ones\n3. **Copy-paste with slight variation**: near-duplicate code blocks that should be unified with a shared abstraction\n4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries\n5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase\n6. **Unnecessary JSX nesting**: wrapper Boxes/elements that add no layout value \u2014 check if inner component props (flexShrink, alignItems, etc.) already provide the needed behavior\n7. **Unnecessary comments**: comments explaining WHAT the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller \u2014 delete; keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds)\n\n### Agent 3: Efficiency Review\n\nReview the same changes for efficiency:\n\n1. **Unnecessary work**: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns\n2. **Missed concurrency**: independent operations run sequentially when they could run in parallel\n3. **Hot-path bloat**: new blocking work added to startup or per-request/per-render hot paths\n4. **Recurring no-op updates**: state/store updates inside polling loops, intervals, or event handlers that fire unconditionally \u2014 add a change-detection guard so downstream consumers aren't notified when nothing changed. Also: if a wrapper function takes an updater/reducer callback, verify it honors same-reference returns (or whatever the \"no change\" signal is) \u2014 otherwise callers' early-return no-ops are silently defeated\n5. **Unnecessary existence checks**: pre-checking file/resource existence before operating (TOCTOU anti-pattern) \u2014 operate directly and handle the error\n6. **Memory**: unbounded data structures, missing cleanup, event listener leaks\n7. **Overly broad operations**: reading entire files when only a portion is needed, loading all items when filtering for one\n\n## Phase 3: Fix Issues\n\nWait for all three agents to complete. Aggregate their findings and fix each issue directly. If a finding is a false positive or not worth addressing, note it and move on \u2014 do not argue with the finding, just skip it.\n\nWhen done, briefly summarize what was fixed (or confirm the code was already clean).\n";
+//# sourceMappingURL=simplify.d.ts.map

package/lib/bundled/simplify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simplify.d.ts","sourceRoot":"","sources":["../../src/bundled/simplify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,IAAI,aAAa,CAAA;AAE9B,eAAO,MAAM,QAAQ,y/HAuDpB,CAAA"}

package/lib/bundled/simplify.js

@@ -0,0 +1,67 @@
+/**
+ * Ported Claude Code bundled `simplify` skill.
+ *
+ * Source: `~/workspace/github.com/claude-code/skills/bundled/simplify.ts`. The
+ * original author tool reference (`${AGENT_TOOL_NAME}`, the `Agent` tool) is
+ * kept as a literal template placeholder; the body is otherwise verbatim.
+ *
+ * @module
+ */
+export const name = 'simplify';
+export const SKILL_MD = `---
+name: simplify
+description: Review changed code for reuse, quality, and efficiency, then fix any issues found.
+user-invocable: true
+---
+
+# Simplify: Code Review and Cleanup
+
+Review all changed files for reuse, quality, and efficiency. Fix any issues found.
+
+## Phase 1: Identify Changes
+
+Run \`git diff\` (or \`git diff HEAD\` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.
+
+## Phase 2: Launch Three Review Agents in Parallel
+
+Use the \${AGENT_TOOL_NAME} tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
+
+### Agent 1: Code Reuse Review
+
+For each change:
+
+1. **Search for existing utilities and helpers** that could replace newly written code. Look for similar patterns elsewhere in the codebase — common locations are utility directories, shared modules, and files adjacent to the changed ones.
+2. **Flag any new function that duplicates existing functionality.** Suggest the existing function to use instead.
+3. **Flag any inline logic that could use an existing utility** — hand-rolled string manipulation, manual path handling, custom environment checks, ad-hoc type guards, and similar patterns are common candidates.
+
+### Agent 2: Code Quality Review
+
+Review the same changes for hacky patterns:
+
+1. **Redundant state**: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls
+2. **Parameter sprawl**: adding new parameters to a function instead of generalizing or restructuring existing ones
+3. **Copy-paste with slight variation**: near-duplicate code blocks that should be unified with a shared abstraction
+4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries
+5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase
+6. **Unnecessary JSX nesting**: wrapper Boxes/elements that add no layout value — check if inner component props (flexShrink, alignItems, etc.) already provide the needed behavior
+7. **Unnecessary comments**: comments explaining WHAT the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller — delete; keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds)
+
+### Agent 3: Efficiency Review
+
+Review the same changes for efficiency:
+
+1. **Unnecessary work**: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns
+2. **Missed concurrency**: independent operations run sequentially when they could run in parallel
+3. **Hot-path bloat**: new blocking work added to startup or per-request/per-render hot paths
+4. **Recurring no-op updates**: state/store updates inside polling loops, intervals, or event handlers that fire unconditionally — add a change-detection guard so downstream consumers aren't notified when nothing changed. Also: if a wrapper function takes an updater/reducer callback, verify it honors same-reference returns (or whatever the "no change" signal is) — otherwise callers' early-return no-ops are silently defeated
+5. **Unnecessary existence checks**: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error
+6. **Memory**: unbounded data structures, missing cleanup, event listener leaks
+7. **Overly broad operations**: reading entire files when only a portion is needed, loading all items when filtering for one
+
+## Phase 3: Fix Issues
+
+Wait for all three agents to complete. Aggregate their findings and fix each issue directly. If a finding is a false positive or not worth addressing, note it and move on — do not argue with the finding, just skip it.
+
+When done, briefly summarize what was fixed (or confirm the code was already clean).
+`;
+//# sourceMappingURL=simplify.js.map

package/lib/bundled/simplify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simplify.js","sourceRoot":"","sources":["../../src/bundled/simplify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,IAAI,GAAG,UAAU,CAAA;AAE9B,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDvB,CAAA"}

package/lib/discovery.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Claude Code skill discovery: root ordering, directory walking, and realpath
+ * deduplication.
+ *
+ * This module finds `<name>/SKILL.md` skills across managed, project, user, and
+ * additional roots in that priority order, plus legacy `.claude/commands/*.md`
+ * files marked as deprecated sources. Discovery reads only frontmatter so the
+ * catalog stays cheap; bodies load on `get()`.
+ *
+ * @module
+ */
+/** Discovery source bucket for one Claude Code skill file. */
+export type CcSkillSource = 'managed' | 'user' | 'project' | 'additional';
+/** Precedence rank (lower wins) for a discovery root within the provider. */
+export type CcRootRank = 100 | 200 | 300 | 400;
+/** A discovered Claude Code skill file locator. */
+export interface CcSkillFile {
+    /** Kebab-case skill name derived from its directory or file name. */
+    readonly name: string;
+    /** Absolute path to `SKILL.md` or a deprecated flat `.md`. */
+    readonly path: string;
+    /** Absolute base directory for relative resources in the body. */
+    readonly directory: string;
+    /** Discovery source bucket. */
+    readonly source: CcSkillSource;
+    /** Precedence rank (lower wins name conflicts). */
+    readonly rank: CcRootRank;
+    /** Whether this came from legacy `.claude/commands/*.md`. */
+    readonly deprecated: boolean;
+}
+/** One candidate root scanned for skills, in discovery order. */
+export interface CcRoot {
+    /** Absolute root path containing `<name>/SKILL.md` entries. */
+    readonly path: string;
+    /** Discovery source bucket. */
+    readonly source: CcSkillSource;
+    /** Precedence rank (lower wins). */
+    readonly rank: CcRootRank;
+    /** Legacy flat-`.md` directory (`.claude/commands`) when applicable. */
+    readonly legacyMdDir?: string;
+}
+/** Options for one discovery pass. */
+export interface CcDiscoveryOptions {
+    /** Harness home which owns the managed and user skill roots. */
+    readonly dshHome: string;
+    /** Optional explicit managed policy root, scanned first when set. */
+    readonly managedDir?: string | undefined;
+    /** Workspace used to locate project `.claude/skills`. */
+    readonly projectCwd?: string | undefined;
+    /** Additional skill roots appended after the defaults. */
+    readonly additionalDirs: readonly string[];
+}
+/**
+ * Compute the ordered discovery roots for a workspace. Scans managed, project,
+ * user, and additional roots; the list is already in precedence order so a
+ * first-wins realpath dedup below is deterministic.
+ * @param options - discovery inputs (home, managed dir, cwd, additional dirs).
+ * @returns the ordered roots to scan.
+ */
+export declare function discoverCcRoots(options: CcDiscoveryOptions): Promise<readonly CcRoot[]>;
+/**
+ * Discover every Claude Code skill file for a workspace, deduplicated by the
+ * resolved real path so symlinked or overlapping roots yield each file once.
+ * @param options - discovery inputs.
+ * @returns the deduplicated skill files in precedence order.
+ */
+export declare function discoverCcSkills(options: CcDiscoveryOptions): Promise<readonly CcSkillFile[]>;
+/** Resolve the project root (nearest ancestor containing `.git`) for a cwd. */
+export declare function findProjectRoot(cwd: string): Promise<string>;
+//# sourceMappingURL=discovery.d.ts.map

package/lib/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAA;AAEzE,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;AAE9C,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC7B;AAED,iEAAiE;AACjE,MAAM,WAAW,MAAM;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,qEAAqE;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAQD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAoB7F;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAUnG;AA8DD,+EAA+E;AAC/E,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQlE"}

package/lib/discovery.js

@@ -0,0 +1,165 @@
+/**
+ * Claude Code skill discovery: root ordering, directory walking, and realpath
+ * deduplication.
+ *
+ * This module finds `<name>/SKILL.md` skills across managed, project, user, and
+ * additional roots in that priority order, plus legacy `.claude/commands/*.md`
+ * files marked as deprecated sources. Discovery reads only frontmatter so the
+ * catalog stays cheap; bodies load on `get()`.
+ *
+ * @module
+ */
+import { access, readdir, realpath, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+const MANAGED_RANK = 100;
+const PROJECT_RANK = 200;
+const USER_RANK = 300;
+const ADDITIONAL_RANK = 400;
+const LEGACY_COMMANDS = 'commands';
+/**
+ * Compute the ordered discovery roots for a workspace. Scans managed, project,
+ * user, and additional roots; the list is already in precedence order so a
+ * first-wins realpath dedup below is deterministic.
+ * @param options - discovery inputs (home, managed dir, cwd, additional dirs).
+ * @returns the ordered roots to scan.
+ */
+export async function discoverCcRoots(options) {
+    const roots = [];
+    if (options.managedDir !== undefined) {
+        roots.push({ path: resolve(options.managedDir), source: 'managed', rank: MANAGED_RANK });
+    }
+    if (options.projectCwd !== undefined) {
+        const projectRoot = await findProjectRoot(resolve(options.projectCwd));
+        const skillsDir = join(projectRoot, '.claude', 'skills');
+        roots.push({
+            path: skillsDir,
+            source: 'project',
+            rank: PROJECT_RANK,
+            legacyMdDir: join(projectRoot, '.claude', LEGACY_COMMANDS),
+        });
+    }
+    roots.push({ path: join(resolve(options.dshHome), 'skills'), source: 'user', rank: USER_RANK });
+    for (const dir of options.additionalDirs) {
+        roots.push({ path: resolve(dir), source: 'additional', rank: ADDITIONAL_RANK });
+    }
+    return roots;
+}
+/**
+ * Discover every Claude Code skill file for a workspace, deduplicated by the
+ * resolved real path so symlinked or overlapping roots yield each file once.
+ * @param options - discovery inputs.
+ * @returns the deduplicated skill files in precedence order.
+ */
+export async function discoverCcSkills(options) {
+    const roots = await discoverCcRoots(options);
+    const files = [];
+    for (const root of roots) {
+        files.push(...await scanDirectoryRoot(root));
+        if (root.legacyMdDir !== undefined) {
+            files.push(...await scanLegacyDirectory(root.legacyMdDir, root));
+        }
+    }
+    return deduplicateByRealpath(files);
+}
+async function scanDirectoryRoot(root) {
+    let entries;
+    try {
+        entries = await readdir(root.path, { withFileTypes: true, encoding: 'utf8' });
+    }
+    catch {
+        // Absent or unreadable roots are valid empty state for discovery.
+        return [];
+    }
+    const found = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        const dirPath = join(root.path, entry.name);
+        const skillPath = join(dirPath, 'SKILL.md');
+        if (!await isReadableFile(skillPath))
+            continue;
+        found.push({
+            name: entry.name,
+            path: skillPath,
+            directory: dirPath,
+            source: root.source,
+            rank: root.rank,
+            deprecated: false,
+        });
+    }
+    return found;
+}
+async function scanLegacyDirectory(dir, root) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true, encoding: 'utf8' });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries) {
+        if (!entry.isFile() && !entry.isSymbolicLink())
+            continue;
+        if (!entry.name.endsWith('.md'))
+            continue;
+        const filePath = join(dir, entry.name);
+        const name = entry.name.replace(/\.md$/, '');
+        found.push({
+            name,
+            path: filePath,
+            directory: dir,
+            source: root.source,
+            rank: root.rank,
+            deprecated: true,
+        });
+    }
+    return found;
+}
+async function isReadableFile(path) {
+    try {
+        const info = await stat(path);
+        return info.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the project root (nearest ancestor containing `.git`) for a cwd. */
+export async function findProjectRoot(cwd) {
+    let current = cwd;
+    while (true) {
+        if (await pathExists(join(current, '.git')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return cwd;
+        current = parent;
+    }
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function deduplicateByRealpath(files) {
+    const seen = new Set();
+    const result = [];
+    for (const file of files) {
+        const identity = await realpath(file.path).catch(() => null);
+        if (identity === null) {
+            result.push(file);
+            continue;
+        }
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        result.push(file);
+    }
+    return result;
+}
+//# sourceMappingURL=discovery.js.map

package/lib/discovery.js.map

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

package/lib/frontmatter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Claude Code skill frontmatter parsing.
+ *
+ * This module owns the full Claude Code `SKILL.md` frontmatter spec: it reads
+ * every known field, tolerates unknown fields, and throws for known fields with
+ * invalid values. Parsing keeps frontmatter independent of body loading so
+ * discovery can estimate tokens and build summaries without reading the body.
+ *
+ * @module
+ */
+/** Parsed named arguments from the `arguments` field. */
+export type ParsedCcArguments = readonly string[];
+/** A complete parse of Claude Code skill frontmatter into harness-facing fields. */
+export interface ParsedCcFrontmatter {
+    /** Kebab-case skill name from `name`; validated by the provider against the registry grammar. */
+    readonly name: string | undefined;
+    /** Routing description from `description`. */
+    readonly description: string;
+    /** Optional routing guidance from `when_to_use`. */
+    readonly whenToUse: string | undefined;
+    /** Allowed tool allow-list from `allowed-tools`, as parsed names. */
+    readonly allowedTools: readonly string[];
+    /** Optional argument usage hint from `argument-hint`. */
+    readonly argumentHint: string | undefined;
+    /** Named argument placeholders from `arguments`. */
+    readonly arguments: ParsedCcArguments;
+    /** Optional semantic version from `version`. */
+    readonly version: string | undefined;
+    /** Resolved model from `model`; `inherit` yields undefined. */
+    readonly model: string | undefined;
+    /** Whether a human may invoke the skill from `user-invocable`. */
+    readonly userInvocable: boolean;
+    /** Whether the model catalog hides the skill from `disable-model-invocation`. */
+    readonly disableModelInvocation: boolean;
+    /** `context: fork` selects subagent execution; otherwise inline. */
+    readonly executionContext: 'fork' | undefined;
+    /** Optional target agent persona from `agent`. */
+    readonly agent: string | undefined;
+    /** Optional effort level from `effort`. */
+    readonly effort: string | undefined;
+    /** Inline-shell toggle from `shell` (false disables `` !`...` `` execution). */
+    readonly shell: boolean | undefined;
+    /** Raw validated hooks object from `hooks`, preserved verbatim. */
+    readonly hooks: unknown;
+    /** Gitignore-style activation paths from `paths`, or undefined when match-all. */
+    readonly paths: readonly string[] | undefined;
+    /** Any unrecognized keys, preserved for downstream tolerant consumers. */
+    readonly unknown: Readonly<Record<string, unknown>>;
+}
+/** A split frontmatter document: parsed data plus the Markdown body. */
+export interface CcFrontmatterDocument {
+    /** Parsed frontmatter values, pre-validation. */
+    readonly data: Record<string, unknown>;
+    /** Markdown body after the closing `---`. */
+    readonly body: string;
+}
+/**
+ * Parse the complete Claude Code frontmatter from a raw `SKILL.md` document.
+ * Unknown keys are preserved in `unknown`; a known key with an invalid value
+ * throws so a malformed skill fails loudly instead of silently mis-activating.
+ * @param raw - the full `SKILL.md` text.
+ * @returns the parsed fields, or `undefined` when the document has no frontmatter.
+ */
+export declare function parseCcFrontmatter(raw: string): ParsedCcFrontmatter | undefined;
+/**
+ * Split a raw `SKILL.md` into its frontmatter YAML payload and Markdown body.
+ * Returns `undefined` when the document does not begin with a `---` fence.
+ * @param raw - the full `SKILL.md` text.
+ * @returns the parsed YAML object and trailing body, or `undefined`.
+ */
+export declare function parseCcFrontmatterDocument(raw: string): CcFrontmatterDocument | undefined;
+//# sourceMappingURL=frontmatter.d.ts.map

package/lib/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,yDAAyD;AACzD,MAAM,MAAM,iBAAiB,GAAG,SAAS,MAAM,EAAE,CAAA;AAEjD,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IAClC,iGAAiG;IACjG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;IACrC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAA;IACxC,oEAAoE;IACpE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAA;IACnC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IAC7C,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACpD;AAED,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAwGD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CA8B/E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAezF"}