@agentxm/registry-protocol 0.28.4-bootstrap.0

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2025-2026 AgentXM, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @agentxm/registry-protocol
+
+The AgentXM Registry wire contracts and the contract-level publication
+validation rules that the AXM client and the Registry implementation must
+interpret identically: request and response schemas, publication and
+deprecation views, suggested-action error vocabulary, extension content
+parsing, and publish lint rules.
+
+Every export lives under an explicit `./unstable/*` subpath: the surface is
+unsupported and may change in any release. Ordinary users should use the
+[`axm` CLI](https://axm.sh) instead.
+
+FSL-1.1-MIT © 2025-2026 AgentXM, Inc.

package/dist/src/unstable/content/agent-skills-standard.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Agent Skills conformance pin.
+ *
+ * AXM validates and materializes agent-facing skill directories against this
+ * exact upstream revision. Bumping the revision requires reviewing both the
+ * specification and `skills-ref` behavior, then updating conformance tests.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const AGENT_SKILLS_STANDARD_REVISION = "217be548739f21d6008915c29aefe320ea1a90af";
+export declare const AGENT_SKILLS_SPECIFICATION_URL = "https://github.com/agentskills/agentskills/blob/217be548739f21d6008915c29aefe320ea1a90af/docs/specification.mdx";
+export declare const AGENT_SKILLS_REFERENCE_VALIDATOR_URL = "https://github.com/agentskills/agentskills/tree/217be548739f21d6008915c29aefe320ea1a90af/skills-ref";
+export declare const AGENT_SKILLS_FRONTMATTER_FIELDS: readonly ["name", "description", "license", "compatibility", "metadata", "allowed-tools"];
+export declare const AGENT_SKILLS_NAME_MAX_LENGTH = 64;
+export declare const AGENT_SKILLS_DESCRIPTION_MAX_LENGTH = 1024;
+export declare const AGENT_SKILLS_COMPATIBILITY_MAX_LENGTH = 500;
+//# sourceMappingURL=agent-skills-standard.d.ts.map

package/dist/src/unstable/content/agent-skills-standard.js

@@ -0,0 +1,24 @@
+/**
+ * Agent Skills conformance pin.
+ *
+ * AXM validates and materializes agent-facing skill directories against this
+ * exact upstream revision. Bumping the revision requires reviewing both the
+ * specification and `skills-ref` behavior, then updating conformance tests.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const AGENT_SKILLS_STANDARD_REVISION = "217be548739f21d6008915c29aefe320ea1a90af";
+export const AGENT_SKILLS_SPECIFICATION_URL = `https://github.com/agentskills/agentskills/blob/${AGENT_SKILLS_STANDARD_REVISION}/docs/specification.mdx`;
+export const AGENT_SKILLS_REFERENCE_VALIDATOR_URL = `https://github.com/agentskills/agentskills/tree/${AGENT_SKILLS_STANDARD_REVISION}/skills-ref`;
+export const AGENT_SKILLS_FRONTMATTER_FIELDS = [
+    "name",
+    "description",
+    "license",
+    "compatibility",
+    "metadata",
+    "allowed-tools",
+];
+export const AGENT_SKILLS_NAME_MAX_LENGTH = 64;
+export const AGENT_SKILLS_DESCRIPTION_MAX_LENGTH = 1024;
+export const AGENT_SKILLS_COMPATIBILITY_MAX_LENGTH = 500;
+//# sourceMappingURL=agent-skills-standard.js.map

package/dist/src/unstable/content/frontmatter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Generic YAML frontmatter parser.
+ *
+ * Parses content that may begin with a YAML frontmatter block delimited
+ * by `---`. Returns the parsed frontmatter as `unknown` so each consumer
+ * can apply its own Schema validation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+/**
+ * Result of parsing frontmatter from content.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface FrontmatterResult {
+    /** Parsed YAML frontmatter, or undefined if no frontmatter block was found. */
+    readonly frontmatter: unknown;
+    /** Content body after the frontmatter block, or full content if no frontmatter. */
+    readonly body: string;
+}
+declare const FrontmatterParseFailure_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "FrontmatterParseFailure";
+} & Readonly<A>;
+/** Bounded, document-relative failure from parsing a YAML frontmatter block. */
+export declare class FrontmatterParseFailure extends FrontmatterParseFailure_base<{
+    readonly reason: string;
+    readonly line?: number;
+    readonly column?: number;
+}> {
+}
+export declare const FRONTMATTER_PARSE_FALLBACK_REASON = "YAML frontmatter could not be parsed";
+/** Normalize a foreign YAML failure without retaining its raw cause or parser code. */
+export declare const normalizeFrontmatterParseFailure: (error: unknown, documentLineOffset: number) => FrontmatterParseFailure;
+/**
+ * Parse frontmatter from content synchronously.
+ *
+ * Throws on malformed YAML. Use `parseFrontmatterEffect` for full error channel.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const parseFrontmatterSync: (content: string) => FrontmatterResult;
+/**
+ * Parse frontmatter from content as an Effect.
+ *
+ * Returns `FrontmatterParseFailure` in the error channel for malformed YAML.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const parseFrontmatterEffect: (content: string) => Effect.Effect<FrontmatterResult, FrontmatterParseFailure>;
+export {};
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/src/unstable/content/frontmatter.js

@@ -0,0 +1,115 @@
+/**
+ * Generic YAML frontmatter parser.
+ *
+ * Parses content that may begin with a YAML frontmatter block delimited
+ * by `---`. Returns the parsed frontmatter as `unknown` so each consumer
+ * can apply its own Schema validation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import YAML, { YAMLParseError } from "yaml";
+/** Bounded, document-relative failure from parsing a YAML frontmatter block. */
+export class FrontmatterParseFailure extends Data.TaggedError("FrontmatterParseFailure") {
+}
+const FRONTMATTER_DELIMITER = "---";
+export const FRONTMATTER_PARSE_FALLBACK_REASON = "YAML frontmatter could not be parsed";
+const FRONTMATTER_PARSE_REASON_MAX_CODE_POINTS = 256;
+const boundedReason = (reason) => {
+    const codePoints = Array.from(reason);
+    if (codePoints.length <= FRONTMATTER_PARSE_REASON_MAX_CODE_POINTS)
+        return reason;
+    return `${codePoints.slice(0, FRONTMATTER_PARSE_REASON_MAX_CODE_POINTS - 1).join("")}…`;
+};
+const parserReason = (error) => {
+    const firstLine = error.message.split(/\r?\n/, 1)[0]?.trim() ?? "";
+    const withoutLocation = firstLine
+        .replace(/\s+at line \d+, column \d+:?$/, "")
+        .replace(/^Missing closing ["']quote$/, "Missing closing quote")
+        .trim();
+    return boundedReason(withoutLocation || FRONTMATTER_PARSE_FALLBACK_REASON);
+};
+/** Normalize a foreign YAML failure without retaining its raw cause or parser code. */
+export const normalizeFrontmatterParseFailure = (error, documentLineOffset) => {
+    if (!(error instanceof YAMLParseError)) {
+        return new FrontmatterParseFailure({ reason: FRONTMATTER_PARSE_FALLBACK_REASON });
+    }
+    const position = error.linePos?.[0];
+    if (position === undefined || !Number.isSafeInteger(position.line) || position.line < 1) {
+        return new FrontmatterParseFailure({ reason: parserReason(error) });
+    }
+    const line = position.line + documentLineOffset;
+    const column = Number.isSafeInteger(position.col) && position.col > 0 ? position.col : undefined;
+    return new FrontmatterParseFailure({
+        reason: parserReason(error),
+        line,
+        ...(column === undefined ? {} : { column }),
+    });
+};
+/**
+ * Find the frontmatter boundaries in content.
+ * Returns [endOfOpening, startOfClosing] indices, or undefined if no frontmatter.
+ */
+const findFrontmatterBoundaries = (content) => {
+    if (!content.startsWith(FRONTMATTER_DELIMITER)) {
+        return undefined;
+    }
+    const afterOpening = content.indexOf("\n");
+    if (afterOpening === -1) {
+        return undefined;
+    }
+    const closingIndex = content.indexOf(`\n${FRONTMATTER_DELIMITER}`, afterOpening);
+    if (closingIndex === -1) {
+        return undefined;
+    }
+    const closingEnd = closingIndex + 1 + FRONTMATTER_DELIMITER.length;
+    const bodyStart = content.startsWith("\r\n", closingEnd)
+        ? closingEnd + 2
+        : content[closingEnd] === "\n"
+            ? closingEnd + 1
+            : closingEnd;
+    return {
+        yamlStart: afterOpening + 1,
+        bodyStart,
+    };
+};
+/**
+ * Parse frontmatter from content synchronously.
+ *
+ * Throws on malformed YAML. Use `parseFrontmatterEffect` for full error channel.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const parseFrontmatterSync = (content) => {
+    const boundaries = findFrontmatterBoundaries(content);
+    if (boundaries === undefined) {
+        return { frontmatter: undefined, body: content };
+    }
+    const yamlContent = content.slice(boundaries.yamlStart, boundaries.bodyStart).split("---")[0];
+    const frontmatter = (() => {
+        try {
+            return YAML.parse(yamlContent ?? "");
+        }
+        catch (error) {
+            const documentLineOffset = content.slice(0, boundaries.yamlStart).split("\n").length - 1;
+            throw normalizeFrontmatterParseFailure(error, documentLineOffset);
+        }
+    })();
+    const body = content.slice(boundaries.bodyStart);
+    return { frontmatter: frontmatter ?? undefined, body };
+};
+/**
+ * Parse frontmatter from content as an Effect.
+ *
+ * Returns `FrontmatterParseFailure` in the error channel for malformed YAML.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const parseFrontmatterEffect = (content) => Effect.try({
+    try: () => parseFrontmatterSync(content),
+    catch: (error) => error instanceof FrontmatterParseFailure
+        ? error
+        : new FrontmatterParseFailure({ reason: FRONTMATTER_PARSE_FALLBACK_REASON }),
+});
+//# sourceMappingURL=frontmatter.js.map

package/dist/src/unstable/content/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Area barrel for the package public surface.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { AGENT_SKILLS_COMPATIBILITY_MAX_LENGTH, AGENT_SKILLS_DESCRIPTION_MAX_LENGTH, AGENT_SKILLS_FRONTMATTER_FIELDS, AGENT_SKILLS_NAME_MAX_LENGTH, AGENT_SKILLS_REFERENCE_VALIDATOR_URL, AGENT_SKILLS_SPECIFICATION_URL, AGENT_SKILLS_STANDARD_REVISION, } from "./agent-skills-standard.js";
+export { FrontmatterParseFailure, type FrontmatterResult, parseFrontmatterEffect, parseFrontmatterSync, } from "./frontmatter.js";
+export { type SkillFrontmatter, SkillFrontmatterSchema, type SkillFrontmatterValidation, parseSkillMd, validateSkillFrontmatter, } from "./skill-content.js";
+export { type Skill } from "./skill-types.js";
+export { type SubagentAgentOverrides, type SubagentContentResult, parseSubagentMd, } from "./subagent-content.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/unstable/content/index.js

@@ -0,0 +1,11 @@
+/**
+ * Area barrel for the package public surface.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { AGENT_SKILLS_COMPATIBILITY_MAX_LENGTH, AGENT_SKILLS_DESCRIPTION_MAX_LENGTH, AGENT_SKILLS_FRONTMATTER_FIELDS, AGENT_SKILLS_NAME_MAX_LENGTH, AGENT_SKILLS_REFERENCE_VALIDATOR_URL, AGENT_SKILLS_SPECIFICATION_URL, AGENT_SKILLS_STANDARD_REVISION, } from "./agent-skills-standard.js";
+export { FrontmatterParseFailure, parseFrontmatterEffect, parseFrontmatterSync, } from "./frontmatter.js";
+export { SkillFrontmatterSchema, parseSkillMd, validateSkillFrontmatter, } from "./skill-content.js";
+export {} from "./skill-types.js";
+export { parseSubagentMd, } from "./subagent-content.js";
+//# sourceMappingURL=index.js.map

package/dist/src/unstable/content/skill-content.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Skill content file module for SKILL.md parsing and frontmatter schemas.
+ *
+ * Defines the frontmatter schema for SKILL.md files and a parser that
+ * combines the shared frontmatter utility with skill-specific validation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import type { Skill } from "./skill-types.js";
+/**
+ * Schema for SKILL.md frontmatter fields.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillFrontmatterSchema: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.String;
+    readonly license: Schema.optionalKey<Schema.String>;
+    readonly compatibility: Schema.optionalKey<Schema.String>;
+    readonly metadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly "allowed-tools": Schema.optionalKey<Schema.String>;
+}>;
+export type SkillFrontmatter = Schema.Schema.Type<typeof SkillFrontmatterSchema>;
+export type SkillFrontmatterValidation = {
+    readonly valid: true;
+    readonly frontmatter: SkillFrontmatter;
+} | {
+    readonly valid: false;
+    readonly errors: ReadonlyArray<string>;
+};
+/** Validate parsed YAML against the pinned Agent Skills metadata contract. */
+export declare const validateSkillFrontmatter: (input: unknown, expectedDirectoryName?: string) => SkillFrontmatterValidation;
+/**
+ * Parse a SKILL.md file's content and extract skill metadata from frontmatter.
+ *
+ * Returns `Option.some(Skill)` when the file has valid YAML frontmatter with
+ * non-empty `name` and `description` fields. Returns `Option.none()` for any
+ * invalid input: missing frontmatter, invalid YAML, or missing/empty required fields.
+ */
+export declare const parseSkillMd: (content: string, expectedDirectoryName?: string) => Option.Option<Skill>;
+//# sourceMappingURL=skill-content.d.ts.map

package/dist/src/unstable/content/skill-content.js

@@ -0,0 +1,184 @@
+/**
+ * Skill content file module for SKILL.md parsing and frontmatter schemas.
+ *
+ * Defines the frontmatter schema for SKILL.md files and a parser that
+ * combines the shared frontmatter utility with skill-specific validation.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { parseFrontmatterSync } from "./frontmatter.js";
+import { AGENT_SKILLS_COMPATIBILITY_MAX_LENGTH, AGENT_SKILLS_DESCRIPTION_MAX_LENGTH, AGENT_SKILLS_FRONTMATTER_FIELDS, AGENT_SKILLS_NAME_MAX_LENGTH, } from "./agent-skills-standard.js";
+const NonEmptyTrimmedStringSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((input) => input.trim().length > 0 ? undefined : "Expected a non-empty string")));
+const BoundedNonEmptyStringSchema = (maximumLength) => NonEmptyTrimmedStringSchema.pipe(Schema.check(Schema.makeFilter((input) => [...input].length <= maximumLength
+    ? undefined
+    : `Expected at most ${maximumLength} characters`)));
+const SkillNameSchema = BoundedNonEmptyStringSchema(AGENT_SKILLS_NAME_MAX_LENGTH).pipe(Schema.check(Schema.makeFilter((input) => {
+    const normalized = input.trim().normalize("NFKC");
+    if (normalized !== normalized.toLowerCase())
+        return "Skill name must be lowercase";
+    if (normalized.startsWith("-") || normalized.endsWith("-")) {
+        return "Skill name cannot start or end with a hyphen";
+    }
+    if (normalized.includes("--"))
+        return "Skill name cannot contain consecutive hyphens";
+    return [...normalized].every((character) => /[\p{L}\p{N}-]/u.test(character))
+        ? undefined
+        : "Skill name may contain only Unicode letters, numbers, and hyphens";
+})));
+const AllowedToolsSchema = NonEmptyTrimmedStringSchema.pipe(Schema.check(Schema.makeFilter((input) => /^\S+(?: \S+)*$/u.test(input) ? undefined : "Allowed tools must be a space-delimited string")));
+/**
+ * Schema for SKILL.md frontmatter fields.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const SkillFrontmatterSchema = Schema.Struct({
+    name: SkillNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "skill name is required in SKILL.md frontmatter" })),
+    description: BoundedNonEmptyStringSchema(AGENT_SKILLS_DESCRIPTION_MAX_LENGTH).pipe(Schema.annotateKey({
+        messageMissingKey: "skill description is required in SKILL.md frontmatter",
+    })),
+    license: Schema.optionalKey(Schema.String),
+    compatibility: Schema.optionalKey(BoundedNonEmptyStringSchema(AGENT_SKILLS_COMPATIBILITY_MAX_LENGTH)),
+    metadata: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+    "allowed-tools": Schema.optionalKey(AllowedToolsSchema),
+}).annotate({
+    identifier: "SkillFrontmatter",
+    title: "Skill Frontmatter",
+    description: "Agent Skills standard metadata at the top of a SKILL.md file.",
+});
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const allowedFrontmatterFields = new Set(AGENT_SKILLS_FRONTMATTER_FIELDS);
+/** Validate parsed YAML against the pinned Agent Skills metadata contract. */
+export const validateSkillFrontmatter = (input, expectedDirectoryName) => {
+    if (!isRecord(input)) {
+        return { valid: false, errors: ["SKILL.md frontmatter must be a YAML mapping"] };
+    }
+    const errors = [];
+    const unexpected = Object.keys(input)
+        .filter((key) => !allowedFrontmatterFields.has(key))
+        .sort();
+    if (unexpected.length > 0) {
+        errors.push(`Unexpected frontmatter fields: ${unexpected.join(", ")}`);
+    }
+    const nameValue = input["name"];
+    let normalizedName;
+    if (typeof nameValue !== "string" || nameValue.trim().length === 0) {
+        errors.push("Field 'name' must be a non-empty string");
+    }
+    else {
+        normalizedName = nameValue.trim().normalize("NFKC");
+        if ([...normalizedName].length > AGENT_SKILLS_NAME_MAX_LENGTH) {
+            errors.push(`Skill name exceeds ${AGENT_SKILLS_NAME_MAX_LENGTH} character limit`);
+        }
+        if (normalizedName !== normalizedName.toLowerCase()) {
+            errors.push("Skill name must be lowercase");
+        }
+        if (normalizedName.startsWith("-") || normalizedName.endsWith("-")) {
+            errors.push("Skill name cannot start or end with a hyphen");
+        }
+        if (normalizedName.includes("--")) {
+            errors.push("Skill name cannot contain consecutive hyphens");
+        }
+        if (![...normalizedName].every((character) => /[\p{L}\p{N}-]/u.test(character))) {
+            errors.push("Skill name may contain only Unicode letters, numbers, and hyphens");
+        }
+        if (expectedDirectoryName !== undefined &&
+            expectedDirectoryName.normalize("NFKC") !== normalizedName) {
+            errors.push(`Directory name '${expectedDirectoryName}' must match skill name '${normalizedName}'`);
+        }
+    }
+    const descriptionValue = input["description"];
+    if (typeof descriptionValue !== "string" || descriptionValue.trim().length === 0) {
+        errors.push("Field 'description' must be a non-empty string");
+    }
+    else if ([...descriptionValue].length > AGENT_SKILLS_DESCRIPTION_MAX_LENGTH) {
+        errors.push(`Description exceeds ${AGENT_SKILLS_DESCRIPTION_MAX_LENGTH} character limit`);
+    }
+    const licenseValue = input["license"];
+    if (licenseValue !== undefined && typeof licenseValue !== "string") {
+        errors.push("Field 'license' must be a string");
+    }
+    const compatibilityValue = input["compatibility"];
+    if (compatibilityValue !== undefined) {
+        if (typeof compatibilityValue !== "string" || compatibilityValue.trim().length === 0) {
+            errors.push("Field 'compatibility' must be a non-empty string");
+        }
+        else if ([...compatibilityValue].length > AGENT_SKILLS_COMPATIBILITY_MAX_LENGTH) {
+            errors.push(`Compatibility exceeds ${AGENT_SKILLS_COMPATIBILITY_MAX_LENGTH} character limit`);
+        }
+    }
+    const metadataValue = input["metadata"];
+    const metadata = {};
+    if (metadataValue !== undefined) {
+        if (!isRecord(metadataValue)) {
+            errors.push("Field 'metadata' must be a mapping from strings to strings");
+        }
+        else {
+            for (const [key, value] of Object.entries(metadataValue)) {
+                if (typeof value !== "string") {
+                    errors.push(`Metadata value for '${key}' must be a string`);
+                }
+                else {
+                    metadata[key] = value;
+                }
+            }
+        }
+    }
+    const allowedToolsValue = input["allowed-tools"];
+    if (allowedToolsValue !== undefined) {
+        if (typeof allowedToolsValue !== "string" || !/^\S+(?: \S+)*$/u.test(allowedToolsValue)) {
+            errors.push("Field 'allowed-tools' must be a non-empty space-delimited string");
+        }
+    }
+    if (errors.length > 0 || normalizedName === undefined || typeof descriptionValue !== "string") {
+        return { valid: false, errors };
+    }
+    return {
+        valid: true,
+        frontmatter: {
+            name: normalizedName,
+            description: descriptionValue,
+            ...(licenseValue !== undefined && typeof licenseValue === "string"
+                ? { license: licenseValue }
+                : {}),
+            ...(compatibilityValue !== undefined && typeof compatibilityValue === "string"
+                ? { compatibility: compatibilityValue }
+                : {}),
+            ...(metadataValue !== undefined ? { metadata } : {}),
+            ...(allowedToolsValue !== undefined && typeof allowedToolsValue === "string"
+                ? { "allowed-tools": allowedToolsValue }
+                : {}),
+        },
+    };
+};
+/**
+ * Parse a SKILL.md file's content and extract skill metadata from frontmatter.
+ *
+ * Returns `Option.some(Skill)` when the file has valid YAML frontmatter with
+ * non-empty `name` and `description` fields. Returns `Option.none()` for any
+ * invalid input: missing frontmatter, invalid YAML, or missing/empty required fields.
+ */
+export const parseSkillMd = (content, expectedDirectoryName) => {
+    try {
+        const parsed = parseFrontmatterSync(content);
+        if (parsed.frontmatter === undefined) {
+            return Option.none();
+        }
+        const validation = validateSkillFrontmatter(parsed.frontmatter, expectedDirectoryName);
+        if (!validation.valid) {
+            return Option.none();
+        }
+        const frontmatter = validation.frontmatter;
+        return Option.some({
+            name: frontmatter.name,
+            description: frontmatter.description,
+            metadata: frontmatter.metadata === undefined ? Option.none() : Option.some(frontmatter.metadata),
+        });
+    }
+    catch {
+        // Invalid YAML or other parsing errors — silently skip
+        return Option.none();
+    }
+};
+//# sourceMappingURL=skill-content.js.map

package/dist/src/unstable/content/skill-types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Core domain types for skills management.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option";
+import * as Record from "effect/Record";
+/**
+ * Represents a discovered skill.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface Skill {
+    /** Unique name of the skill */
+    readonly name: string;
+    /** Description of the skill */
+    readonly description: string;
+    /** Optional metadata from SKILL.md frontmatter */
+    readonly metadata: Option.Option<Record.ReadonlyRecord<string, string>>;
+}
+//# sourceMappingURL=skill-types.d.ts.map

package/dist/src/unstable/content/skill-types.js

@@ -0,0 +1,9 @@
+/**
+ * Core domain types for skills management.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option";
+import * as Record from "effect/Record";
+//# sourceMappingURL=skill-types.js.map