@agentxm/registry-protocol 0.28.4-bootstrap.0

package/dist/src/unstable/lint/catalog/shared/manifest-present.js

@@ -0,0 +1,37 @@
+/**
+ * Shared factory for `manifest-present` advisory rules.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+export const makeManifestPresentRule = (args) => {
+    const severity = args.severity ?? "error";
+    const getFiles = args.getFiles ?? ((context) => context.files);
+    const applies = args.applies ?? (() => true);
+    return {
+        id: args.ruleId,
+        description: args.description,
+        kind: "advisory",
+        severity,
+        check: (context) => {
+            if (!applies(context)) {
+                return Effect.succeed([]);
+            }
+            return Effect.map(getFiles(context).exists(args.manifestFile), (present) => {
+                if (present) {
+                    return [];
+                }
+                return [
+                    {
+                        kind: "advisory",
+                        ruleId: args.ruleId,
+                        severity,
+                        message: args.missingMessage,
+                        location: { file: args.manifestFile },
+                    },
+                ];
+            });
+        },
+    };
+};
+//# sourceMappingURL=manifest-present.js.map

package/dist/src/unstable/lint/catalog/shared/recommended-packs-rules.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared factories for the `standalone` / `recommendedPacks` coherence rules.
+ *
+ * Both fields come from `NonPackManifestFields` in
+ * `extensions/common.ts`, so every non-pack catalog (`skill`, `subagent`,
+ * `mcp-server`, `rule`, `hook`, `knowledge`) enforces the same two invariants
+ * against its own manifest. Rather than copy twelve near-identical rule
+ * bodies, each catalog registers a rule produced here and parameterized by
+ * namespace and manifest accessor — the same shape `shared/schema-rule.ts`
+ * establishes for the `-schema-valid` rules.
+ *
+ * Both rules ship at `warning`. They would otherwise retroactively reject
+ * manifests published before the rules existed, which the rule-authoring
+ * guide's "new rules start soft" clause forbids.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { AdvisoryRule } from "../../rule.js";
+/**
+ * Per-catalog parameters for the shared non-pack manifest rules.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface RecommendedPacksRuleOptions<C> {
+    /** Rule-id namespace; matches the context kind (`skill`, `hook`, ...). */
+    readonly namespace: string;
+    /** Accessor-relative manifest filename stamped on `location.file`. */
+    readonly manifestFile: string;
+    /** Reads the caller-decoded manifest JSON off the rule context. */
+    readonly manifestJson: (context: C) => unknown;
+}
+/**
+ * Split a `recommendedPacks` entry into its FQN and optional version range.
+ *
+ * Mirrors the separator search in `PackSpecSchema`: the range delimiter is the
+ * first `@` after the last `/`, since the owner segment also starts with `@`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const splitPackSpec: (spec: string) => {
+    readonly fqn: string;
+    readonly range: string | undefined;
+};
+/**
+ * Build the `<namespace>/standalone-declaration-valid` rule for one catalog.
+ *
+ * A manifest with `standalone: false` declares that it is meaningless without
+ * one of its recommended packs. With `recommendedPacks` absent or empty that
+ * declaration is self-contradictory and nothing downstream — registry, Library
+ * UI, or `workspace/recommended-packs-retained` — can act on it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const makeStandaloneDeclarationValidRule: <C>(options: RecommendedPacksRuleOptions<C>) => AdvisoryRule<C>;
+/**
+ * Build the `<namespace>/recommended-packs-valid` rule for one catalog.
+ *
+ * `recommendedPacks` is typed `PackSpecSchema`, which permits a trailing
+ * version range, but nothing consumes one — recommendations are matched by
+ * name — and `axm help packs` tells authors to use the bare reference. One
+ * finding per offending entry.
+ *
+ * When published manifests have drained, the field can move to
+ * `PackFqnSchema` and this rule retires: decoding takes over.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const makeRecommendedPacksValidRule: <C>(options: RecommendedPacksRuleOptions<C>) => AdvisoryRule<C>;
+//# sourceMappingURL=recommended-packs-rules.d.ts.map

package/dist/src/unstable/lint/catalog/shared/recommended-packs-rules.js

@@ -0,0 +1,139 @@
+/**
+ * Shared factories for the `standalone` / `recommendedPacks` coherence rules.
+ *
+ * Both fields come from `NonPackManifestFields` in
+ * `extensions/common.ts`, so every non-pack catalog (`skill`, `subagent`,
+ * `mcp-server`, `rule`, `hook`, `knowledge`) enforces the same two invariants
+ * against its own manifest. Rather than copy twelve near-identical rule
+ * bodies, each catalog registers a rule produced here and parameterized by
+ * namespace and manifest accessor — the same shape `shared/schema-rule.ts`
+ * establishes for the `-schema-valid` rules.
+ *
+ * Both rules ship at `warning`. They would otherwise retroactively reject
+ * manifests published before the rules existed, which the rule-authoring
+ * guide's "new rules start soft" clause forbids.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import { isManifestJsonParseFailure } from "./manifest-json.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Narrow a caller-decoded manifest value to a plain record, or `undefined`
+ * when there is nothing for these rules to read. Absent manifests are the
+ * `-present` rule's problem; unparseable ones are the `-schema-valid` rule's.
+ */
+const manifestRecord = (input) => {
+    if (input === undefined || isManifestJsonParseFailure(input) || !isRecord(input)) {
+        return undefined;
+    }
+    return input;
+};
+const stringEntries = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+/**
+ * Split a `recommendedPacks` entry into its FQN and optional version range.
+ *
+ * Mirrors the separator search in `PackSpecSchema`: the range delimiter is the
+ * first `@` after the last `/`, since the owner segment also starts with `@`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const splitPackSpec = (spec) => {
+    const lastSlash = spec.lastIndexOf("/");
+    const rangeAt = lastSlash > 0 ? spec.indexOf("@", lastSlash + 1) : -1;
+    if (rangeAt <= 0) {
+        return { fqn: spec, range: undefined };
+    }
+    return { fqn: spec.slice(0, rangeAt), range: spec.slice(rangeAt + 1) };
+};
+// -----------------------------------------------------------------------------
+// <namespace>/standalone-declaration-valid
+// -----------------------------------------------------------------------------
+/**
+ * Build the `<namespace>/standalone-declaration-valid` rule for one catalog.
+ *
+ * A manifest with `standalone: false` declares that it is meaningless without
+ * one of its recommended packs. With `recommendedPacks` absent or empty that
+ * declaration is self-contradictory and nothing downstream — registry, Library
+ * UI, or `workspace/recommended-packs-retained` — can act on it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const makeStandaloneDeclarationValidRule = (options) => {
+    const ruleId = `${options.namespace}/standalone-declaration-valid`;
+    return {
+        id: ruleId,
+        description: "Extensions that are not standalone recommend at least one pack.",
+        kind: "advisory",
+        severity: "warning",
+        check: (context) => {
+            const manifest = manifestRecord(options.manifestJson(context));
+            if (manifest === undefined || manifest["standalone"] !== false) {
+                return Effect.succeed([]);
+            }
+            if (stringEntries(manifest["recommendedPacks"]).length > 0) {
+                return Effect.succeed([]);
+            }
+            return Effect.succeed([
+                {
+                    kind: "advisory",
+                    ruleId,
+                    severity: "warning",
+                    message: "`standalone` is set to false, which says this extension only works alongside one of its recommended packs, but no `recommendedPacks` are declared. " +
+                        `To keep the restriction, add each pack's fully qualified name (\`@owner/packs/<name>\`) under \`recommendedPacks\` in \`${options.manifestFile}\`. ` +
+                        `If the extension does work on its own, remove the \`standalone\` key from \`${options.manifestFile}\`.`,
+                    location: { file: options.manifestFile },
+                },
+            ]);
+        },
+    };
+};
+// -----------------------------------------------------------------------------
+// <namespace>/recommended-packs-valid
+// -----------------------------------------------------------------------------
+/**
+ * Build the `<namespace>/recommended-packs-valid` rule for one catalog.
+ *
+ * `recommendedPacks` is typed `PackSpecSchema`, which permits a trailing
+ * version range, but nothing consumes one — recommendations are matched by
+ * name — and `axm help packs` tells authors to use the bare reference. One
+ * finding per offending entry.
+ *
+ * When published manifests have drained, the field can move to
+ * `PackFqnSchema` and this rule retires: decoding takes over.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const makeRecommendedPacksValidRule = (options) => {
+    const ruleId = `${options.namespace}/recommended-packs-valid`;
+    return {
+        id: ruleId,
+        description: "Recommended packs are referenced by name without a version range.",
+        kind: "advisory",
+        severity: "warning",
+        check: (context) => {
+            const manifest = manifestRecord(options.manifestJson(context));
+            if (manifest === undefined) {
+                return Effect.succeed([]);
+            }
+            const findings = [];
+            for (const entry of stringEntries(manifest["recommendedPacks"])) {
+                const { fqn, range } = splitPackSpec(entry);
+                if (range === undefined) {
+                    continue;
+                }
+                findings.push({
+                    kind: "advisory",
+                    ruleId,
+                    severity: "warning",
+                    message: `\`recommendedPacks\` entry '${entry}' pins a version range, but recommended packs are matched by name only, so the range is ignored. ` +
+                        `Replace it with the bare pack reference '${fqn}' under \`recommendedPacks\` in \`${options.manifestFile}\`.`,
+                    location: { file: options.manifestFile },
+                });
+            }
+            return Effect.succeed(findings);
+        },
+    };
+};
+//# sourceMappingURL=recommended-packs-rules.js.map

package/dist/src/unstable/lint/catalog/shared/schema-rule.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared schema-delegation plumbing for `-schema-valid` rules.
+ *
+ * Every rule whose id ends in `-schema-valid` implements `check` by
+ * running the canonical schema through `Schema.decodeUnknownResult` with
+ * `onExcessProperty: "ignore"` and `errors: "all"`, then mapping the issues
+ * through `issuesToFindings`.
+ *
+ * Phase 3a is the first catalog; landing the helper now keeps the Phase 3b
+ * pack catalog from duplicating the composition when it arrives. The helper is
+ * intentionally narrow — only the surface the `-schema-valid` rules need.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { AdvisoryFinding, Severity } from "../../rule.js";
+/**
+ * Decode `input` against `schema` (excess keys ignored, all issues collected)
+ * and return one advisory finding per leaf issue. Success produces `[]`.
+ *
+ * `input` of `undefined` short-circuits to `[]` — the caller is expected to
+ * have already guarded on "manifest exists" via the complementary
+ * `-present` rule.
+ *
+ * @param ruleId   - `<namespace>/<name>` id of the calling rule.
+ * @param severity - Severity to stamp on each emitted finding.
+ * @param file     - Accessor-relative file path to stamp on `location.file`.
+ * @param schema   - Canonical Effect schema; `Schema.decodeUnknownResult`
+ *                   runs with `onExcessProperty: "ignore"` and `errors: "all"`.
+ * @param input    - Raw decoded JSON value to check (typically `subject.*Json`).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const schemaDecodeFindings: <A, I>(ruleId: string, severity: Severity, file: string, schema: Schema.Codec<A, I>, input: unknown) => Effect.Effect<ReadonlyArray<AdvisoryFinding>>;
+/**
+ * Read the top-level field names of a `Schema.Struct` value.
+ *
+ * Callers produce an `allowedKeys` set in one place, driven by the schema
+ * itself — no copy-paste of field names into rule bodies. If the schema
+ * gains a field the allowed-keys set grows by construction.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const structFieldKeys: (struct: {
+    readonly fields: Readonly<Record<string, unknown>>;
+}) => ReadonlySet<string>;
+/**
+ * Enumerate top-level keys present on `input` that are not declared by
+ * `allowedKeys`. Returns one advisory finding per unknown key.
+ *
+ * `input` of `undefined` or non-object short-circuits to `[]`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const enumerateUnknownTopLevelKeys: (ruleId: string, severity: Severity, file: string, allowedKeys: ReadonlySet<string>, input: unknown) => ReadonlyArray<AdvisoryFinding>;
+//# sourceMappingURL=schema-rule.d.ts.map

package/dist/src/unstable/lint/catalog/shared/schema-rule.js

@@ -0,0 +1,103 @@
+/**
+ * Shared schema-delegation plumbing for `-schema-valid` rules.
+ *
+ * Every rule whose id ends in `-schema-valid` implements `check` by
+ * running the canonical schema through `Schema.decodeUnknownResult` with
+ * `onExcessProperty: "ignore"` and `errors: "all"`, then mapping the issues
+ * through `issuesToFindings`.
+ *
+ * Phase 3a is the first catalog; landing the helper now keeps the Phase 3b
+ * pack catalog from duplicating the composition when it arrives. The helper is
+ * intentionally narrow — only the surface the `-schema-valid` rules need.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { describeSchemaDocument } from "../../describe-document.js";
+import { issuesToFindings } from "../../issues-to-findings.js";
+import { isManifestJsonParseFailure, manifestJsonParseFailureToFinding } from "./manifest-json.js";
+// -----------------------------------------------------------------------------
+// schemaDecodeFindings
+// -----------------------------------------------------------------------------
+/**
+ * Decode `input` against `schema` (excess keys ignored, all issues collected)
+ * and return one advisory finding per leaf issue. Success produces `[]`.
+ *
+ * `input` of `undefined` short-circuits to `[]` — the caller is expected to
+ * have already guarded on "manifest exists" via the complementary
+ * `-present` rule.
+ *
+ * @param ruleId   - `<namespace>/<name>` id of the calling rule.
+ * @param severity - Severity to stamp on each emitted finding.
+ * @param file     - Accessor-relative file path to stamp on `location.file`.
+ * @param schema   - Canonical Effect schema; `Schema.decodeUnknownResult`
+ *                   runs with `onExcessProperty: "ignore"` and `errors: "all"`.
+ * @param input    - Raw decoded JSON value to check (typically `subject.*Json`).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const schemaDecodeFindings = (ruleId, severity, file, schema, input) => {
+    if (input === undefined) {
+        return Effect.succeed([]);
+    }
+    if (isManifestJsonParseFailure(input)) {
+        return Effect.succeed([manifestJsonParseFailureToFinding(ruleId, severity, file, input)]);
+    }
+    const result = Schema.decodeUnknownResult(schema)(input, {
+        onExcessProperty: "ignore",
+        errors: "all",
+    });
+    if (Result.isSuccess(result)) {
+        return Effect.succeed([]);
+    }
+    return Effect.succeed(issuesToFindings(ruleId, severity, file, result.failure.issue));
+};
+// -----------------------------------------------------------------------------
+// enumerateUnknownTopLevelKeys
+// -----------------------------------------------------------------------------
+/**
+ * Read the top-level field names of a `Schema.Struct` value.
+ *
+ * Callers produce an `allowedKeys` set in one place, driven by the schema
+ * itself — no copy-paste of field names into rule bodies. If the schema
+ * gains a field the allowed-keys set grows by construction.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const structFieldKeys = (struct) => new Set(Object.keys(struct.fields));
+/**
+ * Enumerate top-level keys present on `input` that are not declared by
+ * `allowedKeys`. Returns one advisory finding per unknown key.
+ *
+ * `input` of `undefined` or non-object short-circuits to `[]`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const enumerateUnknownTopLevelKeys = (ruleId, severity, file, allowedKeys, input) => {
+    if (isManifestJsonParseFailure(input)) {
+        return [];
+    }
+    if (!isPlainRecord(input)) {
+        return [];
+    }
+    const findings = [];
+    for (const key of Object.keys(input)) {
+        if (allowedKeys.has(key)) {
+            continue;
+        }
+        findings.push({
+            kind: "advisory",
+            ruleId,
+            severity,
+            message: `${describeSchemaDocument(file)} has unrecognized top-level field '${key}'. ` +
+                `The current schema does not recognize this field.`,
+            location: { file },
+        });
+    }
+    return findings;
+};
+const isPlainRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+//# sourceMappingURL=schema-rule.js.map

package/dist/src/unstable/lint/catalog/skill/frontmatter-parseable.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `skill/frontmatter-parseable` — SKILL.md frontmatter parses as a YAML
+ * mapping.
+ *
+ * Cascade (reports the first failure in the order below; later arms
+ * short-circuit):
+ *
+ * 1. SKILL.md begins with `---` at byte 0 (no BOM, no leading whitespace, no
+ *    leading HTML comment). This is the arm that caught the
+ *    `@agentxm/skills/axm` regression — an HTML comment preceded the
+ *    frontmatter delimiter, so YAML parsers silently treated the content as
+ *    body.
+ * 2. Frontmatter YAML parses without error.
+ * 3. Parsed frontmatter is a mapping (not a list, not a scalar).
+ *
+ * Presence is handled by `skill/skill-md-present`; this rule early-returns
+ * `[]` when `SKILL.md` is absent.
+ *
+ * Advisory-only — the cascade mixes one mechanically-fixable arm
+ * (strip-leading-bytes) with arms requiring human judgment (fix YAML
+ * syntax). Per the lint design, splitting by
+ * kind or adding a byte-range mutation Operation is deferred until a second
+ * mechanical arm justifies it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { SkillRuleContext } from "../../context.js";
+import type { AdvisoryRule } from "../../rule.js";
+export declare const frontmatterParseableRule: AdvisoryRule<SkillRuleContext>;
+//# sourceMappingURL=frontmatter-parseable.d.ts.map

package/dist/src/unstable/lint/catalog/skill/frontmatter-parseable.js

@@ -0,0 +1,148 @@
+/**
+ * `skill/frontmatter-parseable` — SKILL.md frontmatter parses as a YAML
+ * mapping.
+ *
+ * Cascade (reports the first failure in the order below; later arms
+ * short-circuit):
+ *
+ * 1. SKILL.md begins with `---` at byte 0 (no BOM, no leading whitespace, no
+ *    leading HTML comment). This is the arm that caught the
+ *    `@agentxm/skills/axm` regression — an HTML comment preceded the
+ *    frontmatter delimiter, so YAML parsers silently treated the content as
+ *    body.
+ * 2. Frontmatter YAML parses without error.
+ * 3. Parsed frontmatter is a mapping (not a list, not a scalar).
+ *
+ * Presence is handled by `skill/skill-md-present`; this rule early-returns
+ * `[]` when `SKILL.md` is absent.
+ *
+ * Advisory-only — the cascade mixes one mechanically-fixable arm
+ * (strip-leading-bytes) with arms requiring human judgment (fix YAML
+ * syntax). Per the lint design, splitting by
+ * kind or adding a byte-range mutation Operation is deferred until a second
+ * mechanical arm justifies it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import YAML from "yaml";
+const RULE_ID = "skill/frontmatter-parseable";
+const SKILL_MD = "SKILL.md";
+const DELIMITER = "---";
+// U+FEFF — UTF-8 BOM as a single code point. Escape form so the editor /
+// formatter can't silently strip the literal.
+const UTF8_BOM = "\uFEFF";
+// `ignoreBOM: true` here means "pass the BOM through to the decoded string,
+// don't strip it" — cascade arm 1 must see the BOM to flag it.
+const decoder = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true });
+export const frontmatterParseableRule = {
+    id: RULE_ID,
+    description: "SKILL.md frontmatter is a valid YAML mapping.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => Effect.gen(function* () {
+        const exists = yield* context.files.exists(SKILL_MD);
+        if (!exists) {
+            // Presence is covered by `skill/skill-md-present`.
+            return [];
+        }
+        const bytesResult = yield* context.files.readBytes(SKILL_MD).pipe(Effect.map((bytes) => ({ kind: "ok", bytes })), 
+        // Treat read errors the same as absence — presence rule already owns
+        // that path. If `exists` said true but read fails, the cascade can't
+        // run anyway; silence here keeps the finding count at one.
+        Effect.catch(() => Effect.succeed({ kind: "none" })));
+        if (bytesResult.kind === "none") {
+            return [];
+        }
+        const content = decoder.decode(bytesResult.bytes);
+        return evaluateCascade(content);
+    }),
+};
+// -----------------------------------------------------------------------------
+// Cascade
+// -----------------------------------------------------------------------------
+const evaluateCascade = (content) => {
+    const leading = detectLeadingBytes(content);
+    if (leading !== undefined) {
+        return [leading];
+    }
+    const parsed = parseFrontmatterYaml(content);
+    if (parsed === undefined) {
+        // No frontmatter block. Treat as bad (cascade arm 1 "begins with ---"
+        // already handled the "literally no ---" case; reaching here means the
+        // delimiter was found but the closing delimiter is missing).
+        return [
+            finding("SKILL.md frontmatter is malformed because the closing `---` delimiter is missing. Add a closing `---` after the frontmatter block."),
+        ];
+    }
+    if (parsed.kind === "parse-error") {
+        return [
+            finding(`SKILL.md frontmatter YAML is invalid. Detail: ${parsed.message}. Fix the YAML syntax in the frontmatter block.`),
+        ];
+    }
+    if (!isMapping(parsed.value)) {
+        return [
+            finding("SKILL.md frontmatter must be a YAML mapping, not a list or scalar. Rewrite the frontmatter block in `SKILL.md` as `key: value` pairs."),
+        ];
+    }
+    return [];
+};
+// -----------------------------------------------------------------------------
+// Arm 1: leading bytes before `---`
+// -----------------------------------------------------------------------------
+const detectLeadingBytes = (content) => {
+    if (content.startsWith(UTF8_BOM)) {
+        return finding("SKILL.md starts with a UTF-8 BOM before the frontmatter delimiter. Remove the BOM so the file starts with `---`.", { line: 1 });
+    }
+    if (content.startsWith(DELIMITER)) {
+        return undefined;
+    }
+    // Any non-`---` leading content is a cascade-arm-1 violation. Detect the
+    // common HTML-comment case explicitly so the finding message is clear.
+    if (/^\s*<!--/.test(content)) {
+        return finding("SKILL.md starts with an HTML comment before the frontmatter delimiter. Move or remove the comment so the file starts with `---`.", { line: 1 });
+    }
+    return finding("SKILL.md must start with the frontmatter delimiter `---`. Remove any leading content so the file starts with `---`.", { line: 1 });
+};
+const parseFrontmatterYaml = (content) => {
+    // content starts with `---` (arm 1 guaranteed). Find closing delimiter on a
+    // new line.
+    const afterOpening = content.indexOf("\n");
+    if (afterOpening === -1) {
+        return undefined;
+    }
+    const closingIndex = content.indexOf(`\n${DELIMITER}`, afterOpening);
+    if (closingIndex === -1) {
+        return undefined;
+    }
+    const yamlContent = content.slice(afterOpening + 1, closingIndex);
+    try {
+        // YAML.parse returns `null | undefined` for empty input; we care about
+        // shape, not emptiness at this arm.
+        const value = YAML.parse(yamlContent);
+        return { kind: "parsed", value };
+    }
+    catch (error) {
+        return {
+            kind: "parse-error",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+const isMapping = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+// -----------------------------------------------------------------------------
+// Finding helpers
+// -----------------------------------------------------------------------------
+const finding = (message, position) => ({
+    kind: "advisory",
+    ruleId: RULE_ID,
+    severity: "error",
+    message,
+    location: {
+        file: SKILL_MD,
+        ...(position?.line !== undefined ? { line: position.line } : {}),
+        ...(position?.column !== undefined ? { column: position.column } : {}),
+    },
+});
+//# sourceMappingURL=frontmatter-parseable.js.map

package/dist/src/unstable/lint/catalog/skill/frontmatter-standard-valid.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `skill/frontmatter-standard-valid` — SKILL.md metadata conforms to the
+ * pinned Agent Skills specification and reference validator.
+ *
+ * Parsing failures are owned by `skill/frontmatter-parseable`; this rule
+ * returns no findings until the frontmatter is a YAML mapping.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { SkillRuleContext } from "../../context.js";
+import type { AdvisoryRule } from "../../rule.js";
+export declare const frontmatterStandardValidRule: AdvisoryRule<SkillRuleContext>;
+//# sourceMappingURL=frontmatter-standard-valid.d.ts.map

package/dist/src/unstable/lint/catalog/skill/frontmatter-standard-valid.js

@@ -0,0 +1,61 @@
+/**
+ * `skill/frontmatter-standard-valid` — SKILL.md metadata conforms to the
+ * pinned Agent Skills specification and reference validator.
+ *
+ * Parsing failures are owned by `skill/frontmatter-parseable`; this rule
+ * returns no findings until the frontmatter is a YAML mapping.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import YAML from "yaml";
+import { validateSkillFrontmatter } from "../../../content/skill-content.js";
+const RULE_ID = "skill/frontmatter-standard-valid";
+const SKILL_MD = "SKILL.md";
+const decoder = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true });
+const parseFrontmatterMapping = (content) => {
+    if (!content.startsWith("---"))
+        return undefined;
+    const openingEnd = content.indexOf("\n");
+    if (openingEnd === -1)
+        return undefined;
+    const closingStart = content.indexOf("\n---", openingEnd);
+    if (closingStart === -1)
+        return undefined;
+    try {
+        const parsed = YAML.parse(content.slice(openingEnd + 1, closingStart));
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const finding = (message) => ({
+    kind: "advisory",
+    ruleId: RULE_ID,
+    severity: "error",
+    message,
+    location: { file: SKILL_MD, line: 1 },
+});
+export const frontmatterStandardValidRule = {
+    id: RULE_ID,
+    description: "SKILL.md metadata conforms to the pinned Agent Skills standard.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => Effect.gen(function* () {
+        const exists = yield* context.files.exists(SKILL_MD);
+        if (!exists)
+            return [];
+        const content = yield* context.files.readBytes(SKILL_MD).pipe(Effect.map((bytes) => decoder.decode(bytes)), Effect.catch(() => Effect.succeed(undefined)));
+        if (content === undefined)
+            return [];
+        const parsed = parseFrontmatterMapping(content);
+        if (parsed === undefined)
+            return [];
+        const validation = validateSkillFrontmatter(parsed, context.subject.expectedName);
+        return validation.valid ? [] : validation.errors.map(finding);
+    }),
+};
+//# sourceMappingURL=frontmatter-standard-valid.js.map