@agentxm/extension-model 0.28.4-bootstrap.0

package/dist/src/unstable/extensions/refs/ref-base.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Base types for extension references.
+ *
+ * Defines the foundational type hierarchy used by all extension types.
+ * Per-type concrete refs live in their respective feature folders
+ * (skills/refs.ts, mcps/refs.ts, etc.).
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { ExtensionName, ExtensionType } from "../common.js";
+import type * as Option from "effect/Option";
+import type * as Record from "effect/Record";
+import type { RefType, Source } from "../../sources/types.js";
+import type { ExtensionDependencyConstraintMap } from "../common.js";
+import type { Version } from "../../version-constraints/version-constraints.js";
+import type { Handle } from "../handle.js";
+import type { PackageUrlParts } from "../../packaging/package-url.js";
+import type { WorkspaceScope } from "../../workspace-scope.js";
+import type { SourceHash } from "../../sources/source-hash.js";
+import type { DeprecationView } from "../deprecation.js";
+/** Ref details for git-hosted sources (GitHub, GitLab, Bitbucket, AzureRepos, Git). @experimental */
+export interface GitHostedRefDetails {
+    /** Publisher identity declared by the resolved package manifest. */
+    readonly owner: Handle;
+    /** Package identity declared by the resolved package manifest. */
+    readonly name: ExtensionName;
+    /** file:// URL to cloned directory */
+    readonly location: string;
+    /** Repository-relative directory selected for this extension */
+    readonly sourcePath?: string;
+    /** Git tree SHA for integrity verification */
+    readonly gitTreeSha: string;
+    /** Immutable commit checked out while resolving this ref. */
+    readonly gitCommitSha: string;
+}
+/** Ref details for registry sources. @experimental */
+export interface RegistryRefDetails {
+    /** Registry owner that owns the published extension */
+    readonly owner: Handle;
+    /** Immutable registry publisher epoch. */
+    readonly publisherBindingId: string;
+    /**
+     * Registry package name — the identifier used for registry operations (fetch, version resolution).
+     * This may differ from the extension-specific display name (e.g., skill.name, pack.name,
+     * server.name) which is the user-facing name parsed from the extension's manifest.
+     */
+    readonly name: ExtensionName;
+    /** Resolved semver version */
+    readonly version: Version;
+    /** SRI integrity string in `sha512-<base64>` format. None for synthetic refs from publish. */
+    readonly integrity: Option.Option<string>;
+    /** Package URLs this extension is designed to work with, from registry metadata. Empty when absent. */
+    readonly packages: ReadonlyArray<PackageUrlParts>;
+    /** Structured Registry lifecycle evidence captured at resolution time. */
+    readonly deprecation?: DeprecationView;
+    /** Lifecycle notices that must be shown before an exact historical install. */
+    readonly lifecycleWarnings?: ReadonlyArray<string>;
+}
+/** Ref details for local filesystem sources. @experimental */
+export interface LocalRefDetails {
+    /** Publisher identity declared by the resolved package manifest. */
+    readonly owner: Handle;
+    /** Package identity declared by the resolved package manifest. */
+    readonly name: ExtensionName;
+    /** file:// URL to local directory */
+    readonly location: string;
+    /** Workspace-relative selected package directory when known. */
+    readonly sourcePath?: string;
+}
+/** Ref details for intrinsic workspace sources. @experimental */
+export interface WorkspaceRefDetails {
+    /** Owner declared by the workspace locator and manifest. */
+    readonly owner: Handle;
+    /** Package name declared by the workspace locator and manifest. */
+    readonly name: ExtensionName;
+    /** Manifest version; workspace locators never carry a version constraint. */
+    readonly version: Version;
+    /** Scope whose settings document declares the workspace source. */
+    readonly scope: WorkspaceScope;
+    /** Runtime-only canonical package location. Never persisted in the lockfile. */
+    readonly location: string;
+    /** Deterministic hash of the authoritative workspace package content. */
+    readonly sourceHash: SourceHash;
+}
+/** @experimental */
+export interface ExtensionRefBase<TExtensionType extends ExtensionType, TRefType extends RefType, TSource extends Source> {
+    readonly type: TExtensionType;
+    readonly refType: TRefType;
+    readonly source: TSource;
+}
+/** @experimental */
+export type SkillExtensionRefBase<TRefType extends RefType, TSource extends Source> = ExtensionRefBase<"skill", TRefType, TSource> & {
+    readonly skill: {
+        readonly name: ExtensionName;
+        readonly description: Option.Option<string>;
+        readonly metadata: Option.Option<Record.ReadonlyRecord<string, unknown>>;
+    };
+};
+/** @experimental */
+/** @experimental */
+export type McpServerExtensionRefBase<TRefType extends RefType, TSource extends Source> = ExtensionRefBase<"mcp-server", TRefType, TSource> & {
+    readonly server: {
+        readonly name: ExtensionName;
+    };
+};
+/** @experimental */
+export type SubagentExtensionRefBase<TRefType extends RefType, TSource extends Source> = ExtensionRefBase<"subagent", TRefType, TSource> & {
+    readonly subagent: {
+        readonly name: ExtensionName;
+        readonly description: Option.Option<string>;
+    };
+    /** Override platform capability degradation for this extension. */
+    readonly fallback?: "auto" | "none";
+};
+/** @experimental */
+/** @experimental */
+export type PackRefBase<TRefType extends RefType, TSource extends Source> = ExtensionRefBase<"pack", TRefType, TSource> & {
+    readonly owner: Handle;
+    readonly pack: {
+        readonly name: ExtensionName;
+        readonly dependencies: ExtensionDependencyConstraintMap;
+    };
+};
+//# sourceMappingURL=ref-base.d.ts.map

package/dist/src/unstable/extensions/refs/ref-base.js

@@ -0,0 +1,12 @@
+/**
+ * Base types for extension references.
+ *
+ * Defines the foundational type hierarchy used by all extension types.
+ * Per-type concrete refs live in their respective feature folders
+ * (skills/refs.ts, mcps/refs.ts, etc.).
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=ref-base.js.map

package/dist/src/unstable/extensions/refs/rule.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Concrete rule ref types.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { GitHostedRefDetails, LocalRefDetails, RegistryRefDetails, WorkspaceRefDetails } from "./ref-base.js";
+import type { ExtensionRefBase } from "./ref-base.js";
+import type { GitBasedSource, LocalSource, RegistrySource, WorkspaceSource } from "../../sources/types.js";
+import type { ExtensionName } from "../common.js";
+type RuleExtensionRefBase<TRefType, TSource> = ExtensionRefBase<"rule", Extract<TRefType, "git-hosted" | "registry" | "local" | "workspace">, Extract<TSource, GitBasedSource | RegistrySource | LocalSource | WorkspaceSource>> & {
+    readonly rule: {
+        readonly name: ExtensionName;
+    };
+};
+/** @experimental */
+export type GitHostedRuleRef = RuleExtensionRefBase<"git-hosted", GitBasedSource> & GitHostedRefDetails;
+/** @experimental */
+export type RegistryRuleRef = RuleExtensionRefBase<"registry", RegistrySource> & RegistryRefDetails;
+/** @experimental */
+export type LocalRuleRef = RuleExtensionRefBase<"local", LocalSource> & LocalRefDetails;
+/** @experimental */
+export type WorkspaceRuleRef = RuleExtensionRefBase<"workspace", WorkspaceSource> & WorkspaceRefDetails;
+/** @experimental */
+export type RuleExtensionRef = GitHostedRuleRef | RegistryRuleRef | LocalRuleRef | WorkspaceRuleRef;
+export {};
+//# sourceMappingURL=rule.d.ts.map

package/dist/src/unstable/extensions/refs/rule.js

@@ -0,0 +1,8 @@
+/**
+ * Concrete rule ref types.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=rule.js.map

package/dist/src/unstable/extensions/refs/skill.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Skill extension ref types.
+ *
+ * Concrete ref types for skill extensions, built on the shared
+ * ExtensionRefBase and ref detail interfaces.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { SkillExtensionRefBase, GitHostedRefDetails, RegistryRefDetails, LocalRefDetails, WorkspaceRefDetails } from "./ref-base.js";
+import type { GitBasedSource, RegistrySource, LocalSource, WorkspaceSource } from "../../sources/types.js";
+import type { Handle } from "../handle.js";
+type ExternalSkillRefDetails<TDetails extends GitHostedRefDetails | LocalRefDetails> = Omit<TDetails, "owner"> & {
+    readonly owner?: Handle;
+    readonly portable?: boolean;
+};
+/** @experimental */
+export type GitHostedSkillRef = SkillExtensionRefBase<"git-hosted", GitBasedSource> & ExternalSkillRefDetails<GitHostedRefDetails>;
+/** @experimental */
+export type RegistrySkillRef = SkillExtensionRefBase<"registry", RegistrySource> & RegistryRefDetails;
+/** @experimental */
+export type LocalSkillRef = SkillExtensionRefBase<"local", LocalSource> & ExternalSkillRefDetails<LocalRefDetails>;
+/** @experimental */
+export type WorkspaceSkillRef = SkillExtensionRefBase<"workspace", WorkspaceSource> & WorkspaceRefDetails;
+/** @experimental */
+export type SkillExtensionRef = GitHostedSkillRef | RegistrySkillRef | LocalSkillRef | WorkspaceSkillRef;
+export {};
+//# sourceMappingURL=skill.d.ts.map

package/dist/src/unstable/extensions/refs/skill.js

@@ -0,0 +1,11 @@
+/**
+ * Skill extension ref types.
+ *
+ * Concrete ref types for skill extensions, built on the shared
+ * ExtensionRefBase and ref detail interfaces.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=skill.js.map

package/dist/src/unstable/extensions/refs/subagent.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Concrete subagent extension ref types.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { SubagentExtensionRefBase, GitHostedRefDetails, RegistryRefDetails, LocalRefDetails, WorkspaceRefDetails } from "./ref-base.js";
+import type { GitBasedSource, RegistrySource, LocalSource, WorkspaceSource } from "../../sources/types.js";
+/** @experimental */
+export type GitHostedSubagentRef = SubagentExtensionRefBase<"git-hosted", GitBasedSource> & GitHostedRefDetails;
+/** @experimental */
+export type RegistrySubagentRef = SubagentExtensionRefBase<"registry", RegistrySource> & RegistryRefDetails;
+/** @experimental */
+export type LocalSubagentRef = SubagentExtensionRefBase<"local", LocalSource> & LocalRefDetails;
+/** @experimental */
+export type WorkspaceSubagentRef = SubagentExtensionRefBase<"workspace", WorkspaceSource> & WorkspaceRefDetails;
+/** @experimental */
+export type SubagentExtensionRef = GitHostedSubagentRef | RegistrySubagentRef | LocalSubagentRef | WorkspaceSubagentRef;
+//# sourceMappingURL=subagent.d.ts.map

package/dist/src/unstable/extensions/refs/subagent.js

@@ -0,0 +1,8 @@
+/**
+ * Concrete subagent extension ref types.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=subagent.js.map

package/dist/src/unstable/extensions/registry-source.d.ts

@@ -0,0 +1,37 @@
+import * as Schema from "effect/Schema";
+export declare const RegistrySourcePatternPartsSchema: Schema.Struct<{
+    readonly owner: Schema.brand<Schema.String, "Handle">;
+    readonly type: Schema.optional<Schema.Literals<readonly ("skills" | "mcps" | "subagents" | "rules" | "hooks" | "knowledge" | "packs")[]>>;
+    readonly name: Schema.optional<Schema.brand<Schema.NonEmptyString, "ExtensionName">>;
+    readonly versionRange: Schema.optional<Schema.brand<Schema.NonEmptyString, "VersionRange">>;
+}>;
+export type RegistrySourcePatternParts = Schema.Schema.Type<typeof RegistrySourcePatternPartsSchema>;
+export type SourceQualifiedRegistrySourcePatternParts = RegistrySourcePatternParts & {
+    readonly sourceName: string;
+};
+export declare const RegistrySourceRefPartsSchema: Schema.Struct<{
+    readonly owner: Schema.brand<Schema.String, "Handle">;
+    readonly type: Schema.Literals<readonly ("skills" | "mcps" | "subagents" | "rules" | "hooks" | "knowledge" | "packs")[]>;
+    readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+    readonly versionRange: Schema.optional<Schema.brand<Schema.NonEmptyString, "VersionRange">>;
+}>;
+export type RegistrySourceRefParts = Schema.Schema.Type<typeof RegistrySourceRefPartsSchema>;
+export declare const parseRegistrySourcePatternParts: (input: string) => RegistrySourcePatternParts | undefined;
+/** Parse a Registry locator, assigning unqualified input to the built-in agentxm source. */
+export declare const parseSourceQualifiedRegistrySourcePatternParts: (input: string) => SourceQualifiedRegistrySourcePatternParts | undefined;
+export declare const parseRegistrySourceRef: (input: string) => RegistrySourceRefParts | undefined;
+export declare const formatRegistrySourcePatternParts: (value: RegistrySourcePatternParts) => string;
+export declare const formatRegistrySourceRef: (value: RegistrySourceRefParts) => string;
+export declare const RegistrySourcePatternSchema: Schema.decodeTo<Schema.toType<Schema.Struct<{
+    readonly owner: Schema.brand<Schema.String, "Handle">;
+    readonly type: Schema.optional<Schema.Literals<readonly ("skills" | "mcps" | "subagents" | "rules" | "hooks" | "knowledge" | "packs")[]>>;
+    readonly name: Schema.optional<Schema.brand<Schema.NonEmptyString, "ExtensionName">>;
+    readonly versionRange: Schema.optional<Schema.brand<Schema.NonEmptyString, "VersionRange">>;
+}>>, Schema.String, never, never>;
+export declare const RegistrySourceRefSchema: Schema.decodeTo<Schema.toType<Schema.Struct<{
+    readonly owner: Schema.brand<Schema.String, "Handle">;
+    readonly type: Schema.Literals<readonly ("skills" | "mcps" | "subagents" | "rules" | "hooks" | "knowledge" | "packs")[]>;
+    readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+    readonly versionRange: Schema.optional<Schema.brand<Schema.NonEmptyString, "VersionRange">>;
+}>>, Schema.String, never, never>;
+//# sourceMappingURL=registry-source.d.ts.map

package/dist/src/unstable/extensions/registry-source.js

@@ -0,0 +1,158 @@
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+import { ExtensionNameSchema, ExtensionTypePluralSchema } from "./common.js";
+import { HandleSchema } from "./handle.js";
+import { VersionRangeSchema } from "../version-constraints/version-constraints.js";
+const invalidRegistrySourcePattern = (input) => `Expected registry source pattern in @handle, @handle/<plural-type>, or @handle/<plural-type>/<name>@<constraint> form, got: ${input}`;
+const invalidRegistrySourceRef = (input) => `Expected registry source ref in @handle/<plural-type>/<name>@<constraint> form, got: ${input}`;
+export const RegistrySourcePatternPartsSchema = Schema.Struct({
+    owner: HandleSchema,
+    type: Schema.optional(ExtensionTypePluralSchema),
+    name: Schema.optional(ExtensionNameSchema),
+    versionRange: Schema.optional(VersionRangeSchema),
+})
+    .pipe(Schema.check(Schema.makeFilter((value) => {
+    if (value.type === undefined) {
+        return value.name === undefined && value.versionRange === undefined
+            ? undefined
+            : "Registry source pattern cannot include name or versionRange without type";
+    }
+    if (value.name === undefined) {
+        return value.versionRange === undefined
+            ? undefined
+            : "Registry source pattern cannot include versionRange without name";
+    }
+    return undefined;
+})))
+    .annotate({
+    identifier: "RegistrySourcePatternParts",
+    title: "Registry Source Pattern",
+    description: "Structured registry source pattern: @handle, @handle/<type>, or @handle/<type>/<name>@<constraint>.",
+});
+export const RegistrySourceRefPartsSchema = Schema.Struct({
+    owner: HandleSchema,
+    type: ExtensionTypePluralSchema,
+    name: ExtensionNameSchema,
+    versionRange: Schema.optional(VersionRangeSchema),
+}).annotate({
+    identifier: "RegistrySourceRefParts",
+    title: "Registry Source Ref",
+    description: "Structured registry source ref: @handle/<type>/<name> with optional version constraint.",
+});
+const decodeRegistrySourcePatternParts = Schema.decodeUnknownResult(RegistrySourcePatternPartsSchema);
+const decodeRegistrySourceRefParts = Schema.decodeUnknownResult(RegistrySourceRefPartsSchema);
+const parseNameAndConstraintSegment = (segment) => {
+    const atIndex = segment.indexOf("@");
+    if (atIndex === 0) {
+        return undefined;
+    }
+    if (atIndex === -1) {
+        return { name: segment };
+    }
+    const name = segment.slice(0, atIndex);
+    const versionRange = segment.slice(atIndex + 1);
+    if (name.length === 0 || versionRange.length === 0) {
+        return undefined;
+    }
+    return { name, versionRange };
+};
+export const parseRegistrySourcePatternParts = (input) => {
+    if (!input.startsWith("@")) {
+        return undefined;
+    }
+    const segments = input.split("/");
+    if (segments.length < 1 || segments.length > 3) {
+        return undefined;
+    }
+    const owner = segments[0];
+    if (owner === undefined) {
+        return undefined;
+    }
+    let candidate;
+    if (segments.length === 1) {
+        candidate = { owner };
+    }
+    else if (segments.length === 2) {
+        const type = segments[1];
+        if (type !== undefined) {
+            candidate = { owner, type };
+        }
+    }
+    else {
+        const type = segments[1];
+        const third = segments[2];
+        if (type !== undefined && third !== undefined) {
+            const parsedName = parseNameAndConstraintSegment(third);
+            if (parsedName !== undefined) {
+                candidate = {
+                    owner,
+                    type,
+                    name: parsedName.name,
+                    versionRange: parsedName.versionRange,
+                };
+            }
+        }
+    }
+    if (candidate === undefined) {
+        return undefined;
+    }
+    const result = decodeRegistrySourcePatternParts(candidate);
+    return Result.isSuccess(result) ? result.success : undefined;
+};
+/** Parse a Registry locator, assigning unqualified input to the built-in agentxm source. */
+export const parseSourceQualifiedRegistrySourcePatternParts = (input) => {
+    const unqualified = parseRegistrySourcePatternParts(input);
+    if (unqualified !== undefined) {
+        return { ...unqualified, sourceName: "agentxm" };
+    }
+    const separator = input.indexOf(":");
+    if (separator <= 0)
+        return undefined;
+    const sourceName = input.slice(0, separator);
+    const qualified = parseRegistrySourcePatternParts(input.slice(separator + 1));
+    return qualified === undefined ? undefined : { ...qualified, sourceName };
+};
+export const parseRegistrySourceRef = (input) => {
+    const parsed = parseSourceQualifiedRegistrySourcePatternParts(input);
+    if (parsed?.type === undefined || parsed.name === undefined) {
+        return undefined;
+    }
+    const result = decodeRegistrySourceRefParts(parsed);
+    return Result.isSuccess(result) ? result.success : undefined;
+};
+export const formatRegistrySourcePatternParts = (value) => {
+    let output = value.owner;
+    if (value.type !== undefined) {
+        output += `/${value.type}`;
+    }
+    if (value.name !== undefined) {
+        output += `/${value.name}`;
+    }
+    if (value.versionRange !== undefined) {
+        output += `@${value.versionRange}`;
+    }
+    return output;
+};
+export const formatRegistrySourceRef = (value) => formatRegistrySourcePatternParts(value);
+export const RegistrySourcePatternSchema = Schema.String.pipe(Schema.decodeTo(Schema.toType(RegistrySourcePatternPartsSchema), SchemaTransformation.transformOrFail({
+    decode: (input) => {
+        const parsed = parseRegistrySourcePatternParts(input);
+        return parsed === undefined
+            ? Effect.fail(new SchemaIssue.Forbidden({ message: invalidRegistrySourcePattern(input) }, input))
+            : Effect.succeed(parsed);
+    },
+    encode: (value) => Effect.succeed(formatRegistrySourcePatternParts(value)),
+})));
+export const RegistrySourceRefSchema = Schema.String.pipe(Schema.decodeTo(Schema.toType(RegistrySourceRefPartsSchema), SchemaTransformation.transformOrFail({
+    decode: (input) => {
+        const parsed = parseRegistrySourceRef(input);
+        return parsed === undefined
+            ? Effect.fail(new SchemaIssue.Forbidden({ message: invalidRegistrySourceRef(input) }, input))
+            : Effect.succeed(parsed);
+    },
+    encode: (value) => Effect.succeed(formatRegistrySourceRef(value)),
+})));
+//# sourceMappingURL=registry-source.js.map

package/dist/src/unstable/extensions/release-age.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Release-age policy vocabulary consumed by source resolution ports.
+ *
+ * These are the pure evaluation, exemption, and evidence shapes a resolution
+ * request commits to. Record construction, maturity checks, and everything
+ * coupled to registry version entries stays in `@agentxm/registry-protocol`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type * as DateTime from "effect/DateTime";
+import type * as Duration from "effect/Duration";
+import type { ReleaseAgeExcludePattern } from "./fqn-pattern.js";
+export interface ScopedReleaseAgeExcludePattern {
+    readonly pattern: ReleaseAgeExcludePattern;
+    readonly scope: "project" | "user";
+}
+export interface ReleaseAgeEvaluation {
+    readonly minimumReleaseAge: Duration.Duration;
+    readonly evaluatedAt: DateTime.Utc;
+    readonly mode: "enforce" | "ignore";
+    readonly exclude?: ReadonlyArray<ScopedReleaseAgeExcludePattern>;
+    readonly grantedExemption?: ReleaseAgeExemption;
+}
+export type ReleaseAgeExemption = {
+    readonly bypassCause: "exclude";
+    readonly exemptionScope: "project" | "user";
+} | {
+    readonly bypassCause: "ignore-flag";
+};
+export interface ReleaseAgeEvidence {
+    readonly version: string;
+    readonly publishedAt: string;
+    readonly eligibleAt: string;
+    readonly minimumReleaseAgeSeconds: number;
+}
+//# sourceMappingURL=release-age.d.ts.map

package/dist/src/unstable/extensions/release-age.js

@@ -0,0 +1,11 @@
+/**
+ * Release-age policy vocabulary consumed by source resolution ports.
+ *
+ * These are the pure evaluation, exemption, and evidence shapes a resolution
+ * request commits to. Record construction, maturity checks, and everything
+ * coupled to registry version entries stays in `@agentxm/registry-protocol`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export {};
+//# sourceMappingURL=release-age.js.map

package/dist/src/unstable/extensions/universal-skills-dir.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Universal skills directory convention.
+ *
+ * The universal skills directory (`.agents/skills`) is a shared cross-agent
+ * convention used by multiple coding agents. Skills placed here are visible to
+ * every agent that opts in, rather than being scoped to a single agent's
+ * configuration directory.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+/**
+ * WorkspaceMutations-relative path of the universal skills directory.
+ */
+export declare const UNIVERSAL_SKILLS_DIR = ".agents/skills";
+/**
+ * First path segment of {@link UNIVERSAL_SKILLS_DIR}.
+ *
+ * Used by detection and lint logic to exclude the universal directory from
+ * agent-specific filesystem probes.
+ */
+export declare const UNIVERSAL_SKILLS_DIR_SEGMENT: string;
+/**
+ * Strips trailing path separators from a path string.
+ */
+export declare const stripTrailingSeparators: (p: string) => string;
+/**
+ * Returns `true` when `dir` is the workspace-relative universal skills
+ * directory path. Use for descriptor-level comparisons where paths are
+ * relative (e.g., `agent.skills.dir`).
+ *
+ * @see {@link isUniversalSkillsDir} for absolute resolved-path comparisons
+ * (e.g., after `resolveEffectiveSkillsDir`).
+ */
+export declare const isUniversalSkillsRelativeDir: (dir: string) => boolean;
+/**
+ * Resolve per-agent artifact presence when some agents share the universal
+ * skills directory. If any agent in `universalAgentIds` has the artifact,
+ * all agents in that set are treated as having it — because the directory
+ * is shared, one symlink/copy satisfies them all.
+ *
+ * Returns the input unchanged when `universalAgentIds` is empty.
+ */
+export declare const resolveUniversalDirPresence: <T extends {
+    readonly agentId: string;
+    readonly exists: boolean;
+}>(perAgent: ReadonlyArray<T>, universalAgentIds: ReadonlySet<string>) => ReadonlyArray<T>;
+/**
+ * Returns `true` when `resolvedDir` points to the universal skills directory
+ * (`<workspaceRoot>/.agents/skills`).
+ *
+ * Both paths are normalized by stripping trailing separators before comparison.
+ *
+ * Intended for comparing resolved absolute paths from `resolveEffectiveSkillsDir`.
+ * For descriptor-level relative paths, use {@link isUniversalSkillsRelativeDir}.
+ */
+export declare const isUniversalSkillsDir: (resolvedDir: string, workspaceRoot: string) => boolean;
+//# sourceMappingURL=universal-skills-dir.d.ts.map

package/dist/src/unstable/extensions/universal-skills-dir.js

@@ -0,0 +1,68 @@
+/**
+ * Universal skills directory convention.
+ *
+ * The universal skills directory (`.agents/skills`) is a shared cross-agent
+ * convention used by multiple coding agents. Skills placed here are visible to
+ * every agent that opts in, rather than being scoped to a single agent's
+ * configuration directory.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+/**
+ * WorkspaceMutations-relative path of the universal skills directory.
+ */
+export const UNIVERSAL_SKILLS_DIR = ".agents/skills";
+/**
+ * First path segment of {@link UNIVERSAL_SKILLS_DIR}.
+ *
+ * Used by detection and lint logic to exclude the universal directory from
+ * agent-specific filesystem probes.
+ */
+export const UNIVERSAL_SKILLS_DIR_SEGMENT = UNIVERSAL_SKILLS_DIR.split("/")[0] ?? "";
+/**
+ * Strips trailing path separators from a path string.
+ */
+export const stripTrailingSeparators = (p) => p.length > 1 ? p.replace(/[/\\]+$/, "") : p;
+/**
+ * Returns `true` when `dir` is the workspace-relative universal skills
+ * directory path. Use for descriptor-level comparisons where paths are
+ * relative (e.g., `agent.skills.dir`).
+ *
+ * @see {@link isUniversalSkillsDir} for absolute resolved-path comparisons
+ * (e.g., after `resolveEffectiveSkillsDir`).
+ */
+export const isUniversalSkillsRelativeDir = (dir) => dir === UNIVERSAL_SKILLS_DIR;
+/**
+ * Resolve per-agent artifact presence when some agents share the universal
+ * skills directory. If any agent in `universalAgentIds` has the artifact,
+ * all agents in that set are treated as having it — because the directory
+ * is shared, one symlink/copy satisfies them all.
+ *
+ * Returns the input unchanged when `universalAgentIds` is empty.
+ */
+export const resolveUniversalDirPresence = (perAgent, universalAgentIds) => {
+    if (universalAgentIds.size === 0) {
+        return perAgent;
+    }
+    const anyUniversalExists = perAgent.some((p) => p.exists && universalAgentIds.has(p.agentId));
+    if (!anyUniversalExists) {
+        return perAgent;
+    }
+    return perAgent.map((p) => (universalAgentIds.has(p.agentId) ? { ...p, exists: true } : p));
+};
+/**
+ * Returns `true` when `resolvedDir` points to the universal skills directory
+ * (`<workspaceRoot>/.agents/skills`).
+ *
+ * Both paths are normalized by stripping trailing separators before comparison.
+ *
+ * Intended for comparing resolved absolute paths from `resolveEffectiveSkillsDir`.
+ * For descriptor-level relative paths, use {@link isUniversalSkillsRelativeDir}.
+ */
+export const isUniversalSkillsDir = (resolvedDir, workspaceRoot) => {
+    const sep = "/";
+    const expected = stripTrailingSeparators(`${stripTrailingSeparators(workspaceRoot)}${sep}${UNIVERSAL_SKILLS_DIR}`);
+    return stripTrailingSeparators(resolvedDir) === expected;
+};
+//# sourceMappingURL=universal-skills-dir.js.map