# SKILL.md File Structure and Format in Agent-Skills: Complete Guide > Learn the SKILL.md file structure and format for Agent-Skills. Discover how to define skill name, description, overview, when to use, core process, and verification for automatic agent discovery. - Repository: [Addy Osmani/agent-skills](https://github.com/addyosmani/agent-skills) - Tags: how-to-guide - Published: 2026-04-16 --- **SKILL.md files must be placed at `skills//SKILL.md` with required YAML front-matter defining the skill's name and description, followed by standard markdown sections including Overview, When to Use, Core Process, and Verification to enable automatic discovery by OpenCode agents.** In the `addyosmani/agent-skills` repository, each skill is defined by a single [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) file that serves as the authoritative source for agent behavior. These files follow a strict schema to ensure OpenCode agents can automatically discover, parse, and execute the skill correctly. ## File Location and Naming Requirements Every skill must reside in its own directory under the `skills/` folder with an exact filename of [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) (all caps). According to [`AGENTS.md`](https://github.com/addyosmani/agent-skills/blob/main/AGENTS.md), the file must be located at: ```text skills//SKILL.md ``` The directory name must use **kebab-case** (e.g., `test-driven-development`) and must match the `name` field defined in the file's front-matter. The uppercase [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) naming convention is mandatory—variations like [`skill.md`](https://github.com/addyosmani/agent-skills/blob/main/skill.md) or [`Skill.md`](https://github.com/addyosmani/agent-skills/blob/main/Skill.md) will not be recognized by the discovery mechanism. ## Required YAML Front-Matter Structure Every [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) must begin with YAML front-matter enclosed in triple dashes. As specified in [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md), the front-matter requires exactly two fields: - **`name`**: Lowercase, hyphen-separated string matching the containing directory name - **`description`**: Third-person statement explaining what the skill does and when to use it, including a clear "Use when …" trigger (max 1024 characters) ```yaml --- name: test-driven-development description: Guides agents through Red-Green-Refactor testing. Use when implementing new logic, fixing bugs, or changing behavior. --- ``` The description must start with a third-person statement of purpose and include explicit usage triggers so the OpenCode runtime can determine when to invoke the skill. ## Standard Markdown Sections Following the front-matter, [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md) recommends a specific section structure to maintain consistency across all skills: ### Overview and When to Use Begin with an H1 title matching the skill name, followed by an **## Overview** section with 1–2 sentences describing the skill's value. The **## When to Use** section should contain bullet lists of positive triggers and optional "NOT for …" exclusions to prevent inappropriate application. ### Core Process and Specific Techniques The **## Core Process / Workflow** section should provide numbered steps, optional ASCII flowcharts, and code snippets. Follow this with **## Specific Techniques / Patterns** for deeper guidance, templates, and configuration examples. ### Rationalizations, Red Flags, and Verification Complete the structure with: - **## Common Rationalizations**: A table mapping excuses to realities - **## Red Flags**: Signs indicating the skill is being violated - **## Verification**: A checklist with evidence requirements ## Context Efficiency and File Size Limits To optimize token usage during agent execution, [`AGENTS.md`](https://github.com/addyosmani/agent-skills/blob/main/AGENTS.md) enforces strict context-efficiency guidelines. Keep the main [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) under **500 lines** and preferably under **100 lines** when possible. Write concise, actionable steps using progressive disclosure—move bulky reference material to separate files and link to them from the main document. ## Supporting Files and Scripts When the main file would exceed approximately 100 lines, requires large reference material, or ships with executable tooling, place supporting files in the skill directory. Supporting markdown files must use **kebab-case.md** naming. Executable scripts must be placed in a `scripts/` folder within the skill directory (e.g., [`skills/shipping-and-launch/scripts/deploy.sh`](https://github.com/addyosmani/agent-skills/blob/main/skills/shipping-and-launch/scripts/deploy.sh)). These Bash scripts must include `#!/bin/bash` and `set -e` for error handling. Reference scripts from the [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) using relative paths, but **never** paste script contents directly into the markdown file. ```markdown ## Usage ```bash bash /mnt/skills/user/shipping-and-launch/scripts/deploy.sh --env=prod ``` ``` ## Complete SKILL.md Examples ### Minimal Skeleton ```markdown --- name: test-driven-development description: Guides agents through Red-Green-Refactor testing. Use when implementing new logic, fixing bugs, or changing behavior. --- # Test-Driven Development ## Overview Write failing tests first, make them pass, then refactor. Guarantees correctness and guards regressions. ## When to Use - Adding a new feature - Fixing a bug - Refactoring risky code - NOT for quick one-off scripts without test harness ## Core Process 1. Write a failing test that captures the desired behavior. 2. Run the test suite and confirm the new test fails. 3. Implement the minimal code to make the test pass. 4. Run the full test suite; ensure all pass. 5. Refactor the implementation while keeping tests green. 6. Commit with a descriptive message. ## Specific Techniques - **Beyoncé Rule** – keep test files under 200 LOC. - **Test Pyramid** – 80 % unit, 15 % integration, 5 % end-to-end. ## Common Rationalizations | Rationalization | Reality | |---|---| | "I'll add tests later." | Missing tests = undiscovered bugs. | | "Tests slow CI." | Fast unit tests keep CI feedback quick. | ## Red Flags - No failing test before code changes. - Tests that pass without assertions. ## Verification - [ ] All new tests pass locally. - [ ] CI runs `npm test` with 0 failures. - [ ] Coverage for new code ≥ 80 %. ``` ### Advanced Example with Script Reference ```markdown --- name: shipping-and-launch description: Provides a checklist for safely releasing production code. Use when preparing a new version for deployment, especially behind feature flags. --- # Shipping and Launch ## Overview A pre-launch checklist that ensures feature-flag safety, monitoring, and rollback plan. ## When to Use - Deploying a major version. - Enabling a feature flag for the first time. - Performing a staged rollout. ## Core Process 1. Verify all unit, integration, and e2e tests pass (`npm test`). 2. Run performance benchmarks (`./scripts/benchmark.sh`). 3. Tag the commit (`git tag -a vX.Y.Z -m "release"`). 4. Push to `main` and create a PR for release branch. 5. Deploy to staging; run smoke tests. 6. Enable feature flag for 0 % → 10 % → 100 % traffic, monitoring key metrics. 7. If any alert fires, rollback via `git revert` and feature-flag toggle. ## Usage ```bash bash /mnt/skills/user/shipping-and-launch/scripts/deploy.sh --env=prod ``` ## Output ```json { "status": "deployed", "version": "v2.4.1", "metrics": { "errorRate": 0.01, "latencyP95": "120ms" } } ``` ## Present Results to User > **Release v2.4.1** deployed successfully. Error rate 0.01 %, P95 latency 120 ms. No alerts triggered. ## Troubleshooting - **Failed smoke test** – ensure all environment variables are set. - **Rollback failed** – verify the previous tag exists and redeploy. ``` ## Summary - **Location**: Place [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) exactly at `skills//SKILL.md` using kebab-case directory names. - **Front-matter**: Include required `name` and `description` fields in YAML format, with the description written in third-person including "Use when" triggers. - **Sections**: Follow the standard structure: Overview, When to Use, Core Process, Specific Techniques, Common Rationalizations, Red Flags, and Verification. - **Size limits**: Keep the file under 500 lines; move large content to supporting files referenced from the main document. - **Scripts**: Store executable code in `scripts/*.sh` files and reference them from the markdown rather than embedding them. ## Frequently Asked Questions ### What is the exact filename required for skill definitions? The file must be named exactly [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) in all capital letters. Variations such as [`skill.md`](https://github.com/addyosmani/agent-skills/blob/main/skill.md), [`Skill.md`](https://github.com/addyosmani/agent-skills/blob/main/Skill.md), or any other case combination will not be recognized by the OpenCode discovery mechanism according to [`AGENTS.md`](https://github.com/addyosmani/agent-skills/blob/main/AGENTS.md). ### How should the description in the front-matter be formatted? The description must be written in third person, state what the skill does, and include a clear "Use when …" trigger indicating specific scenarios for invocation. The description is limited to 1024 characters and must accurately summarize the skill's purpose for the OpenCode runtime. ### Can executable scripts be included inside the SKILL.md file? No. Executable scripts must be placed in a `scripts/` subdirectory within the skill folder (e.g., `skills//scripts/`). The [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md) should reference these scripts using relative paths in code blocks, but never contain the script contents directly to maintain context efficiency and proper separation of concerns. ### What is the maximum recommended length for a SKILL.md file? The file should not exceed 500 lines total. For optimal context efficiency, aim to keep it under 100 lines when possible. If the content requires more space, move bulky reference material, large tables, or extended examples to separate supporting files using kebab-case naming and link to them from the main [`SKILL.md`](https://github.com/addyosmani/agent-skills/blob/main/SKILL.md).