Agent Skills Contract (SKILL.md) Format and Portability Requirements

The Agent Skills Contract defines a portable markdown specification using strict YAML front-matter for identity metadata and a procedural body for implementation, ensuring skills remain host-agnostic and structurally loadable across different environments.

The rohitg00/ai-engineering-from-scratch repository establishes a strict portability standard for agent capabilities through the Agent Skills Contract defined in SKILL.md files. This specification treats each skill as a directory bundle where SKILL.md serves as the canonical entry point, separating portable metadata from host-specific implementation details to guarantee cross-platform compatibility.

YAML Front-Matter Specification

The contract begins on line 1 with --- delimiters and follows a strict schema defined in phases/13-tools-and-protocols/22-skills-and-agent-sdks/outputs/skill-contract-reviewer/references/contract.md. The front-matter must be entirely self-contained and must not include any host-specific runtime configuration.

Required Identity Fields

Every portable contract must declare these exact fields:

• name: String identifier limited to 64 characters. Must contain only lower-case letters, digits, and single hyphens, and must exactly match the skill-bundle directory name.
• description: Summary text limited to 1024 characters that explicitly states when the skill is useful.
• license: SPDX-compatible license identifier (e.g., MIT, Apache-2.0) defining the legal terms of use.

Optional Metadata Fields

These fields extend the contract without breaking portability:

• compatibility: Platform or version constraints as a string of 1–500 characters.
• metadata: Flat mapping of string keys to string values for arbitrary annotations.
• allowed-tools: Experimental space-separated list of permitted tool identifiers. Hosts must verify behavior independently.

The closing --- delimiter must appear on its own line. All fields not listed above are prohibited within the portable contract and must be placed in separate reference files or host-specific adapters.

Markdown Body and Asset References

After the front-matter delimiter, the file contains free-form procedural markdown describing the skill's operation. According to the specification in skills/learn-agent-skills/SKILL.md, the body may reference three standard subdirectories:

• references/: Auxiliary markdown, JSON, or script contracts that supplement the main procedure.
• scripts/: Executable validation or helper scripts, such as check_skill.py, used by the reviewer or host adapters.
• assets/: Static data including templates, manifests, or configuration snippets.

The body must not embed host-specific command syntax, assume a particular working directory, or contain hardcoded paths that vary by environment. Host-specific extensions belong in the scripts/ or references/ directories, not inline within the portable contract.

Portability Checklist and Constraints

The canonical portability requirements reside in phases/13-tools-and-protocols/22-skills-and-agent-sdks/outputs/skill-contract-reviewer/references/contract.md. A skill must satisfy the following structural constraints before it is considered portable:

• The bundle is a directory containing a regular file named exactly SKILL.md.
• Front-matter starts on the first line with --- and closes with a line containing only ---.
• The name field obeys length and character rules and matches the bundle directory name.
• The description field obeys length limits and clearly articulates the skill's usefulness.
• Optional fields meet their respective size constraints if present.
• Host-specific extensions are clearly distinguishable from the portable contract, residing in external files rather than the YAML front-matter.

Passing this checklist guarantees the package is structurally loadable but explicitly does not grant filesystem, network, secret, subprocess, or tool authority.

Validation and Enforcement Flow

When a new skill is proposed, the skill-contract-reviewer validates compliance before the skill can be executed on any host. The reviewer logic, documented in phases/13-tools-and-protocols/22-skills-and-agent-sdks/outputs/skill-contract-reviewer/SKILL.md, executes the following sequence:

1. Set SKILL_ROOT to the absolute directory of the installed bundle.
2. Resolve the target workspace as TARGET_ROOT.
3. Read contract.md and validate the portable identity fields against the schema.
4. Execute scripts/check_skill.py to produce a JSON validation report indicating structural compliance.

If check_skill.py reports any validation errors, the skill must be corrected before deployment. The skill-release-gate skill in phases/13-tools-and-protocols/27-skill-evals-packaging-and-portability/outputs/skill-release-gate/SKILL.md enforces these rules before any release is authorized.

Minimal SKILL.md Example

Below is a compliant, fully portable SKILL.md that satisfies all contract requirements:

---
name: my-first-skill
description: >
  A demonstration skill that prints a greeting when invoked.
license: MIT
---

# My First Skill

When executed, this skill prints “Hello, world!” to the console.

```text
python3 -c "print('Hello, world!')"

The script scripts/run.sh (not part of the portable contract) can be used by a host adapter to actually run the command.

This example illustrates the separation of concerns: the front-matter contains only portable metadata, the body contains descriptive procedures without host-specific syntax, and any executable wrapper ([`scripts/run.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/run.sh)) remains external to the contract itself.

## Summary

- **Agent Skills Contract** ([`SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/SKILL.md)) uses strict YAML front-matter for metadata and markdown for procedural instructions.
- Required fields include `name` (≤64 chars, specific format), `description` (≤1024 chars), and SPDX `license`.
- Host-specific configuration is prohibited in the front-matter and must be isolated in `references/`, `scripts/`, or `assets/`.
- The `skill-contract-reviewer` validates structural loadability via [`scripts/check_skill.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_skill.py), but portability does not imply runtime authority.
- All fields outside the specified schema are forbidden in the portable contract per [`contract.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/contract.md).

## Frequently Asked Questions

### What is the maximum length for a skill name in SKILL.md?

The `name` field must not exceed 64 characters and can contain only lower-case letters, digits, and single hyphens. It must also exactly match the skill-bundle directory name to ensure structural integrity during validation.

### Can I include host-specific API keys in the YAML front-matter?

No. The portable contract explicitly prohibits host-specific runtime configuration, including secrets or API keys, within the YAML front-matter. These must be handled by host-specific adapters or placed in separate files outside the portable contract boundary.

### How does the skill-contract-reviewer validate a new skill?

The reviewer sets `SKILL_ROOT` to the bundle directory, resolves `TARGET_ROOT`, validates the front-matter schema against [`contract.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/contract.md), and runs [`scripts/check_skill.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_skill.py) to generate a JSON validation report. Any errors must be resolved before the skill is deemed portable.

### What is the difference between structural loadability and runtime authority?

Structural loadability means the skill bundle follows the correct format and can be parsed by a host, as verified by the portability checklist. Runtime authority refers to permissions like filesystem access, network calls, or subprocess execution, which are not granted by the contract itself and must be configured separately by the host environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}