@dsh-cc/skill-loader 0.5.0

package/lib/frontmatter.js

@@ -0,0 +1,200 @@
+/**
+ * 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
+ */
+import { parse as parseYaml } from 'yaml';
+const TRUE_FORMS = /^(?:true|yes|on|1)$/i;
+const FALSE_FORMS = /^(?:false|no|off|0)$/i;
+function booleanValue(key, value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value !== 'string') {
+        throw new TypeError(`frontmatter field "${key}" must be a boolean`);
+    }
+    if (TRUE_FORMS.test(value))
+        return true;
+    if (FALSE_FORMS.test(value))
+        return false;
+    throw new TypeError(`frontmatter field "${key}" must be a boolean`);
+}
+function stringValue(key, value) {
+    if (typeof value !== 'string') {
+        throw new TypeError(`frontmatter field "${key}" must be a string`);
+    }
+    return value;
+}
+function optionalString(key, value) {
+    if (value === undefined)
+        return undefined;
+    return stringValue(key, value);
+}
+function stringList(key, value) {
+    const names = stringValue(key, value).split(',').map(item => item.trim());
+    return names.filter((item, index) => item.length > 0 && names.indexOf(item) === index);
+}
+function parseNamedArguments(value) {
+    if (value === undefined)
+        return [];
+    const raw = Array.isArray(value) ? value : typeof value === 'string' ? value.split(/\s+/) : null;
+    if (raw === null) {
+        throw new TypeError('frontmatter field "arguments" must be a string or array of strings');
+    }
+    return raw
+        .filter((item) => typeof item === 'string')
+        .map(item => item.trim())
+        .filter(item => item.length > 0 && !/^\d+$/.test(item));
+}
+function optionalModel(value) {
+    if (value === undefined)
+        return undefined;
+    const model = stringValue('model', value);
+    return model === 'inherit' ? undefined : model;
+}
+function optionalEffort(value) {
+    if (value === undefined)
+        return undefined;
+    const effort = stringValue('effort', value);
+    const KNOWN = ['low', 'medium', 'high', 'ultrahigh'];
+    if (KNOWN.some(level => level === effort))
+        return effort;
+    if (/^\d+$/.test(effort))
+        return effort;
+    throw new TypeError('frontmatter field "effort" must be a known level or an integer');
+}
+function optionalShell(value) {
+    if (value === undefined)
+        return undefined;
+    return booleanValue('shell', value);
+}
+function parseContext(value) {
+    if (value === undefined)
+        return undefined;
+    const context = stringValue('context', value);
+    if (context === 'fork')
+        return 'fork';
+    throw new TypeError('frontmatter field "context" only supports "fork"');
+}
+function optionalPaths(value) {
+    if (value === undefined)
+        return undefined;
+    const raw = Array.isArray(value) ? value : [value];
+    const patterns = raw
+        .filter((item) => typeof item === 'string')
+        // `ignore` treats "path" as matching both the path and everything inside it,
+        // so a trailing `/**` is redundant and collapses to that directory.
+        .map(pattern => (pattern.endsWith('/**') ? pattern.slice(0, -3) : pattern))
+        .map(String)
+        .filter(pattern => pattern.length > 0);
+    if (patterns.length === 0 || patterns.every(pattern => pattern === '**'))
+        return undefined;
+    return [...new Set(patterns)];
+}
+const KNOWN_KEYS = new Set([
+    'name',
+    'description',
+    'when_to_use',
+    'allowed-tools',
+    'argument-hint',
+    'arguments',
+    'version',
+    'model',
+    'user-invocable',
+    'disable-model-invocation',
+    'context',
+    'agent',
+    'effort',
+    'shell',
+    'hooks',
+    'paths',
+]);
+/**
+ * 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 function parseCcFrontmatter(raw) {
+    const document = parseCcFrontmatterDocument(raw);
+    if (document === undefined)
+        return undefined;
+    const { data } = document;
+    const unknown = {};
+    for (const key of Object.keys(data)) {
+        if (!KNOWN_KEYS.has(key))
+            unknown[key] = data[key];
+    }
+    const fields = {
+        name: optionalString('name', data.name),
+        description: stringValue('description', data.description),
+        whenToUse: optionalString('when_to_use', data.when_to_use),
+        allowedTools: stringList('allowed-tools', data['allowed-tools'] ?? ''),
+        argumentHint: optionalString('argument-hint', data['argument-hint']),
+        arguments: parseNamedArguments(data.arguments),
+        version: optionalString('version', data.version),
+        model: optionalModel(data.model),
+        userInvocable: data['user-invocable'] === undefined ? true : booleanValue('user-invocable', data['user-invocable']),
+        disableModelInvocation: data['disable-model-invocation'] === undefined
+            ? false
+            : booleanValue('disable-model-invocation', data['disable-model-invocation']),
+        executionContext: parseContext(data.context),
+        agent: optionalString('agent', data.agent),
+        effort: optionalEffort(data.effort),
+        shell: optionalShell(data.shell),
+        hooks: data.hooks,
+        paths: optionalPaths(data.paths),
+        unknown,
+    };
+    return fields;
+}
+/**
+ * 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 function parseCcFrontmatterDocument(raw) {
+    const firstLineEnd = raw.indexOf('\n');
+    if (firstLineEnd < 0)
+        return undefined;
+    const firstLine = raw.slice(0, firstLineEnd).replace(/\r$/, '');
+    if (firstLine !== '---')
+        return undefined;
+    const start = firstLineEnd + 1;
+    const closingStart = findClosingFence(raw, start);
+    if (closingStart === undefined)
+        return undefined;
+    const yaml = raw.slice(start, closingStart);
+    const parsed = parseYaml(yaml);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return undefined;
+    return {
+        data: parsed,
+        body: raw.slice(closingFenceBodyStart(raw, closingStart)).replace(/^[ \t]*\r?\n/, '').replace(/\r\n$/, '\n'),
+    };
+}
+function findClosingFence(raw, start) {
+    let lineStart = start;
+    while (lineStart <= raw.length) {
+        const nextNewline = raw.indexOf('\n', lineStart);
+        const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
+        const line = raw.slice(lineStart, lineEnd).replace(/\r$/, '');
+        if (line === '---')
+            return lineStart;
+        if (nextNewline < 0)
+            return undefined;
+        lineStart = nextNewline + 1;
+    }
+    return undefined;
+}
+function closingFenceBodyStart(raw, closingStart) {
+    const nextNewline = raw.indexOf('\n', closingStart);
+    return nextNewline < 0 ? raw.length : nextNewline + 1;
+}
+//# sourceMappingURL=frontmatter.js.map

package/lib/frontmatter.js.map

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

package/lib/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Claude Code skill-format compatible provider for the `ctx.skills` registry.
+ *
+ * This package discovers `SKILL.md` skills in Claude Code's directory layout
+ * (managed, project, user, and additional roots), parses the full Claude Code
+ * frontmatter spec, serves a portable subset of Claude Code's bundled skills,
+ * and hands everything to `@deepseek-ai/dsh-skill`. It is a compatibility
+ * provider: the harness can consume skills written for Claude Code without
+ * copying the runtime that executes them.
+ *
+ * @module @dsh-cc/skill-loader
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type Schema from '@deepseek-ai/schemastery';
+import { type SkillCandidate, type SkillDefinition, type SkillInvocationPolicy, type SkillLookupOptions, type SkillProvider, type SkillProviderControl } from '@deepseek-ai/dsh-skill';
+import { type ParsedCcFrontmatter } from './frontmatter.ts';
+import type { CcInvocationPolicy } from './types.ts';
+export type { CcSkillMetadata, CcInvocationPolicy } from './types.ts';
+export { parseCcFrontmatter, parseCcFrontmatterDocument, type ParsedCcFrontmatter } from './frontmatter.ts';
+export { estimateFrontmatterTokens, renderSkillBody, substituteArguments, extractInlineShell } from './render.ts';
+export { ccRestriction, ccPathMatcher, registerPathActivator } from './translate.ts';
+export { discoverCcRoots, discoverCcSkills, type CcSkillFile, type CcRoot, type CcSkillSource } from './discovery.ts';
+export { discoverBundledSkills, type BundledSkillFile } from './bundled/index.ts';
+export declare const name = "skill-claude-code";
+export declare const inject: string[];
+/**
+ * Claude Code skill provider configuration.
+ */
+export interface Config {
+    /** Unique provider name. Defaults to `claude-code`. */
+    providerName?: string;
+    /** Harness home that owns the user skill root. */
+    dshHome?: string;
+    /** Optional managed policy skill root, scanned before all defaults. */
+    managedDir?: string;
+    /** Additional skill roots appended after project and user roots. */
+    additionalDirs?: string[];
+}
+export declare const Config: Schema<Config>;
+/**
+ * Register the Claude Code skill provider on `ctx.skills`.
+ * @param ctx - active context carrying the skill registry.
+ * @param config - provider configuration.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+/** Provider that maps Claude Code skill directories into `ctx.skills`. */
+export declare class ClaudeCodeSkillProvider implements SkillProvider {
+    private readonly ctx;
+    readonly name: string;
+    private readonly dshHome;
+    private readonly managedDir;
+    private readonly additionalDirs;
+    private readonly control;
+    /** Installed bundled skills for `source: 'bundled'`, parsed once. */
+    private readonly bundled;
+    /**
+     * Conditional (paths-gated) skills discovered so far, keyed by project root
+     * then skill name -> project-relative path matcher.
+     */
+    private readonly conditional;
+    /** Set of skill names already activated per project root (idempotence guard). */
+    private readonly activated;
+    private disposeFsObserver;
+    constructor(ctx: Context, control: SkillProviderControl, config?: Config);
+    /**
+     * Discover Claude Code skills for a cwd-sensitive workspace plus the bundled
+     * subset. Paths-gated skills are excluded until their paths are touched.
+     * @param options - lookup options; `cwd` selects the project root to scan.
+     * @returns provider candidates, one per discovered `SKILL.md`.
+     */
+    list(options: SkillLookupOptions): Promise<SkillCandidate[]>;
+    /**
+     * Load a complete Claude Code skill body from a candidate's file.
+     * @param candidate - the winning candidate returned by this provider.
+     * @returns the full skill definition, or `undefined` if the file disappeared.
+     */
+    get(candidate: SkillCandidate, _options: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+    private parseFile;
+    private toCandidate;
+    private toBundledCandidate;
+    private toDefinition;
+    private toBundledDefinition;
+    private toMetadata;
+    private sourceOf;
+    private rememberConditional;
+    private isActivated;
+    private activate;
+    /**
+     * Register the `fs/observed` listener that activates path-conditional skills
+     * when a Read/Write/Edit tool touches a matching project-relative path. On a
+     * first activation it invalidates the registry so consumers refetch the (now
+     * larger) catalog. This mirrors the `registerPathActivator` contract, but the
+     * projects/skills are discovered dynamically per cwd, so the provider owns the
+     * listener over its live conditional catalog.
+     */
+    private wireConditionalActivation;
+}
+/** Resolve the registry invocation policy from Claude Code bool frontmatter. */
+export declare function ccInvocation(parsed: Pick<ParsedCcFrontmatter, 'userInvocable' | 'disableModelInvocation'>): CcInvocationPolicy & SkillInvocationPolicy;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

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

package/lib/index.js

@@ -0,0 +1,343 @@
+/**
+ * Claude Code skill-format compatible provider for the `ctx.skills` registry.
+ *
+ * This package discovers `SKILL.md` skills in Claude Code's directory layout
+ * (managed, project, user, and additional roots), parses the full Claude Code
+ * frontmatter spec, serves a portable subset of Claude Code's bundled skills,
+ * and hands everything to `@deepseek-ai/dsh-skill`. It is a compatibility
+ * provider: the harness can consume skills written for Claude Code without
+ * copying the runtime that executes them.
+ *
+ * @module @dsh-cc/skill-loader
+ */
+import { readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { BUNDLED_SKILL_RANK, isSkillName, } from '@deepseek-ai/dsh-skill';
+import { discoverBundledSkills } from "./bundled/index.js";
+import { discoverCcSkills, findProjectRoot } from "./discovery.js";
+import { parseCcFrontmatter, parseCcFrontmatterDocument, } from "./frontmatter.js";
+import { ccPathMatcher } from "./translate.js";
+export { parseCcFrontmatter, parseCcFrontmatterDocument } from "./frontmatter.js";
+export { estimateFrontmatterTokens, renderSkillBody, substituteArguments, extractInlineShell } from "./render.js";
+export { ccRestriction, ccPathMatcher, registerPathActivator } from "./translate.js";
+export { discoverCcRoots, discoverCcSkills } from "./discovery.js";
+export { discoverBundledSkills } from "./bundled/index.js";
+export const name = 'skill-claude-code';
+export const inject = ['skills'];
+const DEFAULT_PROVIDER_NAME = 'claude-code';
+const MANAGED_SOURCE = 'managed';
+const PROJECT_SOURCE = 'project-dsh';
+const USER_SOURCE = 'user-dsh';
+const ADDITIONAL_SOURCE = 'custom';
+/** Mutating first-party fs tools that trigger conditional activation. */
+const TOUCH_TOOLS = new Set(['read', 'write', 'edit']);
+export const Config = z.object({
+    providerName: z.string().min(1).default(DEFAULT_PROVIDER_NAME),
+    dshHome: z.string(),
+    managedDir: z.string(),
+    additionalDirs: z.array(z.string()).default([]),
+});
+/**
+ * Register the Claude Code skill provider on `ctx.skills`.
+ * @param ctx - active context carrying the skill registry.
+ * @param config - provider configuration.
+ */
+export function apply(ctx, config = {}) {
+    ctx.skills.registerProvider((control) => {
+        return new ClaudeCodeSkillProvider(ctx, control, config);
+    });
+}
+/** Provider that maps Claude Code skill directories into `ctx.skills`. */
+export class ClaudeCodeSkillProvider {
+    ctx;
+    name;
+    dshHome;
+    managedDir;
+    additionalDirs;
+    control;
+    /** Installed bundled skills for `source: 'bundled'`, parsed once. */
+    bundled;
+    /**
+     * Conditional (paths-gated) skills discovered so far, keyed by project root
+     * then skill name -> project-relative path matcher.
+     */
+    conditional = new Map();
+    /** Set of skill names already activated per project root (idempotence guard). */
+    activated = new Map();
+    disposeFsObserver;
+    constructor(ctx, control, config = {}) {
+        this.ctx = ctx;
+        this.name = config.providerName ?? DEFAULT_PROVIDER_NAME;
+        this.dshHome = resolveDshHome(config.dshHome);
+        this.managedDir = config.managedDir === undefined ? undefined : resolve(config.managedDir);
+        this.additionalDirs = (config.additionalDirs ?? []).map(dir => resolve(dir));
+        this.control = control;
+        this.bundled = discoverBundledSkills();
+        this.wireConditionalActivation();
+        control.signal.addEventListener('abort', () => this.disposeFsObserver?.(), { once: true });
+    }
+    /**
+     * Discover Claude Code skills for a cwd-sensitive workspace plus the bundled
+     * subset. Paths-gated skills are excluded until their paths are touched.
+     * @param options - lookup options; `cwd` selects the project root to scan.
+     * @returns provider candidates, one per discovered `SKILL.md`.
+     */
+    async list(options) {
+        const files = await discoverCcSkills({
+            dshHome: this.dshHome,
+            managedDir: this.managedDir,
+            projectCwd: options.cwd,
+            additionalDirs: this.additionalDirs,
+        });
+        const root = options.cwd === undefined ? undefined : await findProjectRoot(resolve(options.cwd));
+        const candidates = [];
+        for (const file of files) {
+            const parsed = await this.parseFile(file);
+            if (parsed === undefined)
+                continue;
+            if (parsed.paths !== undefined) {
+                // Conditional skill: gate on project-relative path activation.
+                if (root === undefined)
+                    continue;
+                this.rememberConditional(root, parsed);
+                if (!this.isActivated(root, parsed.name))
+                    continue;
+            }
+            candidates.push(this.toCandidate(file, parsed));
+        }
+        for (const bundled of this.bundled) {
+            // Bundled skills are never paths-gated; defend anyway.
+            if (bundled.parsed.paths !== undefined)
+                continue;
+            candidates.push(this.toBundledCandidate(bundled));
+        }
+        return candidates;
+    }
+    /**
+     * Load a complete Claude Code skill body from a candidate's file.
+     * @param candidate - the winning candidate returned by this provider.
+     * @returns the full skill definition, or `undefined` if the file disappeared.
+     */
+    async get(candidate, _options) {
+        if (isBundledLocator(candidate.locator)) {
+            return this.toBundledDefinition(candidate.locator);
+        }
+        const file = candidate.locator;
+        const loaded = await loadCcSkillFile(file.path);
+        if (loaded === undefined)
+            return undefined;
+        const parsed = loaded.parsed;
+        if (!validCcName(parsed))
+            return undefined;
+        return this.toDefinition(candidate, file, parsed, loaded.body);
+    }
+    async parseFile(file) {
+        const loaded = await loadCcSkillFile(file.path);
+        if (loaded === undefined)
+            return undefined;
+        const parsed = loaded.parsed;
+        if (!validCcName(parsed)) {
+            this.ctx.logger.warn(`Claude Code skill ${file.path} ignored: invalid or missing name`);
+            return undefined;
+        }
+        return parsed;
+    }
+    toCandidate(file, parsed) {
+        const source = this.sourceOf(file.source);
+        const metadata = metadataRecord(this.toMetadata(file, parsed));
+        return {
+            name: parsed.name,
+            description: parsed.description,
+            ...parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {},
+            invocation: ccInvocation(parsed),
+            source,
+            provider: this.name,
+            rank: file.rank,
+            locator: file,
+            resourceBase: { kind: 'directory', path: file.directory },
+            path: file.path,
+            metadata,
+        };
+    }
+    toBundledCandidate(file) {
+        const parsed = file.parsed;
+        const metadata = metadataRecord(this.toMetadata(file, parsed));
+        return {
+            name: parsed.name,
+            description: parsed.description,
+            ...parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {},
+            invocation: ccInvocation(parsed),
+            source: 'bundled',
+            provider: this.name,
+            rank: BUNDLED_SKILL_RANK,
+            locator: file,
+            resourceBase: { kind: 'directory', path: file.directory },
+            metadata,
+        };
+    }
+    toDefinition(candidate, file, parsed, body) {
+        return {
+            name: parsed.name,
+            description: parsed.description,
+            ...parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {},
+            invocation: ccInvocation(parsed),
+            source: candidate.source,
+            provider: this.name,
+            resourceBase: { kind: 'directory', path: file.directory },
+            path: file.path,
+            metadata: metadataRecord(this.toMetadata(file, parsed)),
+            content: body,
+        };
+    }
+    toBundledDefinition(file) {
+        return {
+            name: file.parsed.name,
+            description: file.parsed.description,
+            ...file.parsed.whenToUse !== undefined ? { whenToUse: file.parsed.whenToUse } : {},
+            invocation: ccInvocation(file.parsed),
+            source: 'bundled',
+            provider: this.name,
+            resourceBase: { kind: 'directory', path: file.directory },
+            path: file.path,
+            metadata: metadataRecord(this.toMetadata(file, file.parsed)),
+            content: file.body,
+        };
+    }
+    toMetadata(file, parsed) {
+        return {
+            allowedTools: parsed.allowedTools,
+            arguments: parsed.arguments,
+            deprecated: 'deprecated' in file ? file.deprecated : false,
+            source: 'source' in file ? file.source : 'bundled',
+            unknown: parsed.unknown,
+            ...parsed.argumentHint !== undefined ? { argumentHint: parsed.argumentHint } : {},
+            ...parsed.version !== undefined ? { version: parsed.version } : {},
+            ...parsed.model !== undefined ? { model: parsed.model } : {},
+            ...parsed.executionContext !== undefined ? { executionContext: parsed.executionContext } : {},
+            ...parsed.agent !== undefined ? { agent: parsed.agent } : {},
+            ...parsed.effort !== undefined ? { effort: parsed.effort } : {},
+            ...parsed.shell !== undefined ? { shell: parsed.shell } : {},
+            ...parsed.hooks !== undefined ? { hooks: parsed.hooks } : {},
+            ...parsed.paths !== undefined ? { paths: parsed.paths } : {},
+        };
+    }
+    sourceOf(source) {
+        switch (source) {
+            case 'managed':
+                return MANAGED_SOURCE;
+            case 'user':
+                return USER_SOURCE;
+            case 'project':
+                return PROJECT_SOURCE;
+            case 'additional':
+                return ADDITIONAL_SOURCE;
+        }
+    }
+    rememberConditional(root, parsed) {
+        if (parsed.paths === undefined || parsed.name === undefined)
+            return;
+        const normalizedRoot = normalizeRoot(root);
+        let skills = this.conditional.get(normalizedRoot);
+        if (skills === undefined) {
+            skills = new Map();
+            this.conditional.set(normalizedRoot, skills);
+        }
+        if (!skills.has(parsed.name))
+            skills.set(parsed.name, ccPathMatcher(parsed.paths));
+    }
+    isActivated(root, name) {
+        return this.activated.get(normalizeRoot(root))?.has(name) ?? false;
+    }
+    activate(root, name) {
+        let set = this.activated.get(normalizeRoot(root));
+        if (set === undefined) {
+            set = new Set();
+            this.activated.set(normalizeRoot(root), set);
+        }
+        if (set.has(name))
+            return false; // idempotent: already active
+        set.add(name);
+        return true;
+    }
+    /**
+     * Register the `fs/observed` listener that activates path-conditional skills
+     * when a Read/Write/Edit tool touches a matching project-relative path. On a
+     * first activation it invalidates the registry so consumers refetch the (now
+     * larger) catalog. This mirrors the `registerPathActivator` contract, but the
+     * projects/skills are discovered dynamically per cwd, so the provider owns the
+     * listener over its live conditional catalog.
+     */
+    wireConditionalActivation() {
+        const dispose = this.ctx.on('fs/observed', (target, _observation, actor) => {
+            if (!touchActor(actor))
+                return;
+            const path = target.displayPath.replaceAll('\\', '/');
+            for (const [root, skills] of this.conditional) {
+                if (!inProject(path, root))
+                    continue;
+                const rel = relative(root, target.displayPath).replaceAll('\\', '/');
+                for (const [name, matcher] of skills) {
+                    if (this.isActivated(root, name))
+                        continue;
+                    if (!matcher(rel))
+                        continue;
+                    if (this.activate(root, name))
+                        this.control.invalidate();
+                }
+            }
+        });
+        this.disposeFsObserver = dispose;
+    }
+}
+/** Whether `path` is under `root` (identity or root/...), both forward-slash normalized. */
+function inProject(path, root) {
+    return path === root || path.startsWith(`${root}/`);
+}
+function normalizeRoot(root) {
+    return root.replaceAll('\\', '/').replace(/\/+$/, '');
+}
+function touchActor(actor) {
+    if (actor === undefined || !('name' in actor))
+        return false;
+    const value = actor.name;
+    return typeof value === 'string' && TOUCH_TOOLS.has(value);
+}
+function isBundledLocator(locator) {
+    if (typeof locator !== 'object' || locator === null || Array.isArray(locator))
+        return false;
+    return locator.kind === 'bundled';
+}
+/** Resolve the registry invocation policy from Claude Code bool frontmatter. */
+export function ccInvocation(parsed) {
+    return {
+        modelInvocable: !parsed.disableModelInvocation,
+        userInvocable: parsed.userInvocable,
+    };
+}
+/** Whether a parsed skill carries a valid registry name. */
+function validCcName(parsed) {
+    return parsed.name !== undefined && isSkillName(parsed.name);
+}
+/** Widen a typed CC metadata object to the registry's string-keyed metadata map. */
+function metadataRecord(metadata) {
+    return metadata;
+}
+async function loadCcSkillFile(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const document = parseCcFrontmatterDocument(raw);
+    if (document === undefined)
+        return undefined;
+    const parsed = parseCcFrontmatter(raw);
+    if (parsed === undefined)
+        return undefined;
+    return { parsed, body: document.body };
+}
+//# sourceMappingURL=index.js.map