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

The Agent Skills open standard mandates that every skill reside in a skills/<skill-name>/ directory containing exactly four mandatory components: a 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 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.

---
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.

// 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.

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.

<!-- 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.

<!-- 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 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 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:

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 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, scripts/, resources/, and examples/.
• Skills reside within plugin directories that contain a plugin.json manifest and a skills/ folder.
• The 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 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.

How do plugins relate to skills in this standard?

Plugins are organizational containers that group related skills together. Each plugin contains a 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 workflow. The standard only enforces the directory structure, not the implementation language of the scripts themselves.

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