# Agent Skills Open Standard File Structure: Complete Specification for AI-Ready Skills

> Explore the Agent Skills open standard file structure, detailing the mandatory SKILL.md scripts resources and examples directories for AI-ready skills development. Get the complete specification.

- Repository: [Google Labs Code/stitch-skills](https://github.com/google-labs-code/stitch-skills)
- Tags: api-reference
- Published: 2026-07-12

---

**The Agent Skills open standard mandates that every skill reside in a `skills/<skill-name>/` directory containing exactly four mandatory components: a [`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md) file for metadata and workflow, a `scripts/` directory for executables, a `resources/` directory for static assets, and an `examples/` directory for reference inputs.**

The `google-labs-code/stitch-skills` repository defines this specification to standardize how AI agents discover and execute development capabilities. By enforcing a consistent file structure, the standard ensures that agents such as Codex, Gemini CLI, Claude Code, or Cursor can parse skill definitions, run validation scripts, and access knowledge resources without custom integration logic for each tool.

## The Four Mandatory Components

Every skill must contain four specific items at the root of its directory. According to the repository source code, these components are non-optional and must be present for compliance【/cache/repos/github.com/google-labs-code/stitch-skills/main/README.md#L55-L63】.

### SKILL.md: The Mission Control File

The [`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md) file serves as the primary interface declaration. It contains YAML frontmatter specifying the skill name, description, and allowed tools, followed by a step-by-step workflow that the agent follows.

```yaml
---
name: my-example-skill
description: Demonstrates the required Agent Skills file layout.
allowed-tools:
  - "Read"
  - "Write"
---

# My Example Skill

1. **Read** the input prompt.
2. **Run** `scripts/validate.ts` to ensure the prompt meets basic criteria.
3. **Provide** the enhanced prompt back to the user.

```

This file acts as the contract between the agent and the skill, defining precisely which tools the agent may use and the execution sequence.

### scripts/: Executable Enforcers

The `scripts/` directory houses runnable helpers that perform validation, networking, or automation tasks. Each script corresponds to a specific supporting task that the skill invokes during execution.

```ts
// scripts/validate.ts
export function validate(prompt: string): boolean {
  // Simple validation: ensure the prompt contains a verb.
  return /\b(create|build|design)\b/i.test(prompt);
}

```

Scripts can be written in any language (TypeScript, JavaScript, Bash, etc.) provided they are executable and referenced correctly from [`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md).

### resources/: Knowledge-Base Assets

The `resources/` directory contains static knowledge assets such as checklists, style guides, design tokens, or reference documents that the skill reads at runtime.

```markdown
<!-- resources/checklist.md -->

# Prompt Checklist

- [ ] Does the prompt specify a platform (web/mobile)?
- [ ] Does it include a visual style adjective?
- [ ] Are any required components mentioned?

```

These files provide contextual grounding that helps the agent maintain consistency with project standards.

### examples/: Gold-Standard References

The `examples/` directory supplies syntactically valid input specimens that illustrate correct usage of the skill. Developers can copy-paste these to test functionality or understand expected inputs.

```markdown
<!-- examples/sample-prompt.md -->
Create a clean landing page for a fintech startup with a blue accent color.

```

## Repository Organization and Plugin Architecture

Skills are organized into **plugins**, which group related capabilities. Each plugin contains a [`plugin.json`](https://github.com/google-labs-code/stitch-skills/blob/main/plugin.json) file and a `skills/` folder housing individual skill directories【/cache/repos/github.com/google-labs-code/stitch-skills/main/README.md#L27-L52】.

The top-level repository structure follows this pattern:

```

plugins/
├── stitch-design/
│   ├── plugin.json
│   └── skills/
│       ├── code-to-design/
│       ├── generate-design/
│       ├── manage-design-system/
│       ├── extract-design-md/
│       ├── extract-static-html/
│       └── upload-to-stitch/
├── stitch-build/
│   ├── plugin.json
│   └── skills/
│       ├── react-components/
│       ├── react-native/
│       ├── remotion/
│       └── shadcn-ui/
└── stitch-utilities/
    ├── plugin.json
    └── skills/
        ├── design-md/
        ├── enhance-prompt/
        ├── stitch-loop/
        └── taste-design/

```

The [`plugin.json`](https://github.com/google-labs-code/stitch-skills/blob/main/plugin.json) file declares the plugin's identity and entry points for the marketplace, while the `skills/` subdirectory contains the compliant skill folders.

## Implementing a Compliant Skill

To create a new skill called `my-example-skill` within a plugin named `my-plugin`, scaffold the following structure:

```text
plugins/
└── my-plugin/
    ├── plugin.json
    └── skills/
        └── my-example-skill/
            ├── SKILL.md
            ├── scripts/
            │   └── validate.ts
            ├── resources/
            │   └── checklist.md
            └── examples/
                └── sample-prompt.md

```

Ensure that:
- [`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md) includes valid YAML frontmatter with `name`, `description`, and `allowed-tools` fields
- `scripts/` contains files referenced in the workflow steps
- `resources/` and `examples/` directories exist even if empty (directories must be present)

## Summary

- **Agent Skills** standardizes AI agent interactions through a strict file structure defined in the `google-labs-code/stitch-skills` repository.
- Every skill requires four mandatory components: [`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md), `scripts/`, `resources/`, and `examples/`.
- Skills reside within plugin directories that contain a [`plugin.json`](https://github.com/google-labs-code/stitch-skills/blob/main/plugin.json) manifest and a `skills/` folder.
- The [`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md) file declares the execution pipeline and allowed tools via YAML frontmatter.
- This structure enables automatic discovery by agents including Codex, Gemini CLI, Claude Code, and Cursor.

## Frequently Asked Questions

### What is the purpose of the SKILL.md file?

The [`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md) file acts as the mission control document for each skill. It declares the skill's metadata (name, description), specifies which tools the agent is permitted to use, and provides the step-by-step workflow the agent must follow. According to the source code, this file is mandatory and serves as the primary interface for agent discovery and execution.

### Are scripts mandatory in the Agent Skills structure?

Yes, the `scripts/` directory is mandatory even if a skill does not require custom validation or automation. The directory must exist at `skills/<skill-name>/scripts/` to maintain compliance with the open standard. If no custom scripts are needed, the directory can remain empty, though most implementations include at least a validation script referenced in [`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md).

### How do plugins relate to skills in this standard?

Plugins are organizational containers that group related skills together. Each plugin contains a [`plugin.json`](https://github.com/google-labs-code/stitch-skills/blob/main/plugin.json) file declaring its identity and a `skills/` subdirectory that houses individual skill folders. This architecture allows the marketplace to categorize capabilities (such as `stitch-design` for design tasks or `stitch-build` for build tasks) while maintaining consistent discovery paths across the ecosystem.

### Can I use any programming language for the scripts?

Yes, the Agent Skills open standard is language-agnostic regarding the `scripts/` directory contents. You may use TypeScript, JavaScript, Python, Bash, or any other executable format provided the script can be invoked as specified in the [`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md) workflow. The standard only enforces the directory structure, not the implementation language of the scripts themselves.