comisai 1.0.37 → 1.0.40

package/node_modules/@comis/skills/dist/skills/registry/skill-registry/skill-registry-cache.js

@@ -0,0 +1,391 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Skill registry factory + closure-state.
+ *
+ * Owns:
+ *   - createSkillRegistry factory body
+ *   - Closure state: metadataMap, promptCache, cachedSnapshot, snapshotVersion
+ *   - Closure helpers: checkRuntimeEligibility, doInit
+ *   - Methods returned in the factory's object literal: init, getPromptSkill*,
+ *     getUserInvocableSkillNames, getRelevantPromptSkills, getMetadataCount,
+ *     getSnapshot, getSnapshotVersion, startWatching, getEligibleSkillNames,
+ *     getPromptSkillCapabilities, initFromSdkSkills
+ *
+ * The level-2 loader (loadPromptSkillImpl) is delegated to
+ * skill-registry-discovery.ts to keep this file under the per-leaf 500-line
+ * cap.
+ *
+ * @module
+ */
+import * as fs from "node:fs";
+import { systemNowMs } from "@comis/core";
+import { parseComisCapabilityDefensively } from "../../manifest/capability-parser.js";
+import { parseFrontmatter } from "../../manifest/parser.js";
+import { formatAvailableSkillsXml, } from "../../prompt/processor.js";
+import { discoverSkills } from "../discovery.js";
+import { evaluateSkillEligibility, } from "../eligibility.js";
+import { createSkillWatcher, } from "../skill-watcher.js";
+import { isSkillEligible, loadPromptSkillImpl, scoreRelevance, tokenize, } from "./skill-registry-discovery.js";
+/**
+ * Create a skill registry with progressive disclosure.
+ *
+ * @param config - Skills configuration (discovery paths)
+ * @param eventBus - Typed event bus for audit events
+ * @param auditContext - Identity context for audit trail
+ * @returns SkillRegistry instance
+ */
+export function createSkillRegistry(config, eventBus, auditContext, logger, eligibilityContext) {
+    // Level 1: metadata storage
+    const metadataMap = new Map();
+    // Prompt skill cache (no AST/sandbox)
+    const promptCache = new Map();
+    // Snapshot cache: lazily built on first getSnapshot() call, invalidated on init()/reload()
+    let cachedSnapshot = null;
+    let snapshotVersion = 0;
+    /** Check runtime eligibility if context is available and enabled. Returns false if skill should be excluded. */
+    function checkRuntimeEligibility(metadata) {
+        if (!eligibilityContext)
+            return true;
+        const runtimeEnabled = config.runtimeEligibility?.enabled ?? true;
+        if (!runtimeEnabled)
+            return true;
+        const result = evaluateSkillEligibility(metadata, eligibilityContext);
+        if (!result.eligible) {
+            logger?.debug({ skillName: metadata.name, reason: result.reason }, "Skill excluded by runtime eligibility");
+            return false;
+        }
+        return true;
+    }
+    /** Init implementation extracted for reuse by startWatching onReload callback. */
+    function doInit() {
+        const prevMetadataCount = metadataMap.size;
+        const prevCacheCount = promptCache.size;
+        metadataMap.clear();
+        promptCache.clear();
+        logger?.debug({ clearedMetadata: prevMetadataCount, clearedPromptCache: prevCacheCount }, "Registry caches cleared");
+        const { skills: discovered, diagnostics } = discoverSkills(config.discoveryPaths, logger);
+        for (const skill of discovered) {
+            metadataMap.set(skill.name, skill);
+        }
+        logger?.info({ skillCount: discovered.length }, "Skills discovered");
+        for (const diag of diagnostics) {
+            if (diag.type === "collision") {
+                logger?.warn({ collision: { winnerPath: diag.collision?.winnerPath, loserPath: diag.collision?.loserPath }, hint: "Remove duplicate skill definitions or rename to avoid collision", errorKind: "config" }, "Skill name collision");
+            }
+            else if (diag.type === "warning") {
+                logger?.warn({ skillPath: diag.path, hint: "Check skill file format and manifest structure", errorKind: "validation" }, diag.message);
+            }
+        }
+        // Pre-populate binary cache at init time (computed once, reused across requests)
+        if (eligibilityContext) {
+            const allBins = new Set();
+            for (const skill of discovered) {
+                if (skill.requires?.bins) {
+                    for (const bin of skill.requires.bins)
+                        allBins.add(bin);
+                }
+            }
+            if (allBins.size > 0) {
+                eligibilityContext.populateBinaryCache([...allBins]);
+                logger?.debug({ binCount: allBins.size, bins: [...allBins] }, "Binary availability cache populated");
+            }
+        }
+        cachedSnapshot = null;
+        snapshotVersion++;
+        eventBus.emit("skill:registry_reset", {
+            clearedMetadata: prevMetadataCount,
+            clearedPromptCache: prevCacheCount,
+            timestamp: systemNowMs(),
+        });
+    }
+    return {
+        init: doInit,
+        async loadPromptSkill(name) {
+            return loadPromptSkillImpl({
+                name,
+                metadataMap,
+                promptCache,
+                config,
+                eventBus,
+                auditContext,
+                logger,
+            });
+        },
+        getPromptSkillDescriptions() {
+            const descriptions = [];
+            for (const metadata of metadataMap.values()) {
+                // Eligibility filtering: allowedSkills/deniedSkills from config
+                if (!isSkillEligible(metadata.name, config.promptSkills))
+                    continue;
+                // Runtime eligibility: os, binary, env var checks
+                if (!checkRuntimeEligibility(metadata))
+                    continue;
+                descriptions.push({
+                    name: metadata.name,
+                    description: metadata.description,
+                    location: metadata.path,
+                    disableModelInvocation: metadata.disableModelInvocation || undefined,
+                    source: metadata.source,
+                });
+            }
+            return descriptions;
+        },
+        getUserInvocableSkillNames() {
+            const names = new Set();
+            for (const metadata of metadataMap.values()) {
+                if (metadata.userInvocable) {
+                    // Eligibility filtering: allowedSkills/deniedSkills from config
+                    if (!isSkillEligible(metadata.name, config.promptSkills))
+                        continue;
+                    // Runtime eligibility: os, binary, env var checks
+                    if (!checkRuntimeEligibility(metadata))
+                        continue;
+                    names.add(metadata.name);
+                }
+            }
+            return names;
+        },
+        getRelevantPromptSkills(query, maxResults) {
+            const limit = maxResults ?? config.promptSkills.maxAutoInject;
+            if (metadataMap.size === 0)
+                return [];
+            const queryTokens = new Set(tokenize(query));
+            const queryLower = query.toLowerCase();
+            const scored = [];
+            for (const skill of metadataMap.values()) {
+                // Eligibility filtering: allowedSkills/deniedSkills from config
+                if (!isSkillEligible(skill.name, config.promptSkills))
+                    continue;
+                // Runtime eligibility: os, binary, env var checks
+                if (!checkRuntimeEligibility(skill))
+                    continue;
+                let score = scoreRelevance(queryTokens, skill);
+                if (queryLower.includes(skill.name.toLowerCase()))
+                    score += 10;
+                if (score > 0)
+                    scored.push({ skill, score });
+            }
+            scored.sort((a, b) => {
+                if (b.score !== a.score)
+                    return b.score - a.score;
+                return a.skill.name.localeCompare(b.skill.name);
+            });
+            return scored.slice(0, limit).map((s) => s.skill);
+        },
+        getMetadataCount() {
+            return metadataMap.size;
+        },
+        getSnapshot() {
+            if (cachedSnapshot === null) {
+                const descriptions = this.getPromptSkillDescriptions();
+                const prompt = formatAvailableSkillsXml(descriptions);
+                cachedSnapshot = { prompt, skills: descriptions, version: snapshotVersion };
+            }
+            return cachedSnapshot;
+        },
+        getSnapshotVersion() {
+            return snapshotVersion;
+        },
+        startWatching(debounceMs) {
+            return createSkillWatcher({
+                discoveryPaths: config.discoveryPaths,
+                debounceMs,
+                onReload: () => {
+                    // Re-discovery calls init() to refresh metadata and clear caches
+                    doInit();
+                    // Emit skills:reloaded event after successful re-discovery
+                    eventBus.emit("skills:reloaded", {
+                        agentId: auditContext.agentId,
+                        skillCount: metadataMap.size,
+                        timestamp: systemNowMs(),
+                    });
+                },
+                logger,
+            });
+        },
+        getEligibleSkillNames() {
+            const names = new Set();
+            for (const metadata of metadataMap.values()) {
+                if (!isSkillEligible(metadata.name, config.promptSkills))
+                    continue;
+                if (!checkRuntimeEligibility(metadata))
+                    continue;
+                names.add(metadata.name);
+            }
+            return names;
+        },
+        getPromptSkillCapabilities(getOperatorHint) {
+            const out = [];
+            for (const metadata of metadataMap.values()) {
+                // Filter chain -- mirrors getPromptSkillDescriptions PLUS the extra
+                // disableModelInvocation filter (skills hidden from the model are
+                // not capability-index entries).
+                if (!isSkillEligible(metadata.name, config.promptSkills))
+                    continue;
+                if (!checkRuntimeEligibility(metadata))
+                    continue;
+                if (metadata.disableModelInvocation)
+                    continue;
+                // Precedence:
+                //   operator(skillKey) > operator(skillName) > comis.capability > fallback.
+                const opByKey = metadata.skillKey
+                    ? getOperatorHint(metadata.name, metadata.skillKey)
+                    : undefined;
+                const opByName = !opByKey ? getOperatorHint(metadata.name) : undefined;
+                const operatorHint = opByKey ?? opByName;
+                const comisHint = metadata.capability;
+                const cluster = operatorHint?.cluster ?? comisHint?.cluster;
+                const summary = operatorHint?.description ?? comisHint?.summary ?? metadata.description;
+                const rawReplaces = operatorHint?.replacesPackages ?? comisHint?.replacesPackages ?? [];
+                out.push(Object.freeze({
+                    name: metadata.name,
+                    skillKey: metadata.skillKey,
+                    description: metadata.description,
+                    cluster,
+                    summary,
+                    replacesPackages: Object.freeze([...rawReplaces]),
+                    source: metadata.source,
+                }));
+            }
+            return Object.freeze(out);
+        },
+        initFromSdkSkills(sdkSkills) {
+            const prevMetadataCount = metadataMap.size;
+            const prevCacheCount = promptCache.size;
+            metadataMap.clear();
+            promptCache.clear();
+            logger?.debug({ clearedMetadata: prevMetadataCount, clearedPromptCache: prevCacheCount }, "Registry caches cleared (SDK init)");
+            for (const sdkSkill of sdkSkills) {
+                // Map SDK Skill source to Comis SkillSource
+                const source = sdkSkill.source === "bundled" ? "bundled"
+                    : sdkSkill.source === "local" ? "local"
+                        : "workspace";
+                // Start with SDK-provided fields
+                let userInvocable = true;
+                let argumentHint;
+                let os;
+                let requires;
+                let skillKey;
+                let primaryEnv;
+                let commandDispatch;
+                let capability;
+                // Enrichment: read comis: namespace from skill file frontmatter
+                try {
+                    const content = fs.readFileSync(sdkSkill.filePath, "utf-8");
+                    const fmResult = parseFrontmatter(content);
+                    if (fmResult.ok) {
+                        const obj = fmResult.value.frontmatter;
+                        const ns = typeof obj["comis"] === "object" &&
+                            obj["comis"] !== null &&
+                            !Array.isArray(obj["comis"])
+                            ? obj["comis"]
+                            : undefined;
+                        // userInvocable from top-level frontmatter
+                        if (typeof obj["userInvocable"] === "boolean") {
+                            userInvocable = obj["userInvocable"];
+                        }
+                        // argumentHint from top-level frontmatter
+                        if (typeof obj["argumentHint"] === "string") {
+                            argumentHint = obj["argumentHint"];
+                        }
+                        // os -- from comis: namespace only
+                        const rawOs = ns?.["os"];
+                        if (typeof rawOs === "string") {
+                            os = [rawOs.toLowerCase()];
+                        }
+                        else if (Array.isArray(rawOs)) {
+                            os = rawOs
+                                .filter((v) => typeof v === "string")
+                                .map((v) => v.toLowerCase());
+                        }
+                        // requires -- from comis: namespace only
+                        const rawRequires = ns?.["requires"];
+                        if (rawRequires &&
+                            typeof rawRequires === "object" &&
+                            !Array.isArray(rawRequires)) {
+                            const r = rawRequires;
+                            const bins = Array.isArray(r["bins"])
+                                ? r["bins"].filter((v) => typeof v === "string")
+                                : [];
+                            const env = Array.isArray(r["env"])
+                                ? r["env"].filter((v) => typeof v === "string")
+                                : [];
+                            requires = { bins, env };
+                        }
+                        // skill-key -- from comis: namespace only
+                        const rawSkillKey = ns?.["skill-key"];
+                        if (typeof rawSkillKey === "string") {
+                            skillKey =
+                                rawSkillKey
+                                    .toLowerCase()
+                                    .replace(/\s+/g, "-")
+                                    .replace(/[^a-z0-9-]/g, "")
+                                    .replace(/^-+|-+$/g, "") || undefined;
+                        }
+                        // primary-env -- from comis: namespace only
+                        const rawPrimaryEnv = ns?.["primary-env"];
+                        if (typeof rawPrimaryEnv === "string")
+                            primaryEnv = rawPrimaryEnv;
+                        // command-dispatch -- from comis: namespace only
+                        const rawCommandDispatch = ns?.["command-dispatch"];
+                        if (typeof rawCommandDispatch === "string") {
+                            commandDispatch = rawCommandDispatch;
+                        }
+                        // Capability layer -- defensive parse. A typo or type mismatch
+                        // in the inner block returns undefined + emits a WARN; the skill
+                        // itself is NEVER hidden by malformed capability metadata.
+                        capability = parseComisCapabilityDefensively(ns?.["capability"], sdkSkill.name, logger);
+                    }
+                }
+                catch {
+                    // Non-fatal: enrichment failure means we use SDK-provided fields only
+                    logger?.debug({ skillName: sdkSkill.name, filePath: sdkSkill.filePath }, "Skill file enrichment failed (non-fatal)");
+                }
+                const metadata = {
+                    name: sdkSkill.name,
+                    description: sdkSkill.description,
+                    path: sdkSkill.baseDir,
+                    source,
+                    type: "prompt",
+                    userInvocable,
+                    disableModelInvocation: sdkSkill.disableModelInvocation,
+                    argumentHint,
+                    filePath: sdkSkill.filePath,
+                    os,
+                    requires,
+                    skillKey,
+                    primaryEnv,
+                    commandDispatch,
+                    capability,
+                };
+                // Apply eligibility filtering during population
+                if (!isSkillEligible(metadata.name, config.promptSkills))
+                    continue;
+                if (!checkRuntimeEligibility(metadata))
+                    continue;
+                metadataMap.set(metadata.name, metadata);
+            }
+            logger?.info({ sdkSkillCount: sdkSkills.length, eligibleCount: metadataMap.size }, "Registry populated from SDK skills");
+            // Pre-populate binary cache (same as doInit)
+            if (eligibilityContext) {
+                const allBins = new Set();
+                for (const skill of metadataMap.values()) {
+                    if (skill.requires?.bins) {
+                        for (const bin of skill.requires.bins)
+                            allBins.add(bin);
+                    }
+                }
+                if (allBins.size > 0) {
+                    eligibilityContext.populateBinaryCache([...allBins]);
+                }
+            }
+            cachedSnapshot = null;
+            snapshotVersion++;
+            eventBus.emit("skill:registry_reset", {
+                clearedMetadata: prevMetadataCount,
+                clearedPromptCache: prevCacheCount,
+                timestamp: systemNowMs(),
+            });
+        },
+    };
+}

package/node_modules/@comis/skills/dist/skills/registry/skill-registry/skill-registry-discovery.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Skill registry discovery + matching algorithms.
+ *
+ * Owns:
+ *   - Tokenization (tokenize)
+ *   - allowed/denied filter (isSkillEligible)
+ *   - Relevance scoring against a tokenized query (scoreRelevance)
+ *   - loadPromptSkillImpl — the file-IO + manifest + content-scan + audit
+ *     pipeline for level-2 (load) progressive disclosure
+ *
+ * These are the deterministic, reusable helpers — no closure state, all
+ * inputs are passed explicitly (cache map is mutated as the documented
+ * side effect of a successful load).
+ *
+ * @module
+ */
+import type { SkillsConfig, TypedEventBus } from "@comis/core";
+import type { Result } from "@comis/shared";
+import type { SkillMetadata } from "../discovery.js";
+import type { PromptSkillContent, SkillsLogger } from "./skill-registry-types.js";
+/** Tokenize a string into lowercase words (split on whitespace and common punctuation). */
+export declare function tokenize(text: string): string[];
+/**
+ * Check if a skill is eligible based on allowedSkills/deniedSkills config.
+ *
+ * - If allowedSkills is non-empty, skill must be in the list.
+ * - If skill is in deniedSkills, it is excluded (deny takes precedence within allowed set).
+ * - Null-safe: uses `?? []` because test/legacy configs may omit these fields.
+ */
+export declare function isSkillEligible(name: string, promptSkillsConfig: {
+    allowedSkills?: string[];
+    deniedSkills?: string[];
+}): boolean;
+/**
+ * Score a skill's metadata against a query using keyword overlap.
+ * Returns the count of overlapping tokens between query and description.
+ */
+export declare function scoreRelevance(queryTokens: Set<string>, skill: SkillMetadata): number;
+/**
+ * Level-2 (load) progressive-disclosure entry point.
+ *
+ * Reads the skill body from disk, parses frontmatter, defensively strips a
+ * malformed `comis.capability` block, validates the manifest, sanitizes the
+ * body, runs content scanning, emits audit events, and caches the resulting
+ * {@link PromptSkillContent} in `promptCache`.
+ *
+ * Side effects: on `ok()`, `promptCache.set(name, ...)` is called. On any
+ * `err()` return, the cache is NOT mutated.
+ *
+ * @returns `ok(PromptSkillContent)` on success; `err(Error)` when metadata
+ *          missing, file read fails, frontmatter invalid, body empty, manifest
+ *          validation fails, sanitization yields empty body, or content scan
+ *          flags a CRITICAL finding under `blockOnCritical`.
+ */
+export declare function loadPromptSkillImpl(params: {
+    name: string;
+    metadataMap: Map<string, SkillMetadata>;
+    promptCache: Map<string, PromptSkillContent>;
+    config: SkillsConfig;
+    eventBus: TypedEventBus;
+    auditContext: {
+        agentId: string;
+        tenantId: string;
+        userId: string;
+    };
+    logger?: SkillsLogger;
+}): Promise<Result<PromptSkillContent, Error>>;

package/node_modules/@comis/skills/dist/skills/registry/skill-registry/skill-registry-discovery.js

@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Skill registry discovery + matching algorithms.
+ *
+ * Owns:
+ *   - Tokenization (tokenize)
+ *   - allowed/denied filter (isSkillEligible)
+ *   - Relevance scoring against a tokenized query (scoreRelevance)
+ *   - loadPromptSkillImpl — the file-IO + manifest + content-scan + audit
+ *     pipeline for level-2 (load) progressive disclosure
+ *
+ * These are the deterministic, reusable helpers — no closure state, all
+ * inputs are passed explicitly (cache map is mutated as the documented
+ * side effect of a successful load).
+ *
+ * @module
+ */
+import { ok, err } from "@comis/shared";
+import * as fs from "node:fs";
+import { emitSkillAudit } from "../../audit/skill-audit.js";
+import { parseComisCapabilityDefensively } from "../../manifest/capability-parser.js";
+import { parseFrontmatter } from "../../manifest/parser.js";
+import { SkillManifestSchema } from "../../manifest/schema.js";
+import { sanitizeSkillBody } from "../../prompt/sanitizer.js";
+import { scanSkillContent } from "../../prompt/content-scanner.js";
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+/** Tokenize a string into lowercase words (split on whitespace and common punctuation). */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[\s,.;:!?()[\]{}<>/\\|@#$%^&*+=~`"'-]+/)
+        .filter((t) => t.length > 0);
+}
+/**
+ * Check if a skill is eligible based on allowedSkills/deniedSkills config.
+ *
+ * - If allowedSkills is non-empty, skill must be in the list.
+ * - If skill is in deniedSkills, it is excluded (deny takes precedence within allowed set).
+ * - Null-safe: uses `?? []` because test/legacy configs may omit these fields.
+ */
+export function isSkillEligible(name, promptSkillsConfig) {
+    const allowed = promptSkillsConfig.allowedSkills ?? [];
+    const denied = promptSkillsConfig.deniedSkills ?? [];
+    // If allowedSkills is non-empty, skill must be in the list
+    if (allowed.length > 0 && !allowed.includes(name)) {
+        return false;
+    }
+    // If skill is in deniedSkills, it's excluded
+    if (denied.includes(name)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Score a skill's metadata against a query using keyword overlap.
+ * Returns the count of overlapping tokens between query and description.
+ */
+export function scoreRelevance(queryTokens, skill) {
+    const descTokens = tokenize(skill.description);
+    let score = 0;
+    for (const token of descTokens) {
+        if (queryTokens.has(token)) {
+            score++;
+        }
+    }
+    return score;
+}
+// ---------------------------------------------------------------------------
+// Factory-body extraction: loadPromptSkillImpl
+// ---------------------------------------------------------------------------
+/**
+ * Level-2 (load) progressive-disclosure entry point.
+ *
+ * Reads the skill body from disk, parses frontmatter, defensively strips a
+ * malformed `comis.capability` block, validates the manifest, sanitizes the
+ * body, runs content scanning, emits audit events, and caches the resulting
+ * {@link PromptSkillContent} in `promptCache`.
+ *
+ * Side effects: on `ok()`, `promptCache.set(name, ...)` is called. On any
+ * `err()` return, the cache is NOT mutated.
+ *
+ * @returns `ok(PromptSkillContent)` on success; `err(Error)` when metadata
+ *          missing, file read fails, frontmatter invalid, body empty, manifest
+ *          validation fails, sanitization yields empty body, or content scan
+ *          flags a CRITICAL finding under `blockOnCritical`.
+ */
+export async function loadPromptSkillImpl(params) {
+    const { name, metadataMap, promptCache, config, eventBus, auditContext, logger } = params;
+    // Check metadata exists
+    const metadata = metadataMap.get(name);
+    if (!metadata) {
+        return err(new Error(`Prompt skill not found: ${name}`));
+    }
+    // Check prompt cache
+    const cached = promptCache.get(name);
+    if (cached) {
+        return ok(cached);
+    }
+    // Read the file from disk
+    let fileContent;
+    try {
+        fileContent = fs.readFileSync(metadata.filePath, "utf-8");
+    }
+    catch (e) {
+        return err(new Error(`Failed to read prompt skill file for ${name}: ${e instanceof Error ? e.message : String(e)}`));
+    }
+    // Parse frontmatter; defensively strip a malformed comis.capability
+    // block before strict validation so a typo in capability does NOT hide
+    // the skill at load time. Mirrors the discovery-side enrichment in
+    // discovery.ts.
+    const fmResult = parseFrontmatter(fileContent);
+    if (!fmResult.ok) {
+        return err(fmResult.error);
+    }
+    const rawBody = fmResult.value.body;
+    // Validate body is non-empty
+    if (!rawBody.trim()) {
+        return err(new Error(`Prompt skill "${name}" has no body content`));
+    }
+    const frontmatter = fmResult.value.frontmatter;
+    const ns = typeof frontmatter["comis"] === "object" &&
+        frontmatter["comis"] !== null &&
+        !Array.isArray(frontmatter["comis"])
+        ? frontmatter["comis"]
+        : undefined;
+    if (ns && ns["capability"] !== undefined) {
+        // Logger omitted: discovery enrichment already emitted the WARN for
+        // this file; a second identical line at load time is just noise.
+        const cap = parseComisCapabilityDefensively(ns["capability"], name, undefined);
+        if (cap === undefined) {
+            delete ns["capability"];
+        }
+    }
+    const manifestValidation = SkillManifestSchema.safeParse(frontmatter);
+    if (!manifestValidation.success) {
+        const issues = manifestValidation.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join("; ");
+        return err(new Error(`Manifest validation failed: ${issues}`));
+    }
+    const manifest = manifestValidation.data;
+    // Sanitize body content
+    const sanitized = sanitizeSkillBody(rawBody, config.promptSkills.maxBodyLength);
+    // Validate sanitized body is non-empty
+    if (!sanitized.body.trim()) {
+        return err(new Error(`Prompt skill "${name}" has no content after sanitization`));
+    }
+    // Content scanning at load time only, not per-request
+    const scanEnabled = config.contentScanning?.enabled ?? true;
+    if (scanEnabled) {
+        const scanResult = scanSkillContent(sanitized.body);
+        if (!scanResult.clean) {
+            // Diagnostic -- log warnings for each finding
+            for (const finding of scanResult.findings) {
+                logger?.warn({
+                    skillName: name,
+                    ruleId: finding.ruleId,
+                    category: finding.category,
+                    severity: finding.severity,
+                    hint: "Review skill body for suspicious content",
+                    errorKind: "validation",
+                }, `Content scan finding: ${finding.description}`);
+            }
+            // Determine if any CRITICAL findings exist
+            const hasCritical = scanResult.findings.some(f => f.severity === "CRITICAL");
+            // Emit scan audit event with findings in metadata
+            const scanAction = (config.contentScanning?.blockOnCritical && hasCritical)
+                ? "skill.scan.reject"
+                : "skill.scan";
+            emitSkillAudit(eventBus, {
+                ...auditContext,
+                skillName: name,
+                action: scanAction,
+                outcome: scanAction === "skill.scan.reject" ? "denied" : "success",
+                metadata: {
+                    findingCount: scanResult.findings.length,
+                    hasCritical,
+                    findings: scanResult.findings.map(f => ({
+                        ruleId: f.ruleId,
+                        category: f.category,
+                        severity: f.severity,
+                    })),
+                },
+            });
+            // blockOnCritical: return err() to prevent loading when explicitly enabled
+            if (config.contentScanning?.blockOnCritical && hasCritical) {
+                const criticalDetails = scanResult.findings
+                    .filter(f => f.severity === "CRITICAL")
+                    .map(f => `${f.ruleId} at line ${f.lineNumber}: "${f.matchedText}"`)
+                    .join("; ");
+                return err(new Error(`Skill "${name}" blocked: CRITICAL content scan findings [${criticalDetails}]`));
+            }
+        }
+    }
+    // Emit audit event
+    emitSkillAudit(eventBus, {
+        ...auditContext,
+        skillName: name,
+        action: "skill.prompt.load",
+        outcome: "success",
+        metadata: {
+            source: metadata.source,
+            bodyLength: sanitized.body.length,
+            htmlCommentsStripped: sanitized.htmlCommentsStripped,
+            truncated: sanitized.truncated,
+        },
+    });
+    // Construct and cache PromptSkillContent
+    const promptSkill = {
+        name: metadata.name,
+        description: metadata.description,
+        body: sanitized.body,
+        location: metadata.path,
+        userInvocable: metadata.userInvocable,
+        disableModelInvocation: metadata.disableModelInvocation,
+        allowedTools: manifest.allowedTools,
+        argumentHint: metadata.argumentHint,
+        source: metadata.source,
+    };
+    promptCache.set(name, promptSkill);
+    return ok(promptSkill);
+}