Skip to content

agent-skills-compatibility.md

Latest commit

 

History

History
620 lines (505 loc) · 30.6 KB

agent-skills-compatibility.md

File metadata and controls

620 lines (505 loc) · 30.6 KB
Raw

Agent Skills Compatibility and Migration

This document defines Renma's SKILL.md compatibility and migration contract, including the 0.18.0 focused-workflow model. Agent Skills owns the portable Skill format. Renma extends it with deterministic governance evidence, without defining a competing Skill format.

Compatibility is the portable authoring boundary for Skill entrypoints, not Renma's complete repository model. A Renma repository may also contain Context Lenses, independently owned Context Assets, references, policies, lifecycle and ownership declarations, dependencies, and evidence organized across domains, products, teams, or workflows. That flexibility applies to the broader repository assets, not to arbitrary Skill roots: canonical Skill entrypoints in 0.16.0 use SKILL.md under the recognized skills/ and .agents/skills/ roots, subject to the reserved-directory exclusions in the entrypoint path contract. A custom scan glob does not make a path such as docs/skills/demo/SKILL.md a Skill. Renma is not an Agent Skills registry, runtime, or live router, and repository knowledge does not need to be embedded inside the supported Skill directories.

In this document, “pre-0.16 Renma Skill format” refers to the top-level Renma metadata syntax supported before Renma 0.16.0. It is the migration source format. The 0.16.0 target uses Agent Skills standard fields plus flat metadata.renma.* entries.

This rollout follows one operating principle:

LLM proposes. Renma verifies. Human approves.

Responsibility Boundary

Keep these surfaces separate:

Agent Skills name, description, body, and references
  -> portable and primarily LLM-facing

metadata.renma.*
  -> structured governance evidence for Renma

Renma
  -> deterministic validation and migration assistance

Human
  -> approves semantic changes

The Markdown body remains the primary instruction surface after a Skill has been activated. Generic Agent Skills clients may not send arbitrary metadata to a model. Renma metadata therefore does not guarantee model compliance and must not replace behavior-critical instructions.

For a new Skill, or when intentionally redesigning asset boundaries, use renma guide skill to establish Renma repository asset, metadata, Context, and file boundaries. Declare the creation gate passed only after every gate requirement is established, including the smallest justified asset structure, and no Blocking decision remains. Then use platform-native Skill authoring guidance for the name, trigger description, instructions, workflow, constraints, completion criteria, and ambiguity-resolving examples within those boundaries. A name change that alters the canonical Skill directory/name relationship is an intentional path and identity change that requires validation, not an ordinary semantic rewrite. The Authoring Guide owns the general new-Skill and existing-Skill workflows; this document owns the canonical format and migration contract.

Canonical 0.16.0 Frontmatter

Agent Skills owns the standard top-level fields:

  • name
  • description
  • license
  • compatibility
  • metadata
  • allowed-tools

Renma owns flat metadata keys beginning with renma.. Agent Skills metadata values are strings, including values that encode lists or booleans:

---
name: spec-review
description: Review specifications before implementation. Use for ambiguity and boundary analysis.
metadata:
  renma.id: skill.testing.spec-review
  renma.owner: qa-platform
  renma.status: stable
  renma.tags: '["testing","spec-review"]'
---

Do not use unprefixed shared keys such as metadata.owner. Do not use a nested metadata.renma mapping. Unknown renma.* keys and other vendors' string metadata remain valid metadata and are preserved during migration without interpretation.

Operational Renma Metadata

The authoritative metadata reference owns the complete operational field inventory, Skill/non-Skill mappings, value formats, authoring status, and consumer projections. This compatibility guide focuses on canonical Skill serialization, the portable boundary, and migration behavior rather than maintaining a second field list.

For canonical Skills, description is the sole portable discovery source of truth for what the Skill does and when it should be selected. renma.when-to-use and renma.when-not-to-use are reported as unsupported Renma metadata and are not interpreted. Their presence alone does not make an otherwise valid Agent Skills string-to-string metadata mapping specification-invalid. Historical top-level when_to_use and when_not_to_use may help an explicit pre-0.16 migration recover a portable description, but are not emitted as Renma metadata. Their top-level non-Skill forms remain appropriate for shared Context Assets.

Renma normalizes the governance values into the existing asset metadata model used by scan findings, inspect, catalog, ownership, graph and dependency resolution, readiness, BOM, Trust Graph, diff, and CI reporting. The Discovery-only publication marker is parsed separately into the prepared Skill Discovery index and does not enter catalog metadata or dependencies. This is a serialization change, not a second governance model or a change to independent consumers' semantics. graph --view discovery, skill-index, and the compact 0.23.0 Readiness Discovery summary/checks reuse that prepared model. Readiness does not embed Skill Index arrays or diagnostic payloads; semantic diff, CI report, Trust Graph, BOM, ownership, init, scaffold, guide, and suggestions do not gain Skill Index fields.

Text values are trimmed strings. renma.status accepts experimental, stable, suspended, revoked, deprecated, and archived. A suspended or revoked Skill also requires non-blank renma.status-reason and a real YYYY-MM-DD renma.status-changed-at string. Revoked means trust or authorization for use was explicitly withdrawn because of a known problem. These flat keys describe the latest reviewed lifecycle transition and are distinct from freshness field renma.last-reviewed-at. List values are JSON-array strings containing strings only:

metadata:
  renma.tags: '["testing","spec-review"]'
  renma.requires-context: '["context.testing.boundaries"]'
  renma.optional-context: "[]"

Canonical list metadata is not comma-separated. Malformed JSON, non-array JSON, and non-string array members are invalid rather than guessed. Diagnostics for canonical values retain evidence for the specific child key under metadata, not just the parent mapping.

renma.continues-with is the explicit Skill-to-Skill continuation contract. It additionally rejects empty or whitespace-only members, preserves each declaration index at the field's exact line evidence, and creates no routes for an empty array. It is operational only on canonical SKILL.md Agent Skills and does not enter catalog.dependencies. See the Skill Discovery Graph and Index contract.

Historical pre-0.16 top-level status_reason and status_changed_at Skill fields are recognized only as one-way migration input. suggest-metadata preserves their exact reviewed string values as renma.status-reason and renma.status-changed-at; canonical and historical conflicts remain blocked for human review. Renma does not infer either value from Git history or file timestamps.

renma.published-entrypoint is the explicit Skill-local publication marker. Its only valid value is the exact string "true"; omission means unpublished. Native YAML booleans, false values, alternate casing, surrounding whitespace, other types, duplicate declarations, duplicate top-level metadata mappings, aliases, and legacy fallback are rejected with exact evidence. Effective publication additionally requires a specification-valid, active canonical Skill with a repository-unique effective asset ID. Structural roots do not become published automatically. Repository-wide adoption is configured separately with skill_discovery.adopted; see the Skill Discovery Graph and Index contract.

renma skill-index [path] emits the same prepared evidence as compact Markdown or canonical renma.skill-index.v1 JSON. It adds no metadata interpretation: router, workflow, entrypoint, and specialized operational roles remain responsibilities of normal Skills rather than new asset kinds. Exact focus is by effective Skill ID or repository-relative source path only.

Empty text, invalid status, and invalid lifecycle or freshness values retain their existing operational diagnostic semantics and stable finding IDs where applicable.

Operational source selection is explicit:

specification-valid Agent Skill
  -> governance and security metadata comes only from metadata.renma.*

invalid, hybrid, or pre-0.16 Skill
  -> no operational Skill metadata; suggest-metadata may use it as migration input

non-Skill asset
  -> existing top-level Renma metadata syntax

An Agent Skill must pass the Agent Skills specification checks before any Renma metadata becomes operational. Renma authoring warnings do not block operational metadata. A Skill never falls back to or merges top-level pre-0.16 equivalents. Contexts, context lenses, profiles, references, examples, agents, configuration files, and other non-Skill assets keep their existing metadata syntax and behavior.

Canonical security fields use the same flat string-valued boundary. Boolean values must be the exact strings "true" or "false", and list values must be JSON-array strings containing strings only. This includes the asset-local floating-dependency allowance documented in the authoritative table and the Security Policy Guide. Renma does not coerce YAML booleans, alternate boolean spellings, comma-separated lists, or non-string array members. Canonical child-key evidence is preserved for diagnostics, including multiline YAML values.

Entrypoint Paths

Canonical Agent Skills entrypoints follow this structural grammar:

<skill-root>/<domain-segments...>/<skill-directory>/SKILL.md

<skill-root> is exactly skills or .agents/skills. <domain-segments...> may be empty, so one Skill directory is still required between the root and the exact SKILL.md filename. None of the directory segments between the root and SKILL.md may be one of the reserved Skill-support names: assets, examples, profiles, references, or scripts.

Therefore these are valid structural candidates:

skills/payment/SKILL.md
skills/payments/refund/SKILL.md
skills/platform/ios/setup/SKILL.md
.agents/skills/payments/refund/SKILL.md

These are not Skill entrypoints:

skills/references/SKILL.md
skills/payment/references/SKILL.md
skills/payment/references/vendor/SKILL.md
.agents/skills/examples/SKILL.md

A reserved directory directly below a Skill root is a reserved support root without an owning Skill. Once an ordinary Skill directory precedes the reserved segment, the path is Skill-local support owned structurally by that logical Skill directory. Deeper directories do not restart Skill classification, even when a file is named SKILL.md.

The familiar default glob notation remains a qualified shorthand for that grammar:

skills/**/SKILL.md
.agents/skills/**/SKILL.md

Glob matching controls which files discovery reads. The structural classifier still determines whether a discovered file is a Skill entrypoint, Skill-local support, or a reserved support root. Broadening a glob never turns support content into an independent Skill.

The repository walk reports historical skill.md and *.skill.md spellings under those roots, with the same reserved-directory exclusions, so scan can show the required path migration. They remain unknown to operational Skill discovery, cataloging, ownership, inheritance, security, and dependency consumers. A custom glob cannot change that boundary; only an explicit suggest-metadata target creates a migration candidate.

The entrypoint migration is explicit:

skills/demo/skill.md
  -> skills/demo/SKILL.md

skills/testing/spec-review.skill.md
  -> skills/testing/spec-review/SKILL.md

The same mappings apply under .agents/skills/**. A lowercase skill.md requires a rename. A flat *.skill.md requires a move into the filename-derived directory plus a rename. Structured suggest-metadata output reports sourcePath, targetPath, and entrypointMigration (none, rename, or move-and-rename) so the path change cannot be mistaken for an apply-ready frontmatter-only result. Both paths are normalized repository-relative paths. Renma uses that same identity for entrypoint classification and rebases the target against the resolved repository root only when checking the filesystem for collisions.

Repository discovery recognizes these roots only at the beginning of a repository-relative path. A nested path such as docs/skills/demo/SKILL.md is not a repository Skill, and a later skills segment cannot escape a reserved references or examples directory. For absolute suggest-metadata targets, Renma requires one unambiguous Skill root and rejects paths with multiple possible roots. When structural evidence leaves multiple repository roots plausible, Renma returns repository-boundary-ambiguous and does not recommend scanning the caller's current directory. Add a repository marker or supply an explicit root before retrying.

Repository-relative classification normalizes leading and internal . segments and safe .. segments before checking the root. A path is rejected if .. escapes its original skills/ or .agents/skills/ root, even if a later segment would appear to re-enter it. The same invariant applies to explicit historical migration targets. User-facing structured command argv retains the exact path discovered by scan or supplied by the user.

Inside an Agent Skill directory, assets/, examples/, profiles/, references/, and scripts/ contain Skill-local support material and are not treated as nested Skill roots. The same reserved names cannot be used as top-level Skill names under skills/ or .agents/skills/ without reserved-name guidance.

Agent Skills may contain additional package files and directories. Renma does not make those locations canonical Skill-local governance or inherit owner and security policy merely from package containment. When SKILL.md or already inspected support explicitly names a static repository-local path such as templates/prompt.md, docs/instructions.txt, or bin/run.py, Renma retains it as explicit-noncanonical package evidence. Inspection still honors the repository exclusion, size, depth, readability, and no-symlink boundaries; a present but uninspectable explicit target blocks strict completeness. Files in noncanonical locations that are not explicitly referenced remain outside this bounded evidence expansion.

Validation During Scan

Agent Skills validation is part of the existing scan workflow:

renma scan .
renma scan . --format json

The JSON report includes a dedicated agentSkills summary and per-Skill results. Text output includes a concise valid/invalid summary, structural issues, authoring warnings, and a suggest-metadata migration command when a canonical entrypoint contains pre-0.16 Renma Skill fields. Historical filename spellings are not Agent Skills results; repository diagnostics report them as migration- only inputs and direct maintainers to suggest-metadata.

In JSON, migrationCommand on an Agent Skills result contains structured command and args fields plus a display string. The argv fields preserve the exact path and are the source of truth for tools. Text output uses POSIX shell quoting when a path contains spaces or shell metacharacters.

The locally versioned validation profile uses the maintained yaml package in YAML 1.2 mode. It validates:

  • the exact SKILL.md filename;
  • frontmatter presence and closure;
  • YAML syntax and mapping shape;
  • duplicate top-level and metadata keys;
  • the allowed Agent Skills top-level fields;
  • required, non-empty string name and description values;
  • NFKC-normalized name length, Unicode letters/digits, lowercase and hyphen rules, and normalized immediate-parent match. The YAML field is trimmed, but the filesystem directory name is not; leading or trailing directory whitespace is invalid rather than normalized away;
  • description and compatibility length limits;
  • optional field types;
  • metadata as a string-to-string mapping.

The validation profile is local. Renma does not fetch a schema or validation rules at runtime.

Agent Skills validation does not add a separate validation command or change the existing scan or --fail-on exit contract. Agent Skills results are visible in scan output but are not inserted into the existing finding threshold path.

Format Classification

Each inspected Skill receives one migration-oriented classification:

agent-skills
  Agent Skills identity with no pre-0.16 Renma Skill fields

renma-legacy
  pre-0.16 Renma Skill fields without Agent Skills identity

hybrid
  Agent Skills identity plus pre-0.16 Renma Skill fields

unknown
  neither Agent Skills identity nor a recognized migration source

Classification remains migration-oriented. Operational normalization is stricter: only a specification-valid agent-skills document contributes Skill metadata. renma-legacy, hybrid, unknown, and otherwise invalid documents remain visible to validation and migration diagnostics but contribute no operational Skill metadata.

Selection Boundaries and Execution Constraints

A selection boundary determines whether a Skill should be chosen. If the body says Do not use this skill for test execution, that exclusion belongs in description because name and description are the discovery surface.

An execution constraint applies after activation. Instructions such as Do not modify production files or Never upload secrets belong in the body under a prominent heading such as Hard Constraints, Prohibited Actions, or Safety Constraints. A generic execution constraint must not be copied automatically into description. Renma v1 does not operationally accept metadata.renma.when-to-use or metadata.renma.when-not-to-use; portable Skill discovery and selection boundaries belong in description.

Renma may report conservative authoring warnings for a missing usage boundary, an omitted selection exclusion, a buried or scattered execution constraint, or a prohibition without a supported alternative or stop behavior. Nested subsections under a prominent constraint heading remain prominent. These warnings do not make a structurally valid Agent Skill invalid.

Agent Skills body inspection and migration description extraction ignore fenced examples opened with at least three backticks or at least three tildes. A fence closes only with the same character and a marker at least as long as its opener. Fence inspection starts at the Markdown body; fence-like text inside YAML block scalars does not hide body diagnostics.

Agent Skills Diagnostic Identifiers

Agent Skills diagnostics use stable identifiers in the agentSkills portion of scan output. Specification errors make the Skill invalid. Renma authoring warnings do not affect structural validity or the existing --fail-on threshold. Renma-owned authoring warnings use the RN-SKILL-* namespace and remain in the agentSkills projection so maintainers get exact source evidence without confusing them with Agent Skills specification failures.

Specification errors

Identifier Meaning
AS-SKILL-NONCANONICAL-FILENAME The entrypoint filename is not exactly SKILL.md.
AS-SKILL-MISSING-FRONTMATTER YAML frontmatter is absent.
AS-SKILL-UNCLOSED-FRONTMATTER The opening frontmatter delimiter has no closing delimiter.
AS-SKILL-INVALID-YAML The frontmatter is not valid YAML.
AS-SKILL-FRONTMATTER-NOT-MAPPING The frontmatter root is not a YAML mapping.
AS-SKILL-DUPLICATE-FIELD A top-level frontmatter field is declared more than once.
AS-SKILL-DUPLICATE-METADATA-KEY A key in metadata is declared more than once.
AS-SKILL-UNEXPECTED-TOP-LEVEL-FIELD A top-level field is outside the Agent Skills field set.
AS-SKILL-MISSING-NAME The required name field is absent or empty.
AS-SKILL-INVALID-NAME name has the wrong type or violates the name rules.
AS-SKILL-NAME-DIRECTORY-MISMATCH The normalized name does not match its immediate parent directory.
AS-SKILL-MISSING-DESCRIPTION The required description field is absent or empty.
AS-SKILL-INVALID-DESCRIPTION description is not a string.
AS-SKILL-DESCRIPTION-TOO-LONG description exceeds 1,024 Unicode code points.
AS-SKILL-INVALID-COMPATIBILITY compatibility is not a non-empty string.
AS-SKILL-COMPATIBILITY-TOO-LONG compatibility exceeds 500 Unicode code points.
AS-SKILL-INVALID-LICENSE license is present but is not a string.
AS-SKILL-INVALID-ALLOWED-TOOLS allowed-tools is present but is not a string.
AS-SKILL-INVALID-METADATA metadata is not a string-to-string mapping.

Renma authoring warnings

These bounded natural-language authoring checks use English as their primary recognition vocabulary. A non-English or multilingual description remains supported and is conservatively accepted rather than warned merely because its capability, usage, or exclusion phrasing is outside the English word list. Renma does not translate the description or claim equivalent multilingual NLP. The conservative multilingual signal requires non-ASCII letter or combining- mark evidence; typographic punctuation and emoji in otherwise-English prose do not disable the ordinary English-primary authoring warnings.

Identifier Meaning
RN-SKILL-UNSUPPORTED-ROUTING-METADATA Removed renma.when-to-use or renma.when-not-to-use metadata is present and ignored by Renma; this warning does not make the Agent Skill invalid.
RN-SKILL-DESCRIPTION-MISSING-USAGE-BOUNDARY The description does not state when the Skill should be used.
RN-SKILL-DESCRIPTION-MISSING-CAPABILITY The description does not clearly state what the Skill does. This is a Renma authoring warning, not an Agent Skills validity error.
RN-SKILL-DESCRIPTION-OMITS-SELECTION-BOUNDARY A body selection exclusion is absent from the description.
RN-SKILL-EXECUTION-CONSTRAINT-NOT-PROMINENT An execution constraint is outside a prominent constraint section.
RN-SKILL-EXECUTION-CONSTRAINT-SCATTERED Execution constraints are scattered across sections.
RN-SKILL-EXECUTION-CONSTRAINT-MISSING-ALTERNATIVE A prohibition has no nearby supported alternative or stop behavior.

For RN-SKILL-EXECUTION-CONSTRAINT-MISSING-ALTERNATIVE, inspect applicable Skill instructions, Context Assets, and user-provided evidence before asking for clarification. The warning reports a bounded detection result, not proof that the intended behavior is unknown to the authoring agent. Ask only if the required behavior remains unresolved; preserve the constraint and do not invent an alternative or broaden permission to clear the warning.

One-Way Migration

Pre-0.16 Renma Skill fields are migration input only:

pre-0.16 Renma Skill
  -> Agent Skills identity
  -> metadata.renma.*

Use the existing non-editing command with canonical or non-canonical entrypoints:

renma scan . --fail-on high
renma suggest-metadata skills/example/SKILL.md --format prompt
renma suggest-metadata skills/example/skill.md --format json
renma suggest-metadata skills/testing/spec-review.skill.md --format prompt
# apply only an unblocked canonical frontmatter candidate
renma scan . --fail-on high

For Skill targets, suggest-metadata can preserve valid standard Agent Skills fields, use a valid immediate parent directory as name, preserve an existing valid description, conservatively extract description evidence from the body, move recognized pre-0.16 Renma Skill fields to metadata.renma.*, and render canonical frontmatter for human review. It never edits the file and never proposes a reverse conversion for a canonical Agent Skill.

Pre-0.16 security fields migrate in the same one-way proposal. Safe string values are preserved, boolean values serialize as exact "true" or "false" strings, and list values serialize as JSON-array strings. Unsafe or ambiguous values block canonical frontmatter generation for human review.

Before presenting a non-canonical entrypoint migration, Renma renders the candidate frontmatter, combines it with the unchanged Markdown body at the target SKILL.md path, and runs the existing Agent Skills validator on that in-memory result. Any specification error blocks the proposal. If the target entrypoint already exists as a distinct filesystem entry, migration is also blocked; Renma does not propose overwriting, merging, or deleting either file. Case-only renames that resolve to the same filesystem entry are not treated as a collision.

For a specification-valid canonical SKILL.md, an explicit --owner <owner> instead produces a canonical metadata retrofit candidate at metadata.renma.owner. An identical existing owner is preserved without a rewrite. A different existing owner blocks the proposal for human review. Without --owner, Renma does not invent owner metadata or emit a meaningless canonical rewrite. This retrofit is not reverse migration.

After generating a suggestion, review the candidate, apply only intended metadata or migration changes, run renma scan . --fail-on high, fix relevant diagnostics, and rerun validation before human approval. Conduct any requested semantic review separately using platform-native Skill authoring guidance within the repository's established boundaries.

Pre-0.16 Value Serialization

Migration never converts native YAML numbers into text. Native YAML booleans are accepted only for recognized boolean security fields, where the meaning is unambiguous.

  • Text scalar fields (id, title, version, owner, status, purpose, last_reviewed_at, review_cycle, expires_at, and security_profile) require YAML strings.
  • String-list fields accept YAML arrays containing strings only, pre-0.16 comma-separated strings, or JSON-array strings containing strings only. Numeric and boolean elements are blocked.
  • Boolean security fields accept YAML booleans or the exact strings "true" and "false", then serialize to exact canonical strings.

For example, version: "1.0" and tags: ["1.0"] are safe. version: 1.0 and tags: [1.0] block canonical frontmatter generation. Likewise, network_allowed: yes is blocked rather than guessed.

Unsafe Migration Blocking

Renma does not render canonical frontmatter when migration would be ambiguous or lossy. Blocking cases include:

  • invalid or unclosed YAML frontmatter;
  • a non-mapping frontmatter document;
  • duplicate top-level or metadata keys;
  • non-string metadata values;
  • an invalid Skill directory name or conflicting identity;
  • conflicting Agent Skills and pre-0.16 Renma Skill values;
  • an unknown top-level field;
  • missing evidence for a usable description;
  • duplicate semantic list values or unsupported pre-0.16 value shapes;
  • a candidate that remains invalid at its target SKILL.md path;
  • an existing distinct target entrypoint or an unverifiable target collision;

Renma reports structured blocked evidence with the field and reason. It never selects the last duplicate value, silently deletes an unknown field, or assigns an unknown top-level field to a vendor namespace.

When blocked, do not apply a candidate. Review the conflict or invalid evidence, confirm the Skill's intent using platform-native Skill authoring guidance within the Renma boundaries, correct the source evidence, and rerun suggest-metadata. After intended corrections, run renma scan . --fail-on high, fix relevant diagnostics, and rerun the scan.

Within a valid metadata mapping, Renma distinguishes:

known renma.* key
  interpret for migration comparison and preserve

unknown renma.* key
  preserve without interpretation

other vendor metadata
  preserve without interpretation

unknown top-level field
  block migration

Renma 0.16+ Boundary

Renma 0.16.0 completes the repository format migration:

  • Skills must be specification-valid Agent Skills to contribute operational metadata;
  • all Renma Skill governance and security metadata is read from flat metadata.renma.* string entries;
  • pre-0.16 top-level Skill metadata is migration input only;
  • suggest-metadata converts recognized governance and security fields in one reviewed proposal;
  • the repository-owned release-prep Skill and generated Skill scaffolds are fully canonical;
  • non-Skill assets retain their existing top-level metadata behavior.

This boundary does not add runtime Skill selection, prompt assembly, context injection, execution, or telemetry.