How to Create Custom Skills Following the Agent Skills Standard

To create custom skills following the Agent Skills standard, place a self-contained unit inside a plugin's skills/ directory containing a SKILL.md mission control file, executable scripts, static resources, and working examples, following the YAML front-matter schema defined in the stitch-skills repository.

The google-labs-code/stitch-skills repository implements the open Agent Skills specification. Each skill is a self-contained unit that lives inside a plugin folder and provides its own "mission-control" (SKILL.md), executable scripts, resource files, and example references. To add a new custom skill, you must follow the repository-wide directory layout and file conventions described in the root [README.md](https://github.com/google-labs-code/stitch-skills/blob/main/README.md) and in the plugin-specific plugin.json files.

Understanding the Agent Skills Directory Structure

Skills are grouped by functional area under the plugins/ directory. The stitch-skills repository organizes capabilities into three primary plugins:

• Design – plugins/stitch-design
• Build – plugins/stitch-build
• Utilities – plugins/stitch-utilities

Every skill must contain four canonical items. According to the Repository Structure section in the root README (see lines 26-33), the required layout is:

Item	Purpose	Location
SKILL.md	Mission control declaring name, description, allowed tools, and workflow	skills/<skill-name>/SKILL.md
scripts/	Executable scripts for validation or runtime actions	skills/<skill-name>/scripts/
resources/	Static knowledge assets like schemas or checklists	skills/<skill-name>/resources/
examples/	Gold-standard inputs demonstrating correct usage	skills/<skill-name>/examples/

Step-by-Step Guide to Creating a Custom Skill

Choose a Plugin Host

Select the most appropriate plugin for your skill's functional area and place your skill under its skills/ sub-folder. For example, a new utility skill belongs at:

plugins/stitch-utilities/skills/<your-skill-name>/

Create the Required File Structure

Create a directory inside your chosen plugin's skills/ folder. The following skeleton illustrates the minimal structure for a skill named my-custom-skill:

plugins/
└─ stitch-utilities/
   └─ skills/
      └─ my-custom-skill/
         ├─ SKILL.md
         ├─ scripts/
         │   └─ validate.sh
         ├─ resources/
         │   └─ schema.json
         └─ examples/
             └─ input.yaml

Populate the SKILL.md Mission Control

SKILL.md serves as the agent's instruction manual. It begins with a YAML front-matter block followed by a Markdown description. The front matter must declare the skill name, description, and allowed tools:

---
name: my-custom-skill
description: Transform a raw user description into a structured Stitch design specification.
allowed-tools:
  - "Read"
  - "Write"
---

After the front matter, document the following:

1. When to invoke the skill – what user intent triggers it
2. The processing pipeline – each logical step the agent should perform (e.g., "Validate input → Generate assets → Upload to Stitch")
3. Output format – how the result should be returned (plain text, file path, JSON, etc.)
4. Examples – short input/output pairs

A real-world template can be copied from the Enhance Prompt skill's SKILL.md (source), which demonstrates the full documentation standard.

Add Supporting Scripts

If your skill requires executable code (e.g., validation scripts, network calls to a Stitch MCP server, or code-generation utilities), place those scripts in the scripts/ folder and make them executable. The allowed-tools list in SKILL.md must include any tool the script requires.

Example validation script at scripts/validate.sh:

#!/usr/bin/env bash

# Simple sanity check – ensure the input contains at least one keyword.

if grep -qEi "(dashboard|profile|settings)" "$1"; then
  exit 0
else
  echo "❌ Input does not contain recognizable UI keywords."
  exit 1
fi

Provide Resources and Examples

• Resources (resources/) hold static artifacts such as JSON schemas, design checklists, or markdown templates. For example, resources/template.md might contain:

**DESIGN SYSTEM (REQUIRED):**
- Platform: {{platform}}
- Theme: {{theme}}
- Colors: {{primary_color}} ({{primary_hex}})

**Page Structure:**
{{#sections}}
1. **{{title}}:** {{description}}
{{/sections}}

• Examples (examples/) contain fully-validated input files that demonstrate correct usage. These files are used by the built-in test harness to verify the skill's correctness. Example examples/input.yaml:

description: "Create a settings page with a light theme."
platform: web
theme: light

Registering and Validating Your Skill

When adding a new top-level plugin, create a plugin.json describing the plugin metadata (name, version, author, etc.). Existing plugins already contain this file, such as the utilities plugin at [plugins/stitch-utilities/plugin.json](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-utilities/plugin.json). No additional registration step is necessary for a new skill inside an existing plugin; the agent discovers it automatically based on the folder layout.

Run the repository's validation workflow (.github/workflows/validate-skills.yml) which executes the skill's own validation scripts and checks that required files exist. This CI step ensures that newly added skills conform to the Agent Skills schema and do not break existing functionality.

Installing and Publishing Custom Skills

Once the skill passes validation, install it via the Codex CLI, Claude Code, or Cursor using the standard commands shown in the Quick Start section of the README (see lines 7-23):

codex plugin marketplace add google-labs-code/stitch-skills --ref main \
  --sparse plugins/stitch-utilities
npx skills add google-labs-code/stitch-skills

Summary

• Create custom skills following the Agent Skills standard by placing them in plugins/<plugin-name>/skills/<skill-name>/ with four required components: SKILL.md, scripts/, resources/, and examples/.
• The SKILL.md file acts as mission control, using YAML front matter to declare name, description, and allowed-tools.
• Choose existing plugins (stitch-design, stitch-build, or stitch-utilities) or create new ones with a plugin.json descriptor.
• Validate skills using the .github/workflows/validate-skills.yml CI workflow before publishing.
• Reference existing implementations like [plugins/stitch-utilities/skills/enhance-prompt/SKILL.md](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-utilities/skills/enhance-prompt/SKILL.md) for concrete examples of the required documentation structure.

Frequently Asked Questions

What is the minimum required structure for an Agent Skill?

Every skill must contain four items: a SKILL.md file (the mission control document), a scripts/ directory for executables, a resources/ directory for static assets, and an examples/ directory containing gold-standard inputs. These components must reside under plugins/<plugin-name>/skills/<skill-name>/ according to the repository structure defined in the root README.

How do I validate my custom skill before publishing?

Run the repository's .github/workflows/validate-skills.yml workflow, which checks that required files exist and executes any validation scripts in your skill's scripts/ folder. This ensures conformance with the Agent Skills schema and prevents breaking changes to existing functionality.

Can I create a new plugin or must I use existing ones?

You can either add skills to existing plugins (stitch-design, stitch-build, or stitch-utilities) or create entirely new plugins. When creating a new plugin, you must include a plugin.json file describing the plugin metadata, as seen in [plugins/stitch-utilities/plugin.json](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-utilities/plugin.json).

What tools can I specify in the allowed-tools section of SKILL.md?

The allowed-tools list in SKILL.md YAML front matter declares which capabilities the agent may use when executing your skill. Common values include "Read" and "Write" for file system operations, but the specific tools available depend on the Agent Skills runtime environment. Any tool your scripts require must be explicitly listed here.

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