agent-first-data 0.9.0 → 0.11.0

package/README.md

@@ -92,6 +92,13 @@ redactedValueWith(value: unknown, redactionPolicy: RedactionPolicy): JsonValue
 redactedValueWithOptions(value: unknown, redactionOptions: RedactionOptions): JsonValue
 ```
 
+`_url` fields are scrubbed in place during redaction (userinfo password, plus query parameters whose name follows the `_secret`/`secretNames` rule). For a URL inside a free-form string, redact it directly before interpolating:
+
+```typescript
+redactUrlSecrets(url: string): string
+redactUrlSecretsWithOptions(url: string, redactionOptions: RedactionOptions): string
+```
+
 **Use case:** structured protocol payloads (frameworks automatically serialize)
 
 **Example:**
@@ -259,6 +266,30 @@ console.log(cliOutput(result, fmt));
 
 See `examples/agent_cli.ts` for the complete working example (`npx tsx --test examples/agent_cli.ts`).
 
+### Skill Admin (for spore CLIs that ship an Agent Skill)
+
+`runSkillAdmin` installs, uninstalls, and reports status of a spore's embedded `SKILL.md` across Codex, Claude Code, and opencode. Describe the skill once with a `SkillSpec`, then call it per action. It returns a typed `SkillReport` discriminated union (narrow on `code` to read fields, or serialize with `cliOutput`) or throws `SkillError`; it never writes to stdout/stderr. The generated `SKILL.md` is byte-identical to the Rust, Go, and Python ports.
+
+```typescript
+runSkillAdmin(spec: SkillSpec, action: SkillAction, options: SkillOptions): SkillReport
+
+const spec: SkillSpec = { name: "agent-first-widget", source: skillMarkdown, title: "Agent-First Widget", markerSlug: "afwidget" };
+const options: SkillOptions = { agent: "all", scope: "personal" };
+
+try {
+  const report = runSkillAdmin(spec, "install", options);
+  console.log(cliOutput(report as unknown as JsonValue, fmt));
+} catch (e) {
+  if (e instanceof SkillError) {
+    console.log(cliOutput(buildCliError(e.message, e.hint), fmt));
+    process.exit(1);
+  }
+  throw e;
+}
+```
+
+`status` reports `installed` / `valid` / `managed` / `current` per target; `current` is true only when the installed content matches the bundle, so re-running `install` refreshes a stale copy. See `examples/agent_cli.ts` for the `skill` subcommand wiring.
+
 ## Usage Examples
 
 ### Example 1: REST API

package/dist/format.d.ts

@@ -1,9 +1,10 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 16 public APIs and 4 types: protocol builders, redacted value helpers,
- * output formatters, redaction, parseSize, RedactionPolicy, RedactionOptions,
- * OutputStyle, and OutputOptions.
+ * 18 public APIs and 4 types: protocol builders, value redactors (copy and
+ * in-place; cover _secret and _url fields), output formatters, URL-string
+ * redactors (redactUrlSecrets / WithOptions), parseSize, RedactionPolicy,
+ * RedactionOptions, OutputStyle, and OutputOptions.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -24,7 +25,9 @@ export type RedactionOptions = {
     policy?: RedactionPolicy;
     /**
      * Field names to treat as secrets in addition to _secret suffixes.
-     * Matching is exact field-name equality at any nesting level.
+     * Matching is exact field-name equality at any nesting level. The same
+     * list also matches URL query-parameter names inside _url fields (see
+     * redactUrlSecrets).
      */
     secretNames?: readonly string[];
 };
@@ -62,6 +65,24 @@ export declare function redactedValue(value: unknown): JsonValue;
 export declare function redactedValueWith(value: unknown, redactionPolicy: RedactionPolicy): JsonValue;
 /** Return a JSON-safe copy with explicit redaction options applied. */
 export declare function redactedValueWithOptions(value: unknown, redactionOptions: RedactionOptions): JsonValue;
+/**
+ * Redact secret components of a single URL string, using default options.
+ *
+ * Returns url with its userinfo password and any _secret-suffixed query
+ * parameter values replaced by "***". See redactUrlSecretsWithOptions.
+ */
+export declare function redactUrlSecrets(url: string): string;
+/**
+ * Redact secret components of a single URL string.
+ *
+ * A query parameter is redacted iff its (form-decoded) name ends in
+ * _secret/_SECRET or matches an exact entry in secretNames. The userinfo
+ * password (scheme://user:pass@host) is always redacted as a structural rule.
+ * Only the secret spans are replaced with "***"; every other byte is preserved.
+ * A string that is not a single, whitespace-free, scheme-prefixed URL
+ * (including a URL embedded in surrounding prose) is returned unchanged.
+ */
+export declare function redactUrlSecretsWithOptions(url: string, redactionOptions: RedactionOptions): string;
 /**
  * Parse a human-readable size string into bytes.
  * Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).

package/dist/format.js

@@ -1,9 +1,10 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 16 public APIs and 4 types: protocol builders, redacted value helpers,
- * output formatters, redaction, parseSize, RedactionPolicy, RedactionOptions,
- * OutputStyle, and OutputOptions.
+ * 18 public APIs and 4 types: protocol builders, value redactors (copy and
+ * in-place; cover _secret and _url fields), output formatters, URL-string
+ * redactors (redactUrlSecrets / WithOptions), parseSize, RedactionPolicy,
+ * RedactionOptions, OutputStyle, and OutputOptions.
  */
 // ═══════════════════════════════════════════
 // Public API: Protocol Builders
@@ -122,6 +123,29 @@ export function redactedValueWithOptions(value, redactionOptions) {
     applyRedactionOptions(v, redactionOptions);
     return v;
 }
+/**
+ * Redact secret components of a single URL string, using default options.
+ *
+ * Returns url with its userinfo password and any _secret-suffixed query
+ * parameter values replaced by "***". See redactUrlSecretsWithOptions.
+ */
+export function redactUrlSecrets(url) {
+    return redactUrlSecretsWithOptions(url, {});
+}
+/**
+ * Redact secret components of a single URL string.
+ *
+ * A query parameter is redacted iff its (form-decoded) name ends in
+ * _secret/_SECRET or matches an exact entry in secretNames. The userinfo
+ * password (scheme://user:pass@host) is always redacted as a structural rule.
+ * Only the secret spans are replaced with "***"; every other byte is preserved.
+ * A string that is not a single, whitespace-free, scheme-prefixed URL
+ * (including a URL embedded in surrounding prose) is returned unchanged.
+ */
+export function redactUrlSecretsWithOptions(url, redactionOptions) {
+    const redacted = redactUrlInStr(url, secretNameSet(redactionOptions));
+    return redacted ?? url;
+}
 /**
  * Parse a human-readable size string into bytes.
  * Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).
@@ -158,82 +182,240 @@ export function parseSize(s) {
         return null;
     return result;
 }
-// ═══════════════════════════════════════════
-// Secret Redaction
-// ═══════════════════════════════════════════
-const EMPTY_SECRET_NAMES = new Set();
+const DEFAULT_CONTEXT = {
+    secretNames: new Set(),
+};
 function secretNameSet(redactionOptions) {
     return new Set(redactionOptions.secretNames ?? []);
 }
+function contextFromOptions(redactionOptions) {
+    return { secretNames: secretNameSet(redactionOptions) };
+}
 function keyHasSecretSuffix(key) {
     return key.endsWith("_secret") || key.endsWith("_SECRET");
 }
+function keyHasUrlSuffix(key) {
+    return key.endsWith("_url") || key.endsWith("_URL");
+}
 function isSecretKey(key, secretNames) {
     return keyHasSecretSuffix(key) || secretNames.has(key);
 }
-function redactSecrets(value, secretNames = EMPTY_SECRET_NAMES) {
+function redactSecrets(value, context = DEFAULT_CONTEXT) {
     if (isObject(value)) {
         for (const k of Object.keys(value)) {
-            if (isSecretKey(k, secretNames)) {
-                const v = value[k];
+            const v = value[k];
+            if (isSecretKey(k, context.secretNames)) {
                 if (isObject(v) || Array.isArray(v)) {
-                    redactSecrets(v, secretNames);
+                    redactSecrets(v, context);
                 }
                 else {
                     value[k] = "***";
                 }
             }
+            else if (keyHasUrlSuffix(k) && typeof v === "string") {
+                const redacted = redactUrlInStr(v, context.secretNames);
+                if (redacted !== null)
+                    value[k] = redacted;
+            }
             else {
-                redactSecrets(value[k], secretNames);
+                redactSecrets(v, context);
             }
         }
     }
     else if (Array.isArray(value)) {
-        for (const item of value) {
-            redactSecrets(item, secretNames);
+        for (let i = 0; i < value.length; i++) {
+            redactSecrets(value[i], context);
         }
     }
 }
-function redactSecretsStrict(value, secretNames = EMPTY_SECRET_NAMES) {
+function redactSecretsStrict(value, context = DEFAULT_CONTEXT) {
     if (isObject(value)) {
         for (const k of Object.keys(value)) {
-            if (isSecretKey(k, secretNames)) {
+            const v = value[k];
+            if (isSecretKey(k, context.secretNames)) {
                 value[k] = "***";
             }
+            else if (keyHasUrlSuffix(k) && typeof v === "string") {
+                const redacted = redactUrlInStr(v, context.secretNames);
+                if (redacted !== null)
+                    value[k] = redacted;
+            }
             else {
-                redactSecretsStrict(value[k], secretNames);
+                redactSecretsStrict(v, context);
             }
         }
     }
     else if (Array.isArray(value)) {
-        for (const item of value) {
-            redactSecretsStrict(item, secretNames);
+        for (let i = 0; i < value.length; i++) {
+            redactSecretsStrict(value[i], context);
         }
     }
 }
 function applyRedactionPolicy(value, redactionPolicy) {
-    applyRedactionPolicyWithNames(value, redactionPolicy, EMPTY_SECRET_NAMES);
+    applyRedactionPolicyWithContext(value, redactionPolicy, DEFAULT_CONTEXT);
 }
 function applyRedactionOptions(value, redactionOptions) {
-    applyRedactionPolicyWithNames(value, redactionOptions.policy, secretNameSet(redactionOptions));
+    applyRedactionPolicyWithContext(value, redactionOptions.policy, contextFromOptions(redactionOptions));
 }
-function applyRedactionPolicyWithNames(value, redactionPolicy, secretNames) {
+function applyRedactionPolicyWithContext(value, redactionPolicy, context) {
     switch (redactionPolicy) {
         case RedactionPolicy.RedactionTraceOnly:
             if (isObject(value) && value.trace !== undefined) {
-                redactSecrets(value.trace, secretNames);
+                redactSecrets(value.trace, context);
             }
             break;
         case RedactionPolicy.RedactionNone:
             break;
         case RedactionPolicy.RedactionStrict:
-            redactSecretsStrict(value, secretNames);
+            redactSecretsStrict(value, context);
             break;
         default:
             // Empty/unknown policy falls back to default full redaction.
-            redactSecrets(value, secretNames);
+            redactSecrets(value, context);
+            break;
+    }
+}
+// ═══════════════════════════════════════════
+// URL Secret Redaction
+// ═══════════════════════════════════════════
+/**
+ * Redact secret components of a single URL string, returning the redacted URL
+ * when s is a processable URL, or null when it is not (so callers can keep the
+ * original). Only secret spans change; all other bytes are preserved.
+ */
+function redactUrlInStr(s, secretNames) {
+    // Fast path + precondition: a single, whitespace-free, scheme-prefixed URL.
+    if (!s.includes("://") || !isSingleUrl(s) || !urlParses(s)) {
+        return null;
+    }
+    const schemeSep = s.indexOf("://");
+    const scheme = s.slice(0, schemeSep);
+    const rest = s.slice(schemeSep + 3);
+    // Authority runs from after "://" to the first '/', '?', or '#'.
+    let authEnd = rest.length;
+    for (let i = 0; i < rest.length; i++) {
+        const c = rest[i];
+        if (c === "/" || c === "?" || c === "#") {
+            authEnd = i;
+            break;
+        }
+    }
+    const authority = rest.slice(0, authEnd);
+    const remainder = rest.slice(authEnd);
+    const newAuthority = redactUserinfoPassword(authority);
+    // Query runs from the first '?' to the first '#' (or end).
+    let newRemainder;
+    const q = remainder.indexOf("?");
+    if (q >= 0) {
+        const path = remainder.slice(0, q);
+        const qOnwards = remainder.slice(q + 1);
+        const hash = qOnwards.indexOf("#");
+        let query;
+        let fragment;
+        if (hash >= 0) {
+            query = qOnwards.slice(0, hash);
+            fragment = qOnwards.slice(hash);
+        }
+        else {
+            query = qOnwards;
+            fragment = "";
+        }
+        newRemainder = `${path}?${redactQuery(query, secretNames)}${fragment}`;
+    }
+    else {
+        newRemainder = remainder;
+    }
+    return `${scheme}://${newAuthority}${newRemainder}`;
+}
+/**
+ * Replace the userinfo password (user:pass@) with "***", preserving the
+ * username. Authority without '@', or userinfo without ':', is unchanged.
+ */
+function redactUserinfoPassword(authority) {
+    const at = authority.indexOf("@");
+    if (at < 0)
+        return authority;
+    const userinfo = authority.slice(0, at);
+    const colon = userinfo.indexOf(":");
+    if (colon < 0)
+        return authority;
+    return `${authority.slice(0, colon)}:***${authority.slice(at)}`;
+}
+/**
+ * Redact the values of secret-named query parameters, preserving raw bytes of
+ * every other segment (keys, benign values, encoding, ordering, separators).
+ */
+function redactQuery(query, secretNames) {
+    return query
+        .split("&")
+        .map((segment) => {
+        const eq = segment.indexOf("=");
+        if (eq < 0)
+            return segment;
+        const rawKey = segment.slice(0, eq);
+        const name = formDecode(rawKey);
+        if (isSecretKey(name, secretNames)) {
+            return `${rawKey}=***`;
+        }
+        return segment;
+    })
+        .join("&");
+}
+/** Form-decode a query-parameter name: '+' → space, then percent-decode. */
+function formDecode(rawKey) {
+    const withSpaces = rawKey.replace(/\+/g, " ");
+    try {
+        return decodeURIComponent(withSpaces);
+    }
+    catch {
+        return withSpaces;
+    }
+}
+/** True when s parses as a URL (mirrors Rust's url::Url::parse check). */
+function urlParses(s) {
+    try {
+        new URL(s);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when s begins with a URL scheme (ALPHA *(ALPHA / DIGIT / "+" / "-" /
+ * ".") "://") and contains no ASCII whitespace — i.e. a single bare URL, not a
+ * URL embedded in prose.
+ */
+function isSingleUrl(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        // ASCII whitespace: tab, LF, VT, FF, CR, space.
+        if (c === 0x09 || c === 0x0a || c === 0x0b || c === 0x0c || c === 0x0d || c === 0x20) {
+            return false;
+        }
+    }
+    if (s.length === 0)
+        return false;
+    const first = s.charCodeAt(0);
+    if (!isAsciiAlpha(first))
+        return false;
+    let i = 1;
+    while (i < s.length) {
+        const c = s.charCodeAt(i);
+        if (isAsciiAlphanumeric(c) || c === 0x2b /* + */ || c === 0x2d /* - */ || c === 0x2e /* . */) {
+            i += 1;
+        }
+        else {
             break;
+        }
     }
+    return s.slice(i).startsWith("://");
+}
+function isAsciiAlpha(c) {
+    return (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a);
+}
+function isAsciiAlphanumeric(c) {
+    return isAsciiAlpha(c) || (c >= 0x30 && c <= 0x39);
 }
 // ═══════════════════════════════════════════
 // Suffix Processing

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, type RedactionOptions, OutputStyle, type OutputOptions, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, parseSize, } from "./format.js";
+export { buildJsonOk, buildJsonError, buildJson, type JsonValue, RedactionPolicy, type RedactionOptions, OutputStyle, type OutputOptions, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, } from "./format.js";
 export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
 export { type OutputFormat, cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, buildCliError, } from "./cli.js";
+export { type SkillSpec, type SkillAction, type SkillScope, type SkillAgentSelection, type SkillAgent, type SkillOptions, type SkillTargetStatus, type SkillUninstallStatus, type SkillReport, SkillError, runSkillAdmin, } from "./skill.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, OutputStyle, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, parseSize, } from "./format.js";
+export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, OutputStyle, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, } from "./format.js";
 export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
 export { cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, buildCliError, } from "./cli.js";
+export { SkillError, runSkillAdmin, } from "./skill.js";

package/dist/skill.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Reusable Agent Skill installer for spore CLIs.
+ *
+ * A spore that embeds its `SKILL.md` describes itself with a {@link SkillSpec} and calls
+ * {@link runSkillAdmin} to install, uninstall, or report status of that skill across
+ * supported coding agents (Codex, Claude Code, opencode).
+ *
+ * The function performs the filesystem work and returns the protocol value (rendered by
+ * the caller with `cliOutput`) or throws a {@link SkillError}. It never writes to
+ * stdout/stderr itself.
+ */
+/**
+ * Identity of the skill being managed and the tool that manages it.
+ *
+ * `name` is both the skill directory name and the `name:` front-matter field. `source` is
+ * the bundled `SKILL.md`. `title` is a human label for error messages. `markerSlug` seeds
+ * the managed-skill marker and the `Generated by <slug> skill install` comment, and is
+ * referenced in hints (e.g. `afwidget`).
+ */
+export interface SkillSpec {
+    name: string;
+    source: string;
+    title: string;
+    markerSlug: string;
+}
+/** The skill action to perform. */
+export type SkillAction = "status" | "install" | "uninstall";
+/** Where to install the skill. */
+export type SkillScope = "personal" | "project";
+/** Which agent target(s) to manage. */
+export type SkillAgentSelection = "all" | "codex" | "claude-code" | "opencode";
+/** A concrete agent a skill is installed for (no `all`). */
+export type SkillAgent = "codex" | "claude-code" | "opencode";
+/** Options shared by every skill action. */
+export interface SkillOptions {
+    agent: SkillAgentSelection;
+    scope: SkillScope;
+    /** Explicit skills directory; requires a single concrete `agent`. */
+    skillsDir?: string;
+    /** Overwrite or remove a skill that this tool did not manage. */
+    force?: boolean;
+}
+/** A skill admin failure with an operator-facing message and optional hint. */
+export declare class SkillError extends Error {
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+/** Per-target outcome of `status` / `install`. */
+export interface SkillTargetStatus {
+    agent: SkillAgent;
+    scope: SkillScope;
+    skills_dir: string;
+    skill_path: string;
+    installed: boolean;
+    managed: boolean;
+    valid: boolean;
+    current: boolean;
+    validation_error: string | null;
+}
+/** Per-target outcome of `uninstall`. */
+export interface SkillUninstallStatus {
+    agent: SkillAgent;
+    scope: SkillScope;
+    skills_dir: string;
+    skill_path: string;
+    removed: boolean;
+}
+/**
+ * The result of a skill action. Read fields off the discriminated union (narrow on
+ * `code`), or pass it to `cliOutput` to serialize — every field is already JSON-shaped.
+ */
+export type SkillReport = {
+    code: "skill_status";
+    skill: string;
+    installed_all: boolean;
+    valid_all: boolean;
+    current_all: boolean;
+    targets: SkillTargetStatus[];
+} | {
+    code: "skill_install";
+    skill: string;
+    installed: boolean;
+    targets: SkillTargetStatus[];
+    hint: string;
+} | {
+    code: "skill_uninstall";
+    skill: string;
+    removed_any: boolean;
+    targets: SkillUninstallStatus[];
+};
+/**
+ * Install, uninstall, or report status of `spec`'s skill across the selected agent
+ * target(s). Returns the protocol value (caller renders with `cliOutput`) or throws a
+ * {@link SkillError}. Does not touch stdout/stderr.
+ */
+export declare function runSkillAdmin(spec: SkillSpec, action: SkillAction, options: SkillOptions): SkillReport;

package/dist/skill.js

@@ -0,0 +1,369 @@
+/**
+ * Reusable Agent Skill installer for spore CLIs.
+ *
+ * A spore that embeds its `SKILL.md` describes itself with a {@link SkillSpec} and calls
+ * {@link runSkillAdmin} to install, uninstall, or report status of that skill across
+ * supported coding agents (Codex, Claude Code, opencode).
+ *
+ * The function performs the filesystem work and returns the protocol value (rendered by
+ * the caller with `cliOutput`) or throws a {@link SkillError}. It never writes to
+ * stdout/stderr itself.
+ */
+import * as fs from "node:fs";
+import { join } from "node:path";
+const SKILL_FILE_NAME = "SKILL.md";
+/** A skill admin failure with an operator-facing message and optional hint. */
+export class SkillError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = "SkillError";
+        this.hint = hint;
+    }
+}
+/**
+ * Install, uninstall, or report status of `spec`'s skill across the selected agent
+ * target(s). Returns the protocol value (caller renders with `cliOutput`) or throws a
+ * {@link SkillError}. Does not touch stdout/stderr.
+ */
+export function runSkillAdmin(spec, action, options) {
+    switch (action) {
+        case "status":
+            return status(spec, options);
+        case "install":
+            return install(spec, options);
+        case "uninstall":
+            return uninstall(spec, options);
+        default:
+            throw new SkillError(`unknown skill action '${action}'`);
+    }
+}
+function status(spec, options) {
+    const targets = resolveTargets(spec, options);
+    const statuses = targets.map((target) => targetStatus(spec, target));
+    return {
+        code: "skill_status",
+        skill: spec.name,
+        installed_all: statuses.every((s) => s.installed),
+        valid_all: statuses.every((s) => s.valid),
+        current_all: statuses.every((s) => s.current),
+        targets: statuses,
+    };
+}
+function install(spec, options) {
+    validateSkillText(spec, spec.source);
+    const targets = resolveTargets(spec, options);
+    const content = managedSkillContents(spec);
+    const installed = [];
+    for (const target of targets) {
+        fs.mkdirSync(target.skillDir, { recursive: true });
+        if (fs.existsSync(target.skillPath) && !isManagedOrBundledSkill(spec, target.skillPath) && !options.force) {
+            throw new SkillError(`refusing to overwrite unmanaged skill at ${target.skillPath}`, "pass --force to replace it, or choose another --skills-dir");
+        }
+        fs.writeFileSync(target.skillPath, content);
+        validateInstalledSkill(spec, target.skillPath);
+        installed.push(targetStatus(spec, target));
+    }
+    return {
+        code: "skill_install",
+        skill: spec.name,
+        installed: true,
+        targets: installed,
+        hint: "restart the agent so it reloads installed skills",
+    };
+}
+function uninstall(spec, options) {
+    const targets = resolveTargets(spec, options);
+    const removed = [];
+    for (const target of targets) {
+        if (!fs.existsSync(target.skillPath)) {
+            removed.push(targetUninstallStatus(target, false));
+            continue;
+        }
+        if (!isManagedOrBundledSkill(spec, target.skillPath) && !options.force) {
+            throw new SkillError(`refusing to remove unmanaged skill at ${target.skillPath}`, `only skills generated by ${spec.markerSlug} skill install can be removed without --force`);
+        }
+        fs.rmSync(target.skillPath);
+        // Prune the now-empty skill dir; ignore if not empty.
+        try {
+            fs.rmdirSync(target.skillDir);
+        }
+        catch {
+            // directory not empty or already gone
+        }
+        removed.push(targetUninstallStatus(target, true));
+    }
+    return {
+        code: "skill_uninstall",
+        skill: spec.name,
+        removed_any: removed.some((s) => s.removed),
+        targets: removed,
+    };
+}
+function resolveTargets(spec, options) {
+    if (options.skillsDir !== undefined && options.agent === "all") {
+        throw new SkillError("--skills-dir requires a single --agent", "custom skills directories are ambiguous when --agent all is used");
+    }
+    const { agent, scope } = options;
+    if (agent === "all" && scope === "personal") {
+        return [
+            resolveTarget(spec, "codex", "personal", undefined),
+            resolveTarget(spec, "claude-code", "personal", undefined),
+            resolveTarget(spec, "opencode", "personal", undefined),
+        ];
+    }
+    // Codex has no project scope, so --agent all --scope project skips it.
+    if (agent === "all" && scope === "project") {
+        return [
+            resolveTarget(spec, "claude-code", "project", undefined),
+            resolveTarget(spec, "opencode", "project", undefined),
+        ];
+    }
+    if (agent === "codex" && scope === "project") {
+        throw new SkillError("Codex project skill scope is not supported", "use personal scope for Codex, or --agent claude-code/opencode --scope project");
+    }
+    if (agent === "codex") {
+        return [resolveTarget(spec, "codex", "personal", options.skillsDir)];
+    }
+    if (agent === "claude-code") {
+        return [resolveTarget(spec, "claude-code", scope, options.skillsDir)];
+    }
+    if (agent === "opencode") {
+        return [resolveTarget(spec, "opencode", scope, options.skillsDir)];
+    }
+    throw new SkillError(`invalid --agent '${agent}'`);
+}
+function resolveTarget(spec, agent, scope, skillsDir) {
+    const base = skillsDir !== undefined ? expandTilde(skillsDir) : defaultSkillsDir(agent, scope);
+    const skillDir = join(base, spec.name);
+    return {
+        agent,
+        scope,
+        skillsDir: base,
+        skillDir,
+        skillPath: join(skillDir, SKILL_FILE_NAME),
+    };
+}
+function defaultSkillsDir(agent, scope) {
+    if (agent === "codex") {
+        if (scope === "project") {
+            throw new SkillError("Codex project skill scope is not supported");
+        }
+        const codexHome = process.env["CODEX_HOME"];
+        if (codexHome !== undefined) {
+            return join(codexHome, "skills");
+        }
+        return join(homeDir(), ".codex", "skills");
+    }
+    if (agent === "claude-code") {
+        if (scope === "project") {
+            return join(process.cwd(), ".claude", "skills");
+        }
+        return join(homeDir(), ".claude", "skills");
+    }
+    // opencode
+    if (scope === "project") {
+        return join(process.cwd(), ".opencode", "skills");
+    }
+    const xdg = process.env["XDG_CONFIG_HOME"];
+    if (xdg !== undefined) {
+        return join(xdg, "opencode", "skills");
+    }
+    return join(homeDir(), ".config", "opencode", "skills");
+}
+function targetStatus(spec, target) {
+    const installed = isFile(target.skillPath);
+    let valid = false;
+    let current = false;
+    let managed = false;
+    let validationError = null;
+    if (installed) {
+        const text = fs.readFileSync(target.skillPath, "utf-8");
+        managed = skillTextIsManagedOrBundled(spec, text);
+        current = normalizeSkillText(spec, text) === normalizeSkillText(spec, spec.source);
+        const error = validateSkillFrontmatter(text);
+        if (error === null) {
+            valid = true;
+        }
+        else {
+            validationError = error;
+        }
+    }
+    return {
+        agent: target.agent,
+        scope: target.scope,
+        skills_dir: target.skillsDir,
+        skill_path: target.skillPath,
+        installed,
+        managed,
+        valid,
+        current,
+        validation_error: validationError,
+    };
+}
+function targetUninstallStatus(target, removed) {
+    return {
+        agent: target.agent,
+        scope: target.scope,
+        skills_dir: target.skillsDir,
+        skill_path: target.skillPath,
+        removed,
+    };
+}
+function generatedBy(spec) {
+    return `Generated by ${spec.markerSlug} skill install`;
+}
+function marker(spec) {
+    return `${spec.markerSlug}-managed-skill: true`;
+}
+function managedSkillContents(spec) {
+    const gen = generatedBy(spec);
+    const mark = marker(spec);
+    const lines = splitLines(spec.source);
+    const out = [];
+    let inserted = false;
+    lines.forEach((line, i) => {
+        out.push(line);
+        if (i === 0)
+            return;
+        if (!inserted && line.trim() === "---") {
+            out.push(`<!-- ${gen} -->`, `<!-- ${mark} -->`, "");
+            inserted = true;
+        }
+    });
+    if (!inserted) {
+        out.push(`<!-- ${gen} -->`, `<!-- ${mark} -->`);
+    }
+    return out.map((line) => line + "\n").join("");
+}
+function validateInstalledSkill(spec, path) {
+    validateSkillText(spec, fs.readFileSync(path, "utf-8"));
+}
+function validateSkillText(spec, text) {
+    const error = validateSkillFrontmatter(text);
+    if (error !== null) {
+        throw new SkillError(`invalid ${spec.title} skill front matter: ${error}`, "quote scalar values that contain ': ', especially description");
+    }
+}
+function validateSkillFrontmatter(text) {
+    const lines = splitLines(text);
+    if (lines.length === 0) {
+        return "missing YAML front matter";
+    }
+    if (lines[0].trim() !== "---") {
+        return "missing opening --- YAML front matter delimiter";
+    }
+    let foundEnd = false;
+    let hasName = false;
+    let hasDescription = false;
+    for (let idx = 1; idx < lines.length; idx++) {
+        const line = lines[idx];
+        const lineNo = idx + 1;
+        const trimmed = line.trim();
+        if (trimmed === "---") {
+            foundEnd = true;
+            break;
+        }
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            continue;
+        }
+        if (line.startsWith(" ") || line.startsWith("\t")) {
+            return `line ${lineNo}: nested YAML is not supported here`;
+        }
+        const colon = line.indexOf(":");
+        if (colon === -1) {
+            return `line ${lineNo}: expected key: value`;
+        }
+        const key = line.slice(0, colon).trim();
+        if (key === "") {
+            return `line ${lineNo}: empty key`;
+        }
+        const value = line.slice(colon + 1).replace(/^\s+/, "");
+        if (key === "name")
+            hasName = true;
+        if (key === "description")
+            hasDescription = true;
+        if (value.startsWith('"') || value.startsWith("'")) {
+            continue;
+        }
+        if (value.includes(": ")) {
+            return `line ${lineNo}: unquoted scalar contains ': '; quote the value`;
+        }
+    }
+    if (!foundEnd) {
+        return "missing closing --- YAML front matter delimiter";
+    }
+    if (!hasName) {
+        return "missing required name field";
+    }
+    if (!hasDescription) {
+        return "missing required description field";
+    }
+    return null;
+}
+function isManagedOrBundledSkill(spec, path) {
+    if (!fs.existsSync(path)) {
+        return false;
+    }
+    return skillTextIsManagedOrBundled(spec, fs.readFileSync(path, "utf-8"));
+}
+function skillTextIsManagedOrBundled(spec, text) {
+    const mark = marker(spec);
+    const gen = generatedBy(spec);
+    if (text.includes(mark) && text.includes(gen)) {
+        return true;
+    }
+    return normalizeSkillText(spec, text) === normalizeSkillText(spec, spec.source);
+}
+/**
+ * Drop the managed-marker lines, then collapse runs of blank lines to one so that the
+ * blank line `managedSkillContents` inserts after the marker block does not make a
+ * managed install compare unequal to the bundled source.
+ */
+function normalizeSkillText(spec, text) {
+    const mark = marker(spec);
+    const gen = generatedBy(spec);
+    const out = [];
+    for (const line of splitLines(text)) {
+        const trimmed = line.trim();
+        if (trimmed.includes(mark) || trimmed.includes(gen)) {
+            continue;
+        }
+        if (trimmed === "" && out.length > 0 && out[out.length - 1].trim() === "") {
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join("\n").trim();
+}
+function homeDir() {
+    const home = process.env["HOME"] ?? process.env["USERPROFILE"];
+    if (home !== undefined) {
+        return home;
+    }
+    throw new SkillError("cannot determine home directory", "pass --skills-dir explicitly");
+}
+function expandTilde(input) {
+    if (input === "~") {
+        return homeDir();
+    }
+    if (input.startsWith("~/")) {
+        return join(homeDir(), input.slice(2));
+    }
+    return input;
+}
+/**
+ * Mirror Rust's `str::lines`: split on `\n` (normalizing `\r\n`), dropping a single
+ * trailing empty element from a final newline.
+ */
+function isFile(p) {
+    const st = fs.statSync(p, { throwIfNoEntry: false });
+    return st !== undefined && st.isFile();
+}
+function splitLines(s) {
+    const lines = s.replace(/\r\n/g, "\n").split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "A naming convention that lets AI agents understand your data without being told what it means.",
   "license": "MIT",
   "repository": {