@agentxm/extension-content 0.42.0 → 0.42.1

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

@@ -38,12 +38,18 @@ export interface ExtractedSkillMetadata {
     readonly frontmatter?: Readonly<Record<string, unknown>>;
 }
 /**
- * Read external metadata without applying AXM's authoring contract. The source
+ * Read descriptive metadata without imposing a conformance gate. The source
  * remains authoritative: unknown fields, display names and metadata values are
  * retained as declared. Missing or malformed metadata does not make an explicit
  * SKILL.md path unavailable to acquisition.
  */
 export declare const extractSkillMetadata: (content: string) => ExtractedSkillMetadata;
+/**
+ * Choose a native directory component without changing the skill declaration.
+ * The fallback is the caller's already validated source/package identity, never
+ * the physical content directory (which may be named src in an AXM envelope).
+ */
+export declare const skillDirectoryName: (declaredName: string | undefined, fallback: string) => string;
 /** Validate parsed YAML against the pinned Agent Skills metadata contract. */
 export declare const validateSkillFrontmatter: (input: unknown, expectedDirectoryName?: string) => SkillFrontmatterValidation;
 /**

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

@@ -50,7 +50,7 @@ export const SkillFrontmatterSchema = Schema.Struct({
 const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 const allowedFrontmatterFields = new Set(AGENT_SKILLS_FRONTMATTER_FIELDS);
 /**
- * Read external metadata without applying AXM's authoring contract. The source
+ * Read descriptive metadata without imposing a conformance gate. The source
  * remains authoritative: unknown fields, display names and metadata values are
  * retained as declared. Missing or malformed metadata does not make an explicit
  * SKILL.md path unavailable to acquisition.
@@ -73,6 +73,26 @@ export const extractSkillMetadata = (content) => {
         return {};
     }
 };
+/**
+ * Choose a native directory component without changing the skill declaration.
+ * The fallback is the caller's already validated source/package identity, never
+ * the physical content directory (which may be named src in an AXM envelope).
+ */
+export const skillDirectoryName = (declaredName, fallback) => {
+    const reserved = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu;
+    if (declaredName === undefined ||
+        declaredName.length === 0 ||
+        declaredName.trim() !== declaredName ||
+        declaredName === "." ||
+        declaredName === ".." ||
+        declaredName.endsWith(".") ||
+        /[<>:"/\\|?*]/u.test(declaredName) ||
+        [...declaredName].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127) ||
+        reserved.test(declaredName) ||
+        new TextEncoder().encode(declaredName).length > 255)
+        return reserved.test(fallback) ? `skill-${fallback}` : fallback;
+    return declaredName;
+};
 /** Validate parsed YAML against the pinned Agent Skills metadata contract. */
 export const validateSkillFrontmatter = (input, expectedDirectoryName) => {
     if (!isRecord(input)) {

package/dist/src/index.d.ts

@@ -12,7 +12,7 @@
  */
 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 "./content/agent-skills-standard.js";
 export { FRONTMATTER_PARSE_FALLBACK_REASON, FrontmatterParseFailure, type FrontmatterResult, parseFrontmatterEffect, parseFrontmatterSync, } from "./content/frontmatter.js";
-export { type ExtractedSkillMetadata, type SkillFrontmatter, SkillFrontmatterSchema, type SkillFrontmatterValidation, parseSkillMd, extractSkillMetadata, validateSkillFrontmatter, } from "./content/skill-content.js";
+export { type ExtractedSkillMetadata, type SkillFrontmatter, SkillFrontmatterSchema, type SkillFrontmatterValidation, parseSkillMd, extractSkillMetadata, skillDirectoryName, validateSkillFrontmatter, } from "./content/skill-content.js";
 export { type Skill } from "./content/skill-types.js";
 export { type DecodedSubagentPackage, type NativeSubagentContent, type ResolvedSubagentImplementation, type SelectedSubagentImplementation, SubagentContentError, loadSubagentPackage, nativeSubagentFormat, parseNativeSubagent, readSubagentPackage, selectSubagentImplementation, } from "./content/subagent-content.js";
 export { ArchiveGuardrailError, type ArchiveGuardrailLimits, ZIP_LOCAL_SIGNATURE, type ZipEntry, checkForbiddenSourceEntries, defaultReadEntry, parseZipCentralDirectory, validateArchive, } from "./packaging/archive-guardrails.js";

package/dist/src/index.js

@@ -12,7 +12,7 @@
  */
 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 "./content/agent-skills-standard.js";
 export { FRONTMATTER_PARSE_FALLBACK_REASON, FrontmatterParseFailure, parseFrontmatterEffect, parseFrontmatterSync, } from "./content/frontmatter.js";
-export { SkillFrontmatterSchema, parseSkillMd, extractSkillMetadata, validateSkillFrontmatter, } from "./content/skill-content.js";
+export { SkillFrontmatterSchema, parseSkillMd, extractSkillMetadata, skillDirectoryName, validateSkillFrontmatter, } from "./content/skill-content.js";
 export {} from "./content/skill-types.js";
 export { SubagentContentError, loadSubagentPackage, nativeSubagentFormat, parseNativeSubagent, readSubagentPackage, selectSubagentImplementation, } from "./content/subagent-content.js";
 export { ArchiveGuardrailError, ZIP_LOCAL_SIGNATURE, checkForbiddenSourceEntries, defaultReadEntry, parseZipCentralDirectory, validateArchive, } from "./packaging/archive-guardrails.js";

package/dist/src/lint/catalog/hook/envelope.d.ts

@@ -7,6 +7,7 @@ export declare const hookEnvelopeRules: {
     manifestSchemaValid: {
         check: (context: HookRuleContext) => Effect.Effect<readonly import("../../rule.ts").AdvisoryFinding[], never, never>;
         kind: "advisory";
+        enabledByDefault?: false;
         id: string;
         description: string;
         severity: import("../../rule.ts").Severity;

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

@@ -38,6 +38,7 @@ const UTF8_BOM = "\uFEFF";
 const decoder = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true });
 export const frontmatterParseableRule = {
     id: RULE_ID,
+    enabledByDefault: false,
     description: "SKILL.md frontmatter is a valid YAML mapping.",
     kind: "advisory",
     severity: "error",

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

@@ -41,6 +41,7 @@ const finding = (message) => ({
 });
 export const frontmatterStandardValidRule = {
     id: RULE_ID,
+    enabledByDefault: false,
     description: "SKILL.md metadata conforms to the pinned Agent Skills standard.",
     kind: "advisory",
     severity: "error",

package/dist/src/lint/catalog/skill/manifest-present.js

@@ -25,7 +25,7 @@ export const manifestPresentRule = makeManifestPresentRule({
     ruleId: RULE_ID,
     description: "Native skills include a root skill.json manifest.",
     manifestFile: SKILL_JSON,
-    missingMessage: "skill.json is missing for this native skill. Create skill.json with the required manifest fields (`owner`, `type`, `name`, `version`).",
+    missingMessage: "This AXM skill package is missing its required skill.json manifest. Restore the package manifest before managing it.",
     getFiles: (context) => context.packageFiles,
     applies: (context) => context.subject.isNative,
 });

package/dist/src/lint/catalog/skill-accessor/contexts.d.ts

@@ -39,7 +39,6 @@ import type { SkillFileAccessor, SkillRuleContext } from "../../context.js";
  * @experimental This API is unstable and may change without notice.
  */
 export interface InstalledSkillInfo {
-    readonly validationPurpose?: "authoring" | "management";
     readonly isNative: boolean;
     readonly skillJson: unknown;
     readonly expectedName?: string;

package/dist/src/lint/catalog/skill-accessor/contexts.js

@@ -44,9 +44,6 @@
  */
 export const buildSkillRuleContexts = (input) => input.installedSkills.map((info) => ({
     subject: {
-        ...(info.validationPurpose === undefined
-            ? {}
-            : { validationPurpose: info.validationPurpose }),
         isNative: info.isNative,
         skillJson: info.skillJson,
         ...(info.expectedName === undefined ? {} : { expectedName: info.expectedName }),

package/dist/src/lint/catalog/skill.d.ts

@@ -1,8 +1,8 @@
 /**
  * `skill/*` rule catalog.
  *
- * Per the lint design, registry publish and `axm lint`
- * run exactly these rules against each skill context:
+ * Ordinary lint checks management obligations; the two frontmatter
+ * conformance rules run only when explicitly configured:
  *
  * | ID                                     | Severity | Autofix |
  * | -------------------------------------- | -------- | ------- |

package/dist/src/lint/catalog/skill.js

@@ -1,8 +1,8 @@
 /**
  * `skill/*` rule catalog.
  *
- * Per the lint design, registry publish and `axm lint`
- * run exactly these rules against each skill context:
+ * Ordinary lint checks management obligations; the two frontmatter
+ * conformance rules run only when explicitly configured:
  *
  * | ID                                     | Severity | Autofix |
  * | -------------------------------------- | -------- | ------- |
@@ -25,7 +25,6 @@
  * @experimental This API is unstable and may change without notice.
  * @packageDocumentation
  */
-import * as Effect from "effect/Effect";
 import { skillMdPresentRule } from "./skill/skill-md-present.js";
 import { manifestPresentRule } from "./skill/manifest-present.js";
 import { frontmatterParseableRule } from "./skill/frontmatter-parseable.js";
@@ -34,15 +33,6 @@ import { manifestSchemaValidRule } from "./skill/manifest-schema-valid.js";
 import { manifestKeysRecognizedRule } from "./skill/manifest-keys-recognized.js";
 import { recommendedPacksValidRule } from "./skill/recommended-packs-valid.js";
 import { standaloneDeclarationValidRule } from "./skill/standalone-declaration-valid.js";
-/**
- * Authoring rules do not run as routine health checks for acquired content.
- * Skill presence remains a management obligation; accepted identity, integrity,
- * ownership and projection checks are supplied by the workspace catalog.
- */
-const authoringOnly = (rule) => ({
-    ...rule,
-    check: (context) => context.subject.validationPurpose === "management" ? Effect.succeed([]) : rule.check(context),
-});
 /**
  * Ordered `skill/*` rule catalog. Declaration order is the evaluation
  * order within a single `evaluateContexts` call (deterministic ordering is
@@ -52,14 +42,12 @@ const authoringOnly = (rule) => ({
  */
 export const skillRules = [
     skillMdPresentRule,
-    ...[
-        manifestPresentRule,
-        frontmatterParseableRule,
-        frontmatterStandardValidRule,
-        manifestSchemaValidRule,
-        manifestKeysRecognizedRule,
-        standaloneDeclarationValidRule,
-        recommendedPacksValidRule,
-    ].map(authoringOnly),
+    manifestPresentRule,
+    frontmatterParseableRule,
+    frontmatterStandardValidRule,
+    manifestSchemaValidRule,
+    manifestKeysRecognizedRule,
+    standaloneDeclarationValidRule,
+    recommendedPacksValidRule,
 ];
 //# sourceMappingURL=skill.js.map

package/dist/src/lint/catalog-metadata.d.ts

@@ -19,6 +19,7 @@ export type LintCatalogView = "workspace" | "git-index";
 export interface LintCatalogRuleMetadata {
     readonly id: string;
     readonly defaultSeverity: Severity;
+    readonly enabledByDefault?: false;
     readonly group: LintCatalogGroup;
     readonly views: ReadonlyArray<LintCatalogView>;
 }
@@ -34,91 +35,115 @@ export declare const lintCatalogRuleMetadata: readonly ({
     defaultSeverity: "error";
     group: "skill";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
+} | {
+    id: string;
+    enabledByDefault: false;
+    defaultSeverity: "error";
+    group: "skill";
+    views: readonly ["workspace", "git-index"];
 } | {
     id: string;
     defaultSeverity: "warning";
     group: "skill";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "error";
     group: "pack";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "error";
     group: "subagent";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "warning";
     group: "subagent";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "error";
     group: "mcp-server";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "warning";
     group: "mcp-server";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "error";
     group: "hook";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "warning";
     group: "hook";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "error";
     group: "rule";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "warning";
     group: "rule";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "error";
     group: "knowledge";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "warning";
     group: "knowledge";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "error";
     group: "workspace";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "info";
     group: "workspace";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "warning";
     group: "workspace";
     views: readonly ["workspace"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "warning";
     group: "workspace";
     views: readonly ["workspace", "git-index"];
+    enabledByDefault?: never;
 } | {
     id: string;
     defaultSeverity: "error";
     group: "workspace";
     views: readonly ["workspace"];
+    enabledByDefault?: never;
 })[];
 /** Every accepted lint-rule identity, in catalog/reporting order. */
 export declare const allLintCatalogRuleIds: readonly string[];

package/dist/src/lint/catalog-metadata.js

@@ -40,9 +40,16 @@ const defineLintCatalog = (entries) => {
 export const lintCatalogRuleMetadata = defineLintCatalog([
     { id: "skill/skill-md-present", defaultSeverity: "error", group: "skill", views: bothViews },
     { id: "skill/manifest-present", defaultSeverity: "error", group: "skill", views: bothViews },
-    { id: "skill/frontmatter-parseable", defaultSeverity: "error", group: "skill", views: bothViews },
+    {
+        id: "skill/frontmatter-parseable",
+        enabledByDefault: false,
+        defaultSeverity: "error",
+        group: "skill",
+        views: bothViews,
+    },
     {
         id: "skill/frontmatter-standard-valid",
+        enabledByDefault: false,
         defaultSeverity: "error",
         group: "skill",
         views: bothViews,

package/dist/src/lint/config.d.ts

@@ -68,8 +68,8 @@ export type LintConfig = Schema.Schema.Type<typeof LintConfigSchema>;
 /**
  * The platform-canonical `LintConfig` — empty rules, no overrides.
  *
- * Registry publish uses this config; it carries no overrides so every rule
- * fires at its catalog severity.
+ * It carries no overrides: enabled rules use their catalog severity and
+ * opt-in conformance rules remain disabled.
  *
  * @experimental This API is unstable and may change without notice.
  */

package/dist/src/lint/config.js

@@ -90,8 +90,8 @@ export const LintConfigSchema = Schema.Struct({
 /**
  * The platform-canonical `LintConfig` — empty rules, no overrides.
  *
- * Registry publish uses this config; it carries no overrides so every rule
- * fires at its catalog severity.
+ * It carries no overrides: enabled rules use their catalog severity and
+ * opt-in conformance rules remain disabled.
  *
  * @experimental This API is unstable and may change without notice.
  */

package/dist/src/lint/context.d.ts

@@ -140,7 +140,6 @@ export interface SkillRuleContext<S = SkillContent> {
  */
 export interface SkillContent {
     /** Authored checks are opt-in for acquired content; normal health checks use management. */
-    readonly validationPurpose?: "authoring" | "management";
     readonly isNative: boolean;
     readonly skillJson: unknown;
     /** Agent-facing skill directory name used for the standard name-match check. */

package/dist/src/lint/evaluate.js

@@ -57,11 +57,13 @@ const withSeverity = (finding, severity) => ({
  * @experimental This API is unstable and may change without notice.
  */
 export const evaluateContexts = (rules, contexts, config) => Effect.forEach(rules.flatMap((rule) => contexts.map((context) => ({ rule, context }))), ({ rule, context }) => evaluateOne(rule, context, config), { concurrency: 1 });
-const evaluateOne = (rule, context, config) => Effect.map(rule.check(context), (rawFindings) => ({
-    rule,
-    context,
-    findings: applySeverityConfig(rule, rawFindings, config),
-}));
+const evaluateOne = (rule, context, config) => rule.enabledByDefault === false && config.rules?.[rule.id] === undefined
+    ? Effect.succeed({ rule, context, findings: [] })
+    : Effect.map(rule.check(context), (rawFindings) => ({
+        rule,
+        context,
+        findings: applySeverityConfig(rule, rawFindings, config),
+    }));
 const applySeverityConfig = (rule, findings, config) => {
     const override = config.rules?.[rule.id];
     const effective = resolveEffectiveSeverity(rule.severity, override);

package/dist/src/lint/rule.d.ts

@@ -75,6 +75,8 @@ export type LintFinding = AdvisoryFinding;
  * @experimental This API is unstable and may change without notice.
  */
 export interface RuleBase {
+    /** Conformance rules run only when explicitly enabled in lint.rules. */
+    readonly enabledByDefault?: false;
     readonly id: string;
     readonly description: string;
     readonly severity: Severity;

package/dist/src/packaging/manifest-policy.js

@@ -153,7 +153,7 @@ export const resolveManifest = (input) => Effect.gen(function* () {
     })));
     yield* Effect.fromResult(validateManifestHasNoAgentsField(manifestEntry.fileName, parsed));
     const schema = manifestSchemaForType(input.type);
-    yield* Schema.decodeUnknownEffect(schema)(parsed, input.type === "hook" ? { onExcessProperty: "error" } : undefined).pipe(Effect.mapError((error) => {
+    yield* Schema.decodeUnknownEffect(schema)(parsed, input.type === "hook" || input.type === "skill" ? { onExcessProperty: "error" } : undefined).pipe(Effect.mapError((error) => {
         const companionPackageError = classifyCompanionPackageManifestError(parsed);
         return new ManifestError({
             code: companionPackageError?.code ?? "manifest_schema_invalid",

package/package.json

@@ -4,14 +4,14 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/extension-model": "^0.42.0",
+    "@agentxm/extension-model": "^0.42.1",
     "effect": "4.0.1",
     "smol-toml": "^1.9.0",
     "yaml": "^2.9.1"
   },
   "description": "AXM extension content behavior: skill and subagent content parsing, Knowledge bundle inspection and search, the lint rule catalog, and archive and manifest validation shared by the axm CLI and the AgentXM Registry. Unstable and unsupported — use the axm.sh CLI.",
   "devDependencies": {
-    "@agentxm/specification-metadata": "^0.42.0",
+    "@agentxm/specification-metadata": "^0.42.1",
     "@effect/platform-node": "4.0.1",
     "@effect/vitest": "4.0.1",
     "@fast-check/vitest": "^0.5.0",
@@ -60,5 +60,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.42.0"
+  "version": "0.42.1"
 }