Status: Normative
Version: 2.0.0
Sources synthesized: Agent Skills spec (agentskills.io), anthropics/skills, anthropics/claude-code plugin-dev, openai/skills, github/awesome-copilot, Mintlify, Skills Directory, Geeksfino/openskills, addyosmani/agent-skills
Scope: Cross-host portable core (Claude Code, Codex CLI, GitHub Copilot CLI, OpenClaw, compatible hosts)

1. Executive Summary

This document defines a single, maximally strict specification for SKILL.md bundles, synthesized from all major skill ecosystem implementations and deep-research outputs across multiple AI providers. The portable profile is intentionally narrower than the full ecosystem because the source corpus agrees on the core artifact model — directory-scoped skill, required SKILL.md, YAML frontmatter plus Markdown body, progressive disclosure, and optional bundled resources — but diverges on frontmatter breadth, host-specific runtime controls, install/discovery paths, and metadata overlays.

The result is a closed portable core with exactly two required frontmatter fields (name and description), a canonical root layout, a fixed body section order, a deterministic 9-stage validation pipeline, and a mandatory overlay boundary. This is the strictest rule set that remains compatible with the shared open spec, Anthropic product docs, OpenAI product docs, and GitHub product docs without relying on host-specific semantics such as Claude Code frontmatter extensions, Codex agents/openai.yaml, or GitHub CLI provenance injection.

All best practices identified across the source corpus are elevated to mandatory requirements unless they provably break parsing or cross-host compatibility in a major runtime.

2. Source Model & Priority

2.1 Inclusion criteria

A rule is included in this standard only if all of the following are true:

1. The rule is explicit in a cited source or is a necessary inference from multiple cited sources.
2. The rule is machine-testable.
3. The rule applies to the skill artifact itself: SKILL.md, bundled files, or deterministic validation/release behavior.
4. The rule does not depend on undocumented host behavior.
5. If the rule is not in the portable intersection, it is classified as overlay-only or UNKNOWN, not silently promoted into the core.

2.2 What counts as breaking compatibility

A rule breaks compatibility if any major documented runtime would, for the same bundle, do at least one of the following:

• reject parsing or discovery;
• assign materially different execution meaning to the same field;
• require different frontmatter contents for correct operation;
• mutate SKILL.md in a way that invalidates the portable core;
• require host-specific install/discovery location knowledge inside the bundle;
• require host-specific runtime semantics (tool preapproval, subagents, injected metadata) to preserve core meaning.

2.3 Source priority

Where sources conflict, the higher-ranked source wins. Where a higher-ranked source is silent and a lower-ranked source specifies a rule, the rule is adopted if it does not break compatibility.

2.4 Source registry with snapshot dates

The following table is the reproducible registry of sources used to derive this standard. Snapshots were captured on 2026-04-24.

Evidence priority: agentskills.io → Anthropic docs/repos → OpenAI docs/repos → GitHub docs/blog → vendor/community sources.

2.5 Extraction categories

The source corpus yields rules in five categories: syntax/schema (frontmatter fields, name/description constraints, YAML structure); structure/layout (directory shape, optional resource folders, file references, install/discovery locations); authoring guidance (imperative style, concise descriptions, examples, templates, gotchas, verification); runtime behavior (progressive disclosure, automatic invocation from description, host-specific injection/approval behavior); and validation/limits (name/description caps, under-500-line body, one-level references, evaluation/testing guidance).

3. Consensus vs Conflicts

3.1 Consensus (all sources agree)

All cited sources consistently agree on the following:

• A skill is a directory-level artifact with a required root SKILL.md.
• SKILL.md is YAML frontmatter followed by Markdown instructions.
• name and description are the core discovery fields; both are required.
• Progressive disclosure is fundamental: metadata loaded first, body on activation, resources on demand.
• The common portable resource directories are scripts/, references/, and assets/.
• The main SKILL.md must remain short; the hard boundary repeated in the official corpus is 500 lines.
• The description must say both what the skill does and when it should trigger.
• Real testing matters: syntax validation alone is not sufficient for a production skill.

3.2 Conflict resolution table

4. Final Unified Specification

4.1 Scope

This specification defines a portable core and a host overlay boundary. A skill is portable-core compliant only if it passes Sections 5–8 with no reliance on host-specific fields, host-specific discovery paths, host-specific prompt placement, or host-specific execution policy.

4.2 Core model

A portable skill:

1. MUST be a single directory whose basename exactly equals the frontmatter name (filesystem skills).
2. MUST contain exactly one root file named SKILL.md. Case variants (skill.md, Skill.md) MUST NOT exist.
3. MUST begin SKILL.md with YAML frontmatter followed by a Markdown body.
4. MUST contain only name and description in the portable core frontmatter.
5. MUST treat description as the sole authoritative trigger surface for automatic invocation.
6. MUST use only the shared resource model: scripts/, references/, assets/.
7. MUST keep all portable file references relative, one level deep from the skill root, using forward slashes only.
8. MUST keep SKILL.md at or below 500 normalized lines.
9. MUST write all instructions in imperative or infinitive form.
10. MUST NOT rely on host-only fields or overlays to preserve its core meaning.

4.3 Overlay system

1. Core first: validate the portable core alone.
2. Overlay second: apply one host overlay per target host.
3. No semantic override: overlays MUST NOT change core name, core description, or core body meaning.
4. Additive only: overlays may add host UI metadata, discovery/install settings, invocation policy, tool dependency declarations, or host execution controls.
5. Derived artifact rule: if a host can express extensions only by mutating SKILL.md frontmatter, the mutated file is a host build artifact, not the portable source of truth.

The only officially documented in-bundle overlay file in the corpus is agents/openai.yaml for Codex. This standard reserves agents/ as the overlay namespace. All other overlay filenames are host-specific and out of portable-core scope.

4.4 Terminology and artifact model

A skill is a self-contained directory bundle that teaches an agent a reusable capability. The bundle is not merely a prompt fragment: it is a portable instructional artifact with optional scripts, references, and assets that can be loaded progressively by compatible hosts.

A portable core skill is the minimum cross-host bundle that should parse and preserve meaning across documented runtimes. It contains a root SKILL.md, only portable frontmatter, Markdown instructions, and optional portable resource directories.

A host overlay is any host-specific metadata, runtime configuration, UI hint, approval model, provenance field, or installation detail that is useful for a specific ecosystem but not part of the portable core.

A release artifact is the distributable skill bundle after validation, trigger testing, script checks, reference checks, and overlay separation. It should not contain authoring-only files unless those files are part of a documented host overlay.

A publication profile is a way to expose skill-like content outside the runtime bundle itself, such as a web-discovery skill.md. Publication profiles can describe or advertise a skill, but they do not redefine the portable runtime bundle.

The standard deliberately separates these concepts because the source corpus uses the same word, “skill,” for several related but distinct things: runtime bundles, authoring templates, marketplace packages, web-discovery documents, and host-specific plugin resources.

4.5 Conformance profiles

This standard uses profiles to separate the minimum portable runtime contract from stricter authoring, release, and host-extension requirements. Profiles are cumulative unless stated otherwise.

Profile P0 — Portable Runtime Core

P0 is the smallest profile a runtime can reliably consume without knowing any specific host implementation.

A P0 skill MUST:

• be a directory containing exactly one SKILL.md at the skill root;
• have valid YAML frontmatter;
• provide at least name and description in frontmatter;
• keep the portable frontmatter free from host-specific metadata;
• keep all referenced files inside the skill root;
• avoid symlinks, hidden files, and unsafe path traversal;
• be understandable from SKILL.md alone;
• place optional supporting material in portable directories such as scripts/, references/, and assets/.

A P0 runtime MAY ignore all files except SKILL.md, but if it does use supporting files, it MUST resolve them relative to the skill root.

Profile P1 — Strict Authoring Profile

P1 is the recommended profile for authored skills that should be readable, reviewable, and reusable across runtimes.

A P1 skill SHOULD:

• follow the canonical section order;
• provide clear activation/trigger language in the description and body;
• document preconditions, defaults, workflow, decision logic, output format, gotchas, boundaries, verification, and examples;
• use stable relative paths for supporting files;
• avoid time-sensitive claims unless they are explicitly scoped;
• avoid machine-specific assumptions unless they are marked as local examples;
• provide enough context for a model to decide when not to use the skill.

P1 is stricter than the minimum runtime core but still portable.

Profile P2 — Release-Ready Profile

P2 is the profile for skills intended for distribution, registry publication, team reuse, or production-like usage.

A P2 skill MUST satisfy P0 and SHOULD satisfy P1. It additionally requires release evidence:

• validation report;
• trigger tests;
• at least one positive example and one negative example;
• script execution evidence if scripts are included;
• resource-size review for assets and references;
• compatibility notes for claimed hosts;
• version/change notes if distributed through a registry or repository.

P2 does not mean the skill is universally safe. It means the author has supplied enough evidence for a reviewer or registry to evaluate it.

Profile H — Host Overlay Profile

Profile H covers host-specific extensions, generated artifacts, local runtime configuration, and compatibility glue.

Host overlays MAY contain:

• host manifests;
• registry metadata;
• permissions or tool allowlists;
• install hooks;
• model/runtime preferences;
• generated indexes;
• IDE or CLI integration files;
• evaluation metadata specific to a platform.

Host overlays MUST NOT mutate the portable semantic meaning of the skill. A host may adapt packaging, discovery, and execution metadata, but the portable core remains the canonical source of human/model instructions.

5. Frontmatter Schema

5.1 Portable core (source of truth)

---
name: skill-name
description: This skill should be used when… [capability clause and explicit trigger clause].
---

The portable core requires exactly name and description. No other keys are permitted.

5.2 Allowlist (portable core)

5.3 Denylist (portable core MUST NOT contain)

The portable core frontmatter MUST NOT contain any of the following keys: license, compatibility, metadata, allowed-tools, version, author, tags, requires, when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, context, agent, hooks, paths, shell, any provenance keys injected by host tooling, or any unknown top-level key.

5.3a Unknown fields policy

Any frontmatter key not in the portable core allowlist MUST be treated as a validation WARNING, not a FAIL. Runtimes MUST ignore unknown keys to preserve forward compatibility. Validators MUST report them so authors are aware. Authors SHOULD NOT include undocumented fields in the portable source SKILL.md; if a host requires additional fields, they belong in a host build artifact or an overlay file.

5.4 Optional fields (overlay-eligible)

These fields are valid in host build artifacts and host-specific overlays, but MUST NOT appear in the portable source SKILL.md:

5.5 Field constraints

name MUST satisfy all of:

• length 1–64;
• matches ^[a-z0-9]+(?:-[a-z0-9]+)*$ (lowercase, digits, single hyphens as separators);
• no leading or trailing hyphen;
• no consecutive hyphens (--);
• exact match to the parent directory basename (filesystem skills);
• no XML/HTML tags (<, >);
• not equal to anthropic or claude (case-insensitive).

description MUST satisfy all of:

• length 10–1024;
• single-line string;
• non-empty after trimming;
• no XML/HTML tags;
• third-person form;
• contains both a capability clause and an explicit trigger token from the set: Use when, Use this when, Use this skill when, Use whenever, Trigger when, Trigger whenever.

5.6 Regex definitions

NAME_REGEX        = ^[a-z0-9]+(?:-[a-z0-9]+)*$
NO_XML_TAG_REGEX  = </?[A-Za-z][^>]*>
TRIGGER_TOKEN     = (Use when|Use this when|Use this skill when|Use whenever|Trigger when|Trigger whenever)
PATH_REGEX        = ^(scripts|references|assets)/[A-Za-z0-9][A-Za-z0-9._-]*$

5.7a Formal YAML schema

The following machine-readable schema defines all validation constraints for the portable core frontmatter. This is the authoritative reference for implementing a conformant validator.

# SKILL.md Portable Core Frontmatter Schema
# Version: 2.0.0

name:
  type: string
  required: true
  minLength: 1
  maxLength: 64
  pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
  forbiddenSubstring: "--"
  forbiddenValues:
    - "anthropic" # case-insensitive
    - "claude" # case-insensitive
  forbiddenChars: ["<", ">"]
  mustMatchParentDir: true # conditional: filesystem skills only

description:
  type: string
  required: true
  minLength: 10
  maxLength: 1024
  forbiddenChars: ["<", ">"]
  mustContainTriggerToken: true
  # Recognized trigger tokens:
  # "Use when", "Use this when", "Use this skill when",
  # "Use whenever", "Trigger when", "Trigger whenever"

additionalProperties: false
# Any key not listed above is a WARNING (runtimes MUST ignore; validators MUST report)

5.8 YAML restrictions

The portable core frontmatter MUST be a single YAML mapping with exactly two scalar string values. Multiline scalars, nested mappings, lists, anchors, aliases, merge keys, and tags are forbidden in the portable core.

5.9 Source-field mapping and preservation notes

The broader source corpus contains several fields that are valid or documented in at least one ecosystem but unsafe in the closed portable core. They are preserved here as a mapping so implementers do not accidentally treat omission from the core as loss of information.

Unknown keys are never silently accepted as portable. A strict validator must report them. A runtime may ignore them, but an authoring or release gate should either remove them or move them into a documented overlay.

6. Filesystem Layout

6.1 Canonical structure

<skill-name>/
├── SKILL.md                   # REQUIRED
├── LICENSE.txt                # optional
├── scripts/                   # optional: executable code
│   └── <file>                 # self-contained; documented dependencies
├── references/                # optional: supplementary documentation
│   └── <file>                 # one level only; TOC required if >100 lines
├── assets/                    # optional: static resources, templates
│   └── <file>                 # max 5 MB per file
└── agents/                    # optional: overlay namespace only
    └── openai.yaml            # Codex overlay (OpenAI-specific)

6.2 Root allowlist

Portable-core root entries: required SKILL.md; optional LICENSE.txt, scripts/, references/, assets/, agents/. Any other top-level file or directory MUST FAIL portable-core validation. This explicitly excludes README.md, CHANGELOG.md, templates/, examples/, evals/, and tests/ from the portable bundle root.

Rationale for excluding README.md: agents may hallucinate reading README.md instead of SKILL.md, causing context window bloat and incorrect behavior. Any documentation that would go into a README MUST be placed in SKILL.md or references/.

Rationale for excluding examples/ and evals/: these are valid authoring-time artifacts and may exist in the author’s working directory, but they are not part of the distributed portable bundle.

6.3 Directory constraints

6.4 Path rules

Portable path references MUST satisfy all of: forward slashes only; no ..; no absolute paths; no Windows drive prefixes; exactly one path segment after the core directory name; target file must exist; path matches ^(scripts|references|assets)/[A-Za-z0-9][A-Za-z0-9._-]*$.

6.5 Low-level portability rules

• All text files in the portable core MUST be UTF-8.
• UTF-8 BOM MUST FAIL.
• CRLF line endings are accepted but normalized to LF before validation; bare CR MUST FAIL.
• Symlinks MUST FAIL in the portable core.
• Hidden files and hidden directories inside the skill root MUST FAIL.
• Case-insensitive filename collisions MUST FAIL.

6.6 Directory-specific rules

scripts/

The scripts/ directory is for executable or importable helpers that materially improve reliability, repeatability, or deterministic processing. A script should be included only when the body instructions alone are insufficient or would cause fragile manual work.

Rules:

• scripts must be referenced from SKILL.md or from a referenced document;
• scripts must use relative paths and must not assume a global installation path;
• scripts must fail with non-zero exit status on unrecoverable error;
• scripts should expose clear CLI usage and deterministic output;
• scripts should avoid network access unless the skill explicitly documents that requirement;
• scripts must not require credentials unless the preconditions and host permission model explicitly cover them.

references/

The references/ directory is for detailed material that should not be loaded into the model context unless needed: domain rules, long examples, schemas, compatibility tables, checklists, or procedural manuals.

Rules:

• each referenced document must have a clear reason to exist;
• SKILL.md must explain when to read each reference;
• reference files should be short enough to load selectively;
• large reference files should contain a table of contents;
• references must not contradict the root SKILL.md.

assets/

The assets/ directory is for non-instructional resources such as templates, sample inputs, images, schemas, generated fixtures, or static files used by scripts.

Rules:

• assets should be named descriptively;
• generated or bulky assets should be excluded unless required for execution;
• asset formats should be portable and documented;
• binary assets should be small enough for the target host upload/runtime limits.

agents/ and other overlay directories

Host-specific directories are allowed only as overlays. They must not be required to understand the portable skill body. If a host-specific file changes runtime behavior, the portable core must still be valid without it, or the package must be explicitly labeled as host-specific rather than portable.

7. Content Rules

7.1 Mandatory section order

The Markdown body of SKILL.md MUST contain these headings in this exact order:

# <Human-Readable Title>
## Purpose
## Preconditions
## Defaults
## Workflow
## Decision Logic
## Supporting Files
## Output Format
## Gotchas
## Boundaries
## Verification
## Examples

If a section is not applicable, its content MUST be exactly NONE.

7.2 Section rules

• # <Human-Readable Title>: one line only; matches or closely reflects the name field.
• ## Purpose: one paragraph stating scope and task outcome; MUST NOT introduce trigger criteria absent from description.
• ## Preconditions: bullet list of required tools, packages, files, credentials, or environment assumptions; otherwise NONE. Dependencies belong here because compatibility is excluded from the portable core.
• ## Defaults: states which option or mode applies when the user does not specify; mandatory when any choice point exists; the “default instead of menu” rule.
• ## Workflow: numbered list; each step MUST start with an imperative verb. Steps that execute scripts MUST name the exact scripts/<file> path.
• ## Decision Logic: a Markdown table with exact columns Condition | Action | Default. Exactly one row MUST mark Default as YES. If there is no branching, the single row is All cases | Follow Workflow | YES.
• ## Supporting Files: bullet list in the form - path — purpose — load condition, or NONE. Every referenced bundled file MUST appear here exactly once.
• ## Output Format: a fenced template or explicit prose schema. If no fixed structure exists, write exactly No fixed output format. Templates are mandatory where output structure matters.
• ## Gotchas: bullet list or NONE. Every bullet MUST start with - **Never**, - **Always**, or - **Do not**. Non-obvious pitfalls and tribal knowledge belong here.
• ## Boundaries: explicit list of unsupported cases, forbidden operations, or hard limits. NONE only if truly unlimited. This prevents the agent from attempting impossible actions.
• ## Verification: checklist format only; every item MUST start with - [ ]. States measurable completion criteria. Mandatory; cannot be NONE.
• ## Examples: exactly two subsections, ### In Scope and ### Out of Scope. In Scope shows a valid triggering example; Out of Scope shows a reject or non-triggering case.

7.3 Authoring rules

1. Instructional prose in Workflow, Decision Logic, Gotchas, and Verification MUST use imperative or infinitive form. Sentences in those sections MUST NOT begin with You or Your.
2. description and introductory prose MUST use third-person form (This skill should be used when…).
3. Terminology MUST be consistent throughout the file. The same concept MUST NOT be renamed across sections.
4. Unqualified time-sensitive words — today, tomorrow, currently, latest, recent, newest — MUST NOT appear unless the same sentence includes an ISO date (YYYY-MM-DD).
5. Machine-specific paths, Windows-style paths, and hardcoded user-home paths MUST NOT appear in portable instructions.
6. If multiple frameworks, products, or domains are supported, SKILL.md MUST route to separate references/<file> variants rather than embedding all variant detail in the body.
7. If a reference file exceeds 100 lines, it MUST include a table of contents within its first 20 lines.
8. If a reference file exceeds 10,000 words, the ## Supporting Files entry MUST include a search hint in backticks.
9. The body MUST NOT contain setup notes about how the skill was authored, tested, or published.

7.4 Trigger semantics

Automatic invocation authority is defined solely by frontmatter description. Purpose, Examples, and any other body text are secondary documentation and MUST NOT broaden or contradict the trigger boundary in description. If there is any contradiction, description wins and the skill FAILS validation.

7.5 Error-prevention patterns

7.6 Progressive disclosure rules

The root SKILL.md is the activation and routing layer, not a dumping ground. It should contain enough information for the agent to decide what to do, what to read next, and how to produce a correct output. Detailed reference material should be moved into references/, reusable operations into scripts/, and static supporting material into assets/.

A good root body answers these questions quickly:

1. What capability does this skill provide?
2. When should it activate?
3. What are the safe defaults?
4. What workflow should the agent follow?
5. What files should the agent load only under specific conditions?
6. What must the final answer contain?
7. What mistakes must be avoided?
8. How can the output be verified?

Progressive disclosure fails when SKILL.md is so large that activation itself consumes too much context, or when the root body is so vague that the agent cannot know which reference or script to load.

7.7 Description authoring rules

The description is the primary routing signal. It must be more than a short label. It should include capability, trigger conditions, and enough keywords to support semantic matching.

Preferred portable pattern:

This skill should be used when the user asks to <task>, <related task>, or <trigger context>, especially when <specific condition>.

Acceptable variants:

Use this skill when the user asks to <task>...

Use whenever the user mentions <domain>, even if they do not explicitly ask for <exact term>.

The source corpus disagrees on grammatical person. Some official guidance frames the description as an instruction to the agent (“Use this skill when…”), while Claude Code plugin-dev examples often prefer third-person phrasing (“This skill should be used when…”). This standard permits both, but the stricter house style is third-person because it avoids accidental direct user-facing wording and works well as metadata.

Bad descriptions:

Helps with PDFs.

Useful for data.

This skill contains scripts and references.

Good descriptions:

This skill should be used when the user asks to extract text or tables from PDFs, fill PDF forms, merge PDF files, or debug PDF document-processing failures.

This skill should be used when the user asks to review a database migration, inspect table relationships, validate schema changes, or identify downstream PostgreSQL compatibility risks.

7.8 Content scope rules

The root body should not include long background essays, full API references, large code listings, full benchmark reports, or exhaustive domain manuals. Those belong in references or external documentation. The root body should include operationally necessary instruction: defaults, decision logic, workflow, output contract, gotchas, verification, and examples.

The skill must not overclaim. If a skill only reviews API contracts, it should not imply it can generate clients, deploy services, or execute migrations. Boundaries are part of the specification because they reduce unsafe or irrelevant activation.

7.9 Portability clarifications for sensitive content classes

Time-sensitive content

Skills SHOULD avoid embedding facts that decay quickly, such as current pricing, current API limits, current model rankings, live legal requirements, dependency versions, or hosted-service UI paths.

If time-sensitive content is unavoidable, the skill SHOULD:

• state the date or version context;
• describe how to verify freshness;
• avoid presenting stale examples as normative requirements;
• prefer procedures for checking current truth over hard-coded claims.

Bad pattern:

Use model X because it is currently the best coding model.

Better pattern:

Select the coding model from the configured model policy. If no policy exists, compare currently available models using the project evaluation harness before changing defaults.

Machine-specific content

Portable skills MUST NOT depend on one author’s local paths, usernames, shells, package managers, editor configuration, API keys, hostnames, private repositories, or environment variables unless those details are explicitly marked as examples or moved to host/local overlays.

Bad pattern:

Run `/Users/alice/dev/project/scripts/build.sh`.

Better pattern:

Run `scripts/build.sh` from the skill root, or use the host overlay to map this step to a local project path.

Terminology consistency

A skill SHOULD use one term consistently for each concept. For example, avoid mixing skill, agent skill, plugin, workflow, and tool pack unless the distinction matters.

Recommended usage:

• skill — the portable instruction bundle;
• host — the runtime, IDE, CLI, registry, or agent platform consuming the skill;
• overlay — host-specific metadata outside the portable core;
• supporting file — scripts, references, assets, schemas, templates, or examples referenced by the skill.

Visual and document workflows

Skills for PDFs, documents, slides, images, spreadsheets, and visual inspection SHOULD explicitly say when the model must inspect rendered output rather than relying only on extracted text.

For example, a PDF skill SHOULD distinguish:

• text extraction;
• page rendering;
• table inspection;
• figure/chart inspection;
• OCR fallback;
• citation or source anchoring.

Safety and permissions

Portable skills SHOULD express required capabilities abstractly rather than binding them to a particular product permission model.

Good pattern:

Requires permission to read repository files and run local validation commands.

Overlay-specific policy can then map that requirement to an actual tool allowlist or permission grant.

8. Validation Model

Validation is a deterministic PASS/FAIL pipeline. A stage that produces FAIL stops the pipeline.

Stage 0 — normalization

1. Resolve the skill directory path.
2. Reject symlinks anywhere in the portable core.
3. Decode SKILL.md and all referenced text files as UTF-8; reject BOM.
4. Normalize CRLF to LF; reject bare CR.
5. Build a case-insensitive inventory of all root entries; reject collisions.

Stage 1 — root inventory

Is SKILL.md present at root?                                → FAIL if no
Is exactly one SKILL.md present?                            → FAIL if more than one
Are there any disallowed root entries?                      → FAIL if yes
Are there any symlinks?                                     → FAIL if yes
Are there any hidden files or directories?                  → FAIL if yes

Stage 2 — frontmatter parse

Does SKILL.md start with "---" on line 1?                   → FAIL if no
Does SKILL.md contain a closing "---"?                      → FAIL if no
Is content between "---" delimiters valid YAML?             → FAIL if no
Is the frontmatter a mapping (not a list or scalar)?        → FAIL if no

Stage 3 — required field check

Is `name` present?                                          → FAIL if no
Is `name` a string?                                         → FAIL if no
Does `name` match NAME_REGEX?                               → FAIL if no
Does `name` contain "--"?                                   → FAIL if yes
Is `name` case-insensitively "anthropic" or "claude"?       → FAIL if yes
Does `name` contain "<" or ">"?                             → FAIL if yes
Is 1 ≤ len(name) ≤ 64?                                      → FAIL if no
Is `description` present?                                   → FAIL if no
Is `description` a string?                                  → FAIL if no
Is 10 ≤ len(description.trim()) ≤ 1024?                     → FAIL if no
Does `description` contain "<" or ">"?                      → FAIL if yes

Stage 4 — denylist check

Does frontmatter contain any key not in {name, description}? → FAIL if yes

Stage 5 — directory name consistency (filesystem skills only)

Does basename(skill-dir) == name?                           → FAIL if no

Stage 6 — body check

Is there content after the closing "---"?                   → WARN if no
Is body ≤ 500 lines?                                        → WARN if exceeds
Are all mandatory sections present in correct order?        → WARN for each missing section
Are all mandatory sections with content either prose/list or "NONE"? → WARN if not
Does `## Verification` contain at least one "- [ ]" item?  → WARN if not
Does `## Decision Logic` contain a row with "YES"?          → WARN if not

Stage 7 — path check

Do any referenced file paths fail PATH_REGEX?               → FAIL if yes
Do any referenced files not exist on disk?                  → WARN if yes
Are any reference paths more than one level deep?           → FAIL if yes
Are there circular reference chains?                        → WARN if yes

Stage 8 — trigger quality check

Does `description` contain a recognized trigger token?      → WARN if no
Is `description` ≥ 10 characters (after trim)?              → FAIL if no
Does `description` appear self-contradictory vs body?       → WARN if detected

8.1 PASS/FAIL summary table

8.3 Bash-operational validation commands

The following commands can be run directly in the skill directory to operationalize the pipeline. Each returns non-zero or non-empty output on failure.

# Stage 5: directory name matches frontmatter name
[ "$(basename "$PWD")" = "$(grep '^name:' SKILL.md | head -1 | awk '{print $2}')" ] || echo "FAIL: name/dir mismatch"

# Stage 6a: no extraneous root files (README, CHANGELOG, INSTALL)
ls | grep -E -i '^(README|CHANGELOG|INSTALL)' && echo "FAIL: extraneous root files found"

# Stage 6b: body line count
[ "$(wc -l < SKILL.md)" -le 500 ] || echo "WARN: body exceeds 500 lines"

# Stage 6c: body has at least one H1 heading
grep -q '^# ' SKILL.md || echo "WARN: no H1 heading found"

# Stage 7a: asset files over 5 MB
find assets/ -type f -size +5M 2>/dev/null && echo "FAIL: asset exceeds 5 MB"

# Stage 7b: nested subdirectories in references/
find references/ -mindepth 2 -type f 2>/dev/null && echo "FAIL: references/ has nested files"

# Stage 7c: nested subdirectories in scripts/
find scripts/ -mindepth 2 -type f 2>/dev/null && echo "FAIL: scripts/ has nested files"

# Stage 0: no symlinks anywhere in portable core
find . -maxdepth 3 -type l 2>/dev/null && echo "FAIL: symlinks present"

# Stage 0: no hidden files or directories
find . -maxdepth 2 -name '.*' ! -name '.' 2>/dev/null && echo "FAIL: hidden files present"

All commands returning empty output and exit code 0 indicate the corresponding check passed.

8.4 WARNING conditions (non-blocking)

8.5 Validation pseudocode

The following pseudocode is intentionally conservative. It is not the only valid implementation, but it preserves the major checks required by this standard.

import re
from pathlib import Path

import yaml

NAME_RE = re.compile(r"^(?!.*--)[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
CORE_KEYS = {"name", "description"}
ROOT_ALLOWLIST = {"SKILL.md", "LICENSE.txt", "scripts", "references", "assets", "agents", ".overlays"}


def validate(skill_dir: Path) -> list[Issue]:
    issues: list[Issue] = []
    skill_md = skill_dir / "SKILL.md"

    if not skill_md.exists():
        return [FAIL("SKILL.md not found")]
    if not skill_md.is_file():
        return [FAIL("SKILL.md is not a regular file")]

    for path in skill_dir.rglob("*"):
        rel = path.relative_to(skill_dir)
        if path.is_symlink():
            issues.append(FAIL(f"symlink not allowed: {rel}"))
        if any(part.startswith(".") and part not in {".overlays"} for part in rel.parts):
            issues.append(FAIL(f"hidden path not allowed in portable core: {rel}"))

    for item in skill_dir.iterdir():
        if item.name not in ROOT_ALLOWLIST:
            issues.append(FAIL(f"unexpected root item: {item.name}"))

    try:
        text = skill_md.read_text(encoding="utf-8")
    except UnicodeDecodeError:
        return [FAIL("SKILL.md is not valid UTF-8")]

    if text.startswith("\ufeff"):
        issues.append(FAIL("UTF-8 BOM is not allowed"))
    if "\r" in text:
        issues.append(FAIL("CRLF/CR line endings are not allowed"))
    if not text.startswith("---\n"):
        return [FAIL("SKILL.md must start with YAML frontmatter delimiter")]

    close = text.find("\n---\n", 4)
    if close == -1:
        return [FAIL("closing YAML frontmatter delimiter not found")]

    fm_text = text[4:close]
    body = text[close + 5:]

    try:
        frontmatter = yaml.safe_load(fm_text)
    except yaml.YAMLError as exc:
        return [FAIL(f"invalid YAML frontmatter: {exc}")]

    if not isinstance(frontmatter, dict):
        return [FAIL("frontmatter must be a mapping")]

    missing = CORE_KEYS - set(frontmatter)
    for key in sorted(missing):
        issues.append(FAIL(f"missing required frontmatter key: {key}"))

    unknown = set(frontmatter) - CORE_KEYS
    for key in sorted(unknown):
        issues.append(WARN(f"non-core frontmatter key should move to overlay: {key}"))

    name = frontmatter.get("name")
    description = frontmatter.get("description")

    if not isinstance(name, str) or not name.strip():
        issues.append(FAIL("name must be a non-empty string"))
    elif not (1 <= len(name) <= 64):
        issues.append(FAIL("name must be 1-64 characters"))
    elif not NAME_RE.fullmatch(name):
        issues.append(FAIL("name does not match portable regex"))
    elif skill_dir.name != name:
        issues.append(FAIL("skill directory name must match frontmatter name"))

    if not isinstance(description, str) or not description.strip():
        issues.append(FAIL("description must be a non-empty string"))
    elif not (1 <= len(description) <= 1024):
        issues.append(FAIL("description must be 1-1024 characters"))
    else:
        lowered = description.lower()
        if len(description) < 50:
            issues.append(WARN("description is likely too short for reliable routing"))
        if not any(token in lowered for token in ("when", "use", "asks", "mentions")):
            issues.append(WARN("description may lack trigger context"))

    if not body.strip():
        issues.append(FAIL("Markdown body is empty"))

    body_lines = body.splitlines()
    if len(body_lines) > 500:
        issues.append(FAIL("Markdown body exceeds 500 lines"))
    if len(body) // 4 > 5000:
        issues.append(WARN("Markdown body may exceed 5000 tokens"))

    for required_heading in (
        "## Purpose", "## Preconditions", "## Defaults", "## Workflow", "## Decision Logic",
        "## Supporting Files", "## Output Format", "## Gotchas", "## Boundaries",
        "## Verification", "## Examples",
    ):
        if required_heading not in body:
            issues.append(FAIL(f"missing mandatory body section: {required_heading}"))

    for match in re.finditer(r"\[[^\]]*\]\(([^)]+)\)", body):
        target = match.group(1).strip()
        if target.startswith(("http://", "https://", "mailto:")):
            continue
        if target.startswith(("/", "~", "..")):
            issues.append(FAIL(f"non-portable reference path: {target}"))
            continue
        resolved = (skill_dir / target).resolve()
        if not str(resolved).startswith(str(skill_dir.resolve())):
            issues.append(FAIL(f"reference escapes skill root: {target}"))
        elif not resolved.exists():
            issues.append(FAIL(f"referenced file does not exist: {target}"))

    return issues

8.6 Extended semantic validation stages

The deterministic validation stages above are the minimum strict validation pipeline. Release-quality validators SHOULD add semantic checks that catch skills that are syntactically valid but operationally weak.

Script validation

If scripts/ exists, validators SHOULD check that:

• scripts are referenced from SKILL.md or clearly documented;
• executable scripts have the expected executable bit where the host supports it;
• scripts use portable interpreters where possible;
• scripts do not rely on absolute author-machine paths;
• scripts do not silently require secrets;
• scripts fail visibly when prerequisites are missing;
• scripts are small enough to audit or are accompanied by a clear reference explanation.

Script validation MUST distinguish between:

• portable helper scripts that are part of the skill;
• host installation scripts that belong in overlays;
• project-specific scripts that should remain outside the portable bundle.

Semantic lint

Semantic lint is non-deterministic or partially heuristic validation. It SHOULD produce warnings, not hard failures, unless a registry explicitly chooses a stricter profile.

Semantic lint SHOULD detect:

• vague descriptions that do not identify triggers;
• descriptions that are too broad and would over-activate;
• missing negative examples;
• missing boundaries;
• claims that depend on live external facts;
• references to unavailable local files;
• workflow steps that cannot be performed with declared capabilities;
• examples that contradict the stated boundaries;
• instructions that imply hidden host-specific permissions;
• duplicated content that inflates context without adding decision value.

Semantic lint is useful because skills are consumed by models, not only by parsers. A schema-valid skill can still be harmful if it teaches the model to activate at the wrong time, assume unavailable tools, or ignore verification.

Overlay boundary validation

Overlay boundary validation checks that host-specific material has not leaked into the portable core.

Validators SHOULD warn when portable SKILL.md contains:

• host names used as normative requirements rather than examples;
• IDE-specific commands as the only supported path;
• runtime-specific permission syntax;
• generated metadata;
• registry-only fields;
• local installation steps;
• private filesystem paths;
• environment-specific secrets or tokens;
• claims such as “works in host X” without corresponding overlay or test evidence.

Validators SHOULD also check that overlays do not contradict the portable core. For example, if the portable skill says scripts are optional but a host overlay makes script execution mandatory, that difference must be documented as host behavior rather than presented as portable truth.

9. Release Gate

A skill MUST pass all PASS/FAIL checks in §8.1 before release. A skill SHOULD pass all WARNING checks in §8.2. Syntactic validation alone is not sufficient.

9.1 Minimum evaluation requirements

9.2 Verification model

1. Run structural validation (§8.1)          → MUST PASS all
2. Run warning checks (§8.2)                 → REVIEW each; accept or fix
3. Run trigger evals (positive + negative)   → MUST meet thresholds in §9.1
4. Run instruction-following evals           → MUST follow ≥ 90% of steps
5. Run script execution tests                → ALL scripts MUST complete without error
6. Run edge case tests                       → MUST handle ≥ 3 documented edge cases
7. Release

9.3 Trigger testing protocol

For each skill, define a trigger test set. Positive triggers (5+): prompts that SHOULD activate the skill. Negative triggers (5+): prompts that SHOULD NOT activate the skill. Ambiguous triggers (3+): borderline prompts with documented expected behavior. All positive triggers MUST activate. All negative triggers MUST NOT activate. Ambiguous triggers are documented, not required to pass.

9.4 Script execution guarantees

• Every script in scripts/ MUST execute successfully in a clean environment matching the ## Preconditions section.
• Scripts MUST produce deterministic output for deterministic input.
• Scripts MUST exit with code 0 on success and non-zero on failure.
• Scripts MUST include error messages on failure (no silent failures).
• Scripts MUST generate LLM-friendly standard output (truncate massive payloads, suppress irrelevant stack traces, provide explicit success/failure codes).

9.5 Required release evidence

A release candidate should include evidence, either in CI logs, release notes, or an external release manifest, that the following checks were performed:

A skill must not claim compatibility with a host unless either the host’s documented validator accepts the bundle or the release evidence explains the exact compatibility boundary.

9.6 Host-compatibility claims

Compatibility claims must be precise. Avoid labels like “works everywhere” unless the artifact is limited to the portable core and has no hidden host assumptions.

Recommended labels:

• portable-core: uses only name, description, Markdown body, and portable resource directories;
• openai-overlay: includes OpenAI-specific overlay files or release metadata;
• claude-overlay: includes Claude-specific authoring or plugin metadata;
• github-overlay: includes GitHub/Copilot-specific metadata or catalog conventions;
• web-discovery-profile: intended for publication/discovery, not necessarily a runtime bundle.

A package can include multiple overlays, but each overlay must be separable from the portable core.

10. Overlay System

10.1 Portable core vs host-specific overlays

Portable core (MUST work on all hosts):

• SKILL.md with only name and description in frontmatter
• scripts/, references/, assets/ contents using portable conventions
• All file paths using forward slashes, one level deep

Host-specific overlays (outside the portable bundle or in agents/):

<skill-name>/
├── SKILL.md                    # Portable core
├── scripts/                    # Portable
├── references/                 # Portable
├── assets/                     # Portable
└── agents/
    └── openai.yaml             # Codex: interface, policy, dependencies

GitHub CLI mutations (allowed-tools, user-invocable, disable-model-invocation) are permitted only in GitHub-specific build artifacts, not in the portable source SKILL.md.

10.2 Separation rules

10.3 Migration table

10.4 Overlay manifest pattern

For projects that need rich metadata without polluting portable SKILL.md, use a release or overlay manifest outside the portable frontmatter. The exact filename is project-specific unless a host documents one. A conservative internal convention is:

<skill-name>/
├── SKILL.md
├── references/
├── scripts/
├── assets/
└── .overlays/
    ├── release.yaml
    ├── openai/
    │   └── agents/openai.yaml
    ├── claude/
    │   └── manifest.yaml
    └── github/
        └── manifest.yaml

Example release manifest:

schema_version: 1
skill_name: api-contract-review
version: 1.2.0
license: MIT
authors:
  - Example Team
compatibility:
  portable_core: true
  openai: tested
  claude: untested
  github: untested
evidence:
  frontmatter_validation: passed
  body_validation: passed
  trigger_eval: passed
  script_execution: passed

This manifest is not part of the portable runtime contract. It is packaging and release metadata. Validators may read it, but agents should not require it to understand the skill.

10.5 Recommended host overlay layout

A multi-host repository MAY use this layout:

<skill-name>/
  SKILL.md
  scripts/
  references/
  assets/
  overlays/
    openai/
      manifest.yaml
      generated/
    github/
      manifest.yaml
      gh-skill.yaml
    claude-code/
      plugin.yaml
    openclaw/
      manifest.yaml
      policy.yaml

The exact overlay directory names are not normative. The boundary is normative: host-specific files live outside the portable root contract and cannot be required to understand the portable skill.

OpenAI/Codex overlay

An OpenAI/Codex overlay may contain packaging metadata, generated indexes, validation outputs, or runtime-specific declarations required by that host.

It MUST NOT introduce portable-frontmatter keys into SKILL.md merely because a host supports them. Host metadata belongs in the overlay unless it is also valid portable core metadata.

GitHub overlay

A GitHub overlay may contain gh skill metadata, repository publication metadata, CI validation workflows, or Copilot-specific packaging artifacts.

Repository metadata such as license, changelog, release workflow, and contribution policy belongs at repository level, not inside the portable skill bundle unless the skill itself explicitly needs that material as supporting reference content.

Claude Code overlay

A Claude Code or plugin-development overlay may include plugin manifests, command registration, install hooks, local runtime configuration, and permission declarations.

Plugin lifecycle mechanics should not be treated as portable skill requirements. The portable core describes what the model should know and do; the overlay describes how one host installs, discovers, grants, or executes it.

OpenClaw/custom runtime overlay

A custom runtime overlay may include:

• tool contracts;
• permission policies;
• routing metadata;
• trigger scoring hints;
• memory-suggestion policies;
• execution sandbox declarations;
• evaluation harness metadata;
• observability configuration.

These are valid host concerns, but they must remain separable from the portable instruction bundle.

11. Final Classification

11.1 Normative requirements (MUST)

1. SKILL.md MUST exist at the root of the skill directory.
2. Frontmatter MUST be valid YAML delimited by ---.
3. Frontmatter MUST be a single mapping with exactly two keys: name and description.
4. name MUST be present, 1–64 characters, matching NAME_REGEX, no --, no <>, not reserved.
5. description MUST be present, 10–1024 characters, non-empty after trim, no <>, third-person.
6. description MUST contain a recognized trigger token.
7. For filesystem skills, directory name MUST match name.
8. Root MUST contain only allowlisted entries.
9. File references MUST use relative paths, one level deep, forward slashes.
10. Scripts MUST exit 0 on success, non-zero on failure, with error output on failure.
11. All text files MUST be UTF-8, no BOM, no bare CR.
12. SKILL.md MUST NOT contain references to host-specific fields in instructions.

11.2 Strong recommendations (SHOULD)

1. description SHOULD describe both capability and trigger, ≥ 50 characters, with specific keywords.
2. Body SHOULD be ≤ 500 lines and ≤ 5000 tokens.
3. All mandatory sections SHOULD be present in canonical order.
4. Reference files SHOULD be ≤ 1 level deep.
5. Reference files SHOULD include a table of contents if > 100 lines.
6. Scripts SHOULD be self-contained or clearly document dependencies.
7. Detailed reference material SHOULD be moved to separate files.

11.3 Optional (MAY)

1. LICENSE.txt MAY be present at root.
2. scripts/, references/, assets/ directories MAY be present.
3. agents/openai.yaml MAY be present as an OpenAI-specific overlay.
4. Additional host-specific files MAY exist in agents/ subdirectories.

11.4 Prohibited (MUST NOT)

1. name MUST NOT contain uppercase, underscores, spaces, or special characters beyond a-z, 0-9, -.
2. name MUST NOT start or end with a hyphen.
3. name MUST NOT contain consecutive hyphens (--).
4. name MUST NOT be anthropic or claude (case-insensitive).
5. name and description MUST NOT contain < or >.
6. Frontmatter MUST NOT contain any key other than name and description.
7. Root MUST NOT contain README.md, CHANGELOG.md, examples/, evals/, tests/, templates/ or any other non-allowlisted entry.
8. File reference chains MUST NOT exceed 1 hop (cascading references forbidden).
9. Scripts MUST NOT fail silently.
10. Symlinks MUST NOT appear in the portable core.

11.5 Element classification summary

11.6 Extended conflict log

The following conflict log preserves lower-level decisions from the source corpus. It is intentionally more detailed than the summary table because these conflicts are the areas where future authors are most likely to accidentally reintroduce non-portable behavior.

12A. Packaging Model

12A.1 Portable bundle

A portable bundle is the smallest distributable unit that another runtime can consume without host-specific knowledge.

A portable bundle contains:

<skill-name>/
  SKILL.md
  scripts/        # optional
  references/     # optional
  assets/         # optional

A portable bundle SHOULD NOT contain:

• repository-level documentation such as README.md or CHANGELOG.md unless explicitly allowed by a host profile;
• generated indexes;
• package-manager lockfiles;
• IDE configuration;
• host plugin manifests;
• local environment files;
• CI/CD workflow files;
• registry publication metadata.

Those files may exist in a source repository, but they are not part of the portable runtime bundle.

12A.2 Multi-skill repository

A multi-skill repository may contain many skills plus repository-level governance files.

Recommended structure:

skills-repo/
  README.md
  CHANGELOG.md
  LICENSE
  skills/
    postgres-schema-audit/
      SKILL.md
    api-contract-review/
      SKILL.md
  overlays/
    github/
    openai/
    custom-runtime/
  validators/
  tests/

In this model, repository-level files are allowed because the repository is not itself a portable skill bundle. Export tooling SHOULD be able to materialize each portable bundle independently.

12A.3 Generated host artifacts

Generated host artifacts SHOULD be reproducible from the portable core and overlay metadata.

Generated artifacts include:

• compiled registries;
• embedding indexes;
• trigger indexes;
• host manifests;
• packaged archives;
• validation reports;
• generated documentation;
• runtime cache files.

Generated artifacts SHOULD NOT be treated as source of truth. If a generated artifact contradicts SKILL.md, the portable source wins unless the host explicitly documents the artifact as an override.

12B. Migration Guide

12B.1 From Agent Skills / Anthropic-style minimal skills

Keep the existing SKILL.md as the core artifact.

Recommended migration:

• ensure name and description exist in frontmatter;
• tighten the description so it clearly identifies activation triggers;
• add missing strict-authoring sections if targeting P1;
• move large examples or references into references/;
• move host-specific metadata into an overlay;
• run deterministic validation before publishing.

12B.2 From OpenAI/Codex skills

Use the existing skill body as the portable core when possible.

Recommended migration:

• preserve portable instruction content in SKILL.md;
• move OpenAI/Codex-specific packaging, registry, or runtime metadata into overlays/openai/;
• remove non-portable frontmatter keys from the portable frontmatter;
• keep generated artifacts outside the portable bundle;
• document compatibility claims with validation evidence.

12B.3 From GitHub CLI/Copilot skills

Recommended migration:

• preserve the skill instructions in SKILL.md;
• move GitHub-specific metadata to overlays/github/;
• keep repository-level docs at repository level;
• separate CLI packaging from portable model instructions;
• ensure examples do not assume GitHub unless the skill is intentionally GitHub-specific.

12B.4 From Claude Code plugin-development style

Claude Code plugin structures often mix command registration, tool permissions, lifecycle hooks, and instruction text.

Recommended migration:

• extract model-facing instructions into SKILL.md;
• move command registration and lifecycle metadata into overlays/claude-code/;
• move permission declarations into overlay policy files;
• keep portable examples independent of one local CLI installation;
• document any host-required behavior as host-specific.

12B.5 From Skills Directory / community catalog style

Community catalogs often include rich metadata, tags, categories, screenshots, examples, and ratings.

Recommended migration:

• keep only portable runtime metadata in frontmatter;
• move catalog metadata into registry or overlay files;
• preserve useful examples in SKILL.md or references/;
• preserve screenshots or diagrams in assets/ only if they are needed for skill execution or explanation;
• do not confuse popularity metadata with runtime semantics.

12B.6 From Mintlify/web skill.md

A web-discovery skill.md is not equivalent to a portable agent skill bundle.

Recommended migration:

• treat web skill.md as discovery or documentation metadata;
• extract reusable agent instructions into a proper SKILL.md bundle;
• avoid assuming website navigation metadata is model-execution metadata;
• keep web publishing configuration outside the portable bundle;
• use rel=alternate, llms.txt, or site metadata as web-discovery mechanisms, not as the skill runtime contract.

12. Examples

12.1 Minimal portable skill

---
name: postgres-schema-audit
description: This skill should be used when the user asks to inspect a PostgreSQL schema, trace table relationships, explain column usage, or validate migration impact across related tables.
---

# Postgres schema audit

## Purpose

Audit a PostgreSQL schema and explain structural impact before changing it.

## Preconditions

- psql CLI available and connected to target database

## Defaults

Use `psql` metadata queries first. Read `references/schema-conventions.md` only when naming or relationship rules are unclear.

## Workflow

1. Inspect tables, columns, indexes, constraints, and foreign keys.
2. Identify upstream and downstream dependencies.
3. State migration risks before proposing changes.
4. Produce a concise impact summary.

## Decision Logic

| Condition                | Action                          | Default |
| ------------------------ | ------------------------------- | ------- |
| Migration proposed       | Include rollback path in output | NO      |
| All cases (no migration) | Produce structural summary only | YES     |

## Supporting Files

- `references/schema-conventions.md` — naming conventions and relationship patterns — load when naming or relationship rules are ambiguous

## Output Format

Markdown report with sections: Affected Tables, Constraints, Migration Risks (if any), Rollback Concerns (if any).

## Gotchas

- **Do not** invent schema details not visible in the live schema or bundled references.
- **Always** apply `deleted_at IS NULL` filters when querying soft-deleted tables.
- **Never** assume historical tables use `_history`; they use `_archive`.

## Boundaries

- Does not execute migrations or DDL statements.
- Does not infer undocumented semantics from column names alone.

## Verification

- [ ] Output lists all affected tables by name.
- [ ] Output lists all affected constraints.
- [ ] If a migration is proposed, output includes at least one rollback concern.

## Examples

### In Scope

User: "What would break if I drop the `orders` table?"
Expected: Structural analysis identifying foreign keys, dependent views, and migration risks.

### Out of Scope

User: "Run the migration script."
Expected: Decline; this skill does not execute DDL.

12.2 Full strict skill with overlay

---
name: api-contract-review
description: This skill should be used when the user asks to design, review, or change an API contract, compare request/response schemas, assess backward compatibility, or evaluate interface boundaries before implementation.
---

# API contract review

## Purpose

Review API contracts before implementation or release.

## Preconditions

- Access to OpenAPI or JSON Schema files
- A diff-capable shell environment

## Defaults

Use bundled schema references before proposing contract changes. Prefer backward-compatible changes. Prefer additive evolution over breaking mutation.

## Workflow

1. Read the current contract files.
2. Identify changed endpoints, fields, enums, and error shapes.
3. Classify each change as additive, behavior-changing, or breaking.
4. Check client impact, versioning impact, and migration impact.
5. Run `scripts/check_openapi_diff.py` to verify diff output.
6. Produce a decision with evidence.

## Decision Logic

| Condition                | Action                                           | Default |
| ------------------------ | ------------------------------------------------ | ------- |
| Breaking change detected | Name blast radius, migration path, rollback path | NO      |
| Additive change only     | Confirm backward compatibility and document      | YES     |

## Supporting Files

- `references/compatibility-rules.md` — versioning and compatibility policy — load when assessing backward compatibility
- `references/error-model.md` — canonical error semantics — load when evaluating error shape changes
- `scripts/check_openapi_diff.py` — structural diff helper — run in step 5

## Output Format

API Contract Review

Change Classification

…

Affected Consumers

…

Backward-Compatibility Assessment

…

Migration Recommendation

…

Unanswered Questions

…

## Gotchas
- **Do not** treat `nullable: true` and "field omitted" as equivalent.
- **Never** approve a breaking change without naming its blast radius.
- **Always** treat error-body shape changes as contract changes, even with identical HTTP status codes.
- **Do not** infer undocumented semantics from field names alone.

## Boundaries
- Does not execute schema migrations.
- Does not generate client code.
- Does not assess performance impact.

## Verification
- [ ] Output includes a change classification for each modified endpoint or field.
- [ ] Output names all affected consumers.
- [ ] Output includes a backward-compatibility assessment.
- [ ] Output includes a migration recommendation.
- [ ] Output lists explicit unanswered questions.

## Examples

### In Scope
User: "I'm adding a required field to the /orders POST body. Is that breaking?"
Expected: Classification as breaking, blast radius analysis, migration path suggestion.

### Out of Scope
User: "Generate a Python client for this API."
Expected: Decline; this skill reviews contracts, not generates clients.

Corresponding layout:

api-contract-review/
├── SKILL.md
├── references/
│   ├── compatibility-rules.md
│   └── error-model.md
├── scripts/
│   └── check_openapi_diff.py
├── assets/
│   └── contract-template.yaml
└── agents/
    └── openai.yaml

12.3 PDF processing skill pattern

This example is preserved because it demonstrates a common non-code skill with scripts, references, fallback logic, and concrete gotchas.

---
name: pdf-processing
description: This skill should be used when the user asks to extract text or tables from PDF files, fill PDF forms, merge PDF documents, debug scanned-document extraction, or work with PDF forms and OCR.
---

# PDF Processing

## Purpose

Process PDF documents reliably, including text extraction, table extraction, form inspection, form filling, OCR fallback, and merging.

## Preconditions

- Python PDF tooling is available in the target environment.
- OCR tooling is available before handling scanned PDFs.

## Defaults

Use direct text extraction first. Fall back to OCR only when direct extraction returns no useful text. Prefer deterministic scripts for form inspection and filling.

## Workflow

1. Inspect whether the PDF contains selectable text.
2. Extract text with a PDF parser when possible.
3. Detect scanned or image-only pages.
4. Use OCR fallback for scanned pages.
5. For forms, inspect fields before filling values.
6. Validate output by reopening the generated PDF or checking extracted text.

## Decision Logic

| Condition                               | Action                                     | Default |
| --------------------------------------- | ------------------------------------------ | ------- |
| `extract_text()` returns useful text    | Use direct extraction                      | YES     |
| text extraction returns empty or `None` | Use OCR fallback                           | NO      |
| PDF contains form fields                | Run field-inspection script before filling | YES     |
| merged cells break table extraction     | Use alternate table extractor              | NO      |

## Supporting Files

- `references/form-filling.md` — detailed form field mapping guide — read when filling multi-page forms.
- `references/ocr-guide.md` — OCR setup and language packs — read when direct extraction returns no useful text.
- `scripts/analyze_form.py` — extracts form field names and metadata.
- `scripts/fill_form.py` — fills fields from a values file and writes a new PDF.

## Output Format

Return a concise Markdown report with extracted text summary, extraction method used, files produced, and unresolved extraction issues.

## Gotchas

- Scanned PDFs may return `None` from direct text extraction.
- Table extraction can fail on merged cells or visually aligned columns.
- Form field names may be non-human-readable and must be inspected before filling.
- OCR language packs must match the document language.

## Boundaries

- Does not bypass password protection.
- Does not guarantee perfect OCR accuracy.
- Does not alter original PDFs in place.

## Verification

- [ ] Output file exists when a file is generated.
- [ ] Extracted text is non-empty or OCR failure is explicitly reported.
- [ ] Form fields are listed before form filling.
- [ ] The original file remains unchanged.

## Examples

### In Scope

User: "Extract text from this scanned invoice PDF."
Expected: Detect poor direct extraction, use OCR fallback, report confidence and unresolved pages.

### Out of Scope

User: "Remove the password from this protected PDF."
Expected: Decline; password bypass is outside the skill boundary.

13. Compliance Tiers

Skills may conform to this standard at one of four levels. Tooling, registries, and review processes should communicate which tier is required.

A skill distributed through a public registry SHOULD meet at minimum the Standard tier. Skills used in production automation SHOULD meet the Strict tier.

14. Limitations

1. No live runtime validation: compatibility is inferred from official specifications, documentation, product guidance, and documented validation behavior, not from runtime black-box tests. The conservative decisions around allowed-tools and GitHub-specific fields are intentional.

2. Experimental fields: allowed-tools is marked experimental in the spec. Its behavior across runtimes is not guaranteed.

3. Token counting imprecision: the “≤ 5000 tokens” recommendation is approximate. Different tokenizers produce different counts. Validators should use the target runtime’s tokenizer; otherwise, approximately 1 token ≈ 4 characters for English text.

4. GitHub provenance metadata: GitHub gh skill writes provenance metadata into frontmatter, but no stable public schema contract exists for those auto-generated keys. They are not included in the canonical author-written schema.

5. No versioning mechanism: the current spec does not define a versioning mechanism for skills. This standard does not introduce one.

6. No namespacing for skill names: the name field has no namespace mechanism; collision between skills from different authors is possible and is a known gap not addressed by any scraped source.

7. Overlay filenames for Claude Code and GitHub: only agents/openai.yaml is explicitly documented. Claude Code and GitHub overlay filenames are classified as UNKNOWN and out of portable-core scope until separately documented.

8. WASM/WASI compilation: this specification covers native scripts and Markdown definitions. Advanced sandboxed runtimes (such as OpenSkills’ WASM execution environment) require external compilation steps — for example, compiling JS/TS to .wasm components — which fall outside the scope of raw SKILL.md parsing and are not addressed here.

9. Dynamic context: this standard cannot statically guarantee that an agent will choose to read a specific reference file. Authors must rely on strong trigger descriptions within SKILL.md and explicit ## Supporting Files entries to guide the model toward the correct resources.

15. Implementation Notes for Validators and Registries

15.1 Validator behavior

A validator should distinguish hard failures from authoring warnings. Hard failures indicate the bundle is invalid as a strict portable skill. Warnings indicate portability risk, weak trigger quality, vague descriptions, excessive context weight, untested scripts, or host-specific material that should be moved to an overlay.

Recommended validator outputs:

• machine-readable JSON for CI;
• human-readable Markdown for review;
• stable issue codes for suppression and regression tracking;
• explicit path, line, and rule identifier where possible.

Example issue shape:

{
  "severity": "FAIL",
  "code": "FM_UNKNOWN_CORE_KEY",
  "path": "SKILL.md",
  "line": 4,
  "message": "Top-level frontmatter key 'version' is not part of the portable core. Move it to release metadata or a host overlay."
}

15.2 Registry behavior

A registry should not rewrite portable SKILL.md in place to inject provenance, catalog tags, install metadata, analytics fields, or UI hints. If metadata is needed, store it outside the bundle or inside a clearly separated overlay. Mutation of SKILL.md is allowed only when the target registry is explicitly host-specific and no portable compatibility claim is made.

15.3 Authoring-time artifacts

Authoring-time artifacts are valuable but should not be confused with the runtime bundle. Examples include drafts, eval datasets, test fixtures, CI configs, changelogs, contribution guides, screenshots, and benchmark notes. They may live beside the source project, but strict release packaging should include only the runtime bundle and documented overlays.

15.4 Preservation policy

This standard preserves source material by classification rather than by verbatim appendix. When two sources express the same rule differently, the rule is stated once in canonical language. When sources conflict, the rejected alternative is retained in conflict logs, mapping tables, migration tables, or limitations. When a source provides a useful example, the example is normalized into the strict body template rather than copied as an incompatible fragment.

16. Consolidation Notes

This merged standard intentionally uses the larger strict document as the canonical base and integrates the unique high-value material from the smaller consolidated document. The merge preserves strict validation logic, source-priority rules, conflict tables, examples, schemas, validation commands, release-gate evidence, classification tables, overlay boundaries, packaging rules, and migration guidance.

Material was not removed merely because it was verbose. Content should be removed only when it is true duplication, contradicted by the normative model, or belongs exclusively in host-specific overlays.

The resulting standard is intentionally standards-heavy. Its purpose is not to be the smallest possible authoring guide; it is to be a canonical reference that can support validators, registries, authoring tools, runtime implementers, and human reviewers.