Skill Template Format for Portable SKILL.md Files: A Complete Guide

The skill template format for portable SKILL.md files requires YAML front‑matter defining metadata keys (skill, title, description, author, version) followed by standardized markdown sections including Overview, Parameters, and Example Usage to enable automatic discovery, versioning, and execution.

The rohitg00/ai-engineering-from-scratch repository establishes a strict skill template format for portable SKILL.md files that powers the curriculum's skill runtime and discovery system. Every portable skill resides in a dedicated directory containing a SKILL.md file that serves dual purposes as human-readable documentation and machine-parseable configuration. This standardized structure allows the skill-catalog-builder to automatically generate registries, discovery UIs, and progressive disclosure hints without manual intervention.

Required YAML Front-Matter Structure

Every SKILL.md file must begin with a YAML front‑matter block enclosed between triple dashes. The repository tooling, specifically scripts/audit_lessons.py and site/build.js, parses these fields to validate and index skills.

The following metadata keys are required:

• skill: The canonical identifier (slug) used to invoke the skill via the runtime.
• title: A human-readable name displayed in discovery interfaces.
• description: A concise one-sentence summary of the skill's purpose.
• author: The creator or maintainer of the skill.
• version: Semantic version string (e.g., 1.0.0) for tracking changes.
• tags: Optional list of categorical keywords for filtering and discovery.

Standardized Markdown Sections

After the front‑matter, the document follows a predictable structure to ensure consistency across the curriculum.

Title Header

The first markdown heading must be an H1 (#) that mirrors the title defined in the front‑matter. This provides immediate visual confirmation for learners browsing the repository directly.

Overview Section

The ## Overview section contains free-form prose explaining the skill's purpose, typical use cases, and high-level concepts. This section answers what the skill does and when to use it, providing essential context before implementation details.

Parameters Table

The ## Parameters section defines the skill's contract using a markdown table with four columns: name, type, required, and description.

Column	Description
name	The parameter key used in invocation calls.
type	Expected data type (string, number, boolean, etc.).
required	Boolean indicating if the parameter must be provided.
description	Human-readable explanation of the parameter's purpose.

Skills that require no input should explicitly state this with a row indicating none or false for required.

Example Usage Section

The ## Example Usage section provides a minimal, runnable code snippet demonstrating how to invoke the skill. The example typically uses the language of the enclosing lesson or a pseudo-code representation of the skill runtime interface.

Optional Sections

Two additional sections enhance documentation when relevant:

• ## Implementation Details: Notes about underlying algorithms, performance characteristics, or required runtime assets.

• ## License / Attribution: Legal information, particularly important when skills reuse external material or datasets.

Validation and Build Tooling

The repository enforces the skill template format through automated scripts:

• scripts/audit_lessons.py: Validates the presence and syntactic correctness of YAML front‑matter across all SKILL.md files in the repository. It ensures mandatory fields exist and conform to expected types.
• site/build.js: Generates the public skill catalog by parsing every SKILL.md file. This build script consumes the front‑matter to create discovery interfaces and links to implementation files.

Concrete Implementation Examples

The repository demonstrates this template through several reference implementations.

Minimal Skill Example

Located at skills/start-learning/SKILL.md, this example shows the minimal required structure:

---
skill: hello-world
title: Hello World Skill
description: Returns a greeting string.
author: rohitg00
version: 1.0.0
tags: [example, greeting]
---

# Hello World Skill

## Overview

A trivial skill that returns "Hello, World!" when invoked. Useful as a sanity-check for the skill-runtime pipeline.

## Parameters

| name | type | required | description |
|------|------|----------|-------------|
| none | – | false | This skill takes no input. |

## Example Usage

```python
from skill_runtime import invoke

result = invoke("hello-world")
print(result)   # → Hello, World!

Implementation Details

The implementation lives in outputs/hello-world/main.py and simply returns a constant string.

### Parameterized Skill Example

The [`skills/learn/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/learn/SKILL.md) and [`phases/13-tools-and-protocols/27-skill-evals-packaging-and-portability/outputs/skill-release-gate/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/13-tools-and-protocols/27-skill-evals-packaging-and-portability/outputs/skill-release-gate/SKILL.md) demonstrate skills requiring inputs:

```markdown
---
skill: math-adder
title: Math Adder
description: Adds two numbers and returns the sum.
author: rohitg00
version: 1.2.0
tags: [math, arithmetic]
---

# Math Adder

## Overview

Adds the numeric values of `a` and `b`. Demonstrates parameter handling and type conversion.

## Parameters

| name | type | required | description |
|------|------|----------|-------------|
| a | number | true | First addend. |
| b | number | true | Second addend. |

## Example Usage

```typescript
import { invoke } from "skill-runtime";

const sum = await invoke("math-adder", { a: 5, b: 7 });
console.log(sum); // 12

Implementation Details

Implemented in TypeScript under outputs/math-adder/main.ts. The runtime validates that both parameters are numbers before performing the addition.

## Summary

- The skill template format for portable SKILL.md files requires mandatory YAML front‑matter with `skill`, `title`, `description`, `author`, and `version` keys.
- Documents must include standardized H1 titles and sections for Overview, Parameters (as tables), and Example Usage.
- Optional sections like Implementation Details and License/Attribution provide additional context when needed.
- [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validates front‑matter compliance, while [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) generates the skill catalog from these files.
- Reference implementations in [`skills/start-learning/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/skills/start-learning/SKILL.md) and the skill-release-gate pipeline demonstrate the template in production contexts.

## Frequently Asked Questions

### What happens if a SKILL.md file is missing required front‑matter keys?

The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validation script will fail the CI pipeline, preventing incomplete skills from entering the curriculum catalog. The script specifically checks for the presence of `skill`, `title`, `description`, `author`, and `version` fields, ensuring every portable skill carries sufficient metadata for discovery and execution.

### Can I add custom metadata fields to the YAML front‑matter?

While the front‑matter parser in [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) only consumes the standard keys (`skill`, `title`, `description`, `author`, `version`, `tags`), additional custom fields will not break validation. However, custom fields will be ignored by the catalog builder unless you modify the build script to recognize them, so it is best practice to stick to the defined schema for maximum compatibility.

### How does the skill runtime use the Parameters table?

The Parameters table serves as documentation for humans and as a contract reference for developers, but the actual runtime validation logic resides in the skill's implementation code (e.g., [`outputs/hello-world/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/outputs/hello-world/main.py)). The runtime does not dynamically parse the markdown table; instead, developers must ensure their implementation matches the documented parameters to prevent invocation errors.

### Where can I find examples of skills used in production pipelines?

The [`phases/13-tools-and-protocols/27-skill-evals-packaging-and-portability/outputs/skill-release-gate/SKILL.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/13-tools-and-protocols/27-skill-evals-packaging-and-portability/outputs/skill-release-gate/SKILL.md) file demonstrates a skill integrated into the CI release-gate pipeline. This example shows how the standard template accommodates complex validation logic while maintaining the portable, machine-readable structure required for automated curriculum deployment.

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