AGENTS.md · expo/skills

Sections

1. Repository Structure
2. Plugin Manifests
3. Skill Files
4. Supporting Files
5. Marketplace Configuration
6. Adding a Skill
7. Testing Plugins
8. User Installation
9. Conventions in This Repo
10. Feedback

First lines (shown under the repo's MIT license)

# Expo Skills Repository

This repository contains official Expo AI agent skills. Codex and other Agent Plugins clients load each plugin from a root `plugin.json` ([Agent Plugins](https://agent-plugins.org/) 1.0.0). Grok uses that root manifest when it is present. Claude Code and Cursor read `.claude-plugin/plugin.json`. The skills should stay useful to any agent that can consume `SKILL.md` files.

## Repository Structure

```
.claude-plugin/
  marketplace.json          # Claude Code and Cursor marketplace catalog
.agents/
  plugins/
    marketplace.json        # Codex marketplace catalog
plugins/
  expo/
    plugin.json             # Agent Plugins manifest (Codex and other compatible clients)
    mcp.json                # Agent Plugins MCP configuration
    .claude-plugin/
      plugin.json           # Claude Code and Cursor plugin manifest
    .mcp.json               # Claude Code, Grok, and Cursor MCP configuration
    skills/
      README.md             # Grouped index of all skills
      skill-name/
        SKILL.md            # Main skill file
        references/         # Optional supporting documentation
        scripts/            # Optional utility scripts
        agents/
          openai.yaml       # Codex trigger metadata
    README.md               # Plugin documentation
README.md                   # User-facing installation instructions
CONTRIBUTING.md             # Contributor guidance (adding skills, naming, free vs paid)
skills.sh.json              # skills.sh catalog groupings
scripts/                    # CI checks (skill limits, plugin version bump)
```

Both marketplaces expose the active `expo` and `expo-experiments` plugins. Entry names match the plugin manifest names. Do not add compatibility aliases.

## Plugin Manifests

The `expo` plugin carries two manifests that share one `version`. CI rejects a skill or manifest change that does not bump them together. `expo-experiments` ships the same pair.

| Manifest | Who reads it |
| --- | --- |
| `plugins/expo/plugin.json` | Codex, other [Agent Plugins](https://agent-plugins.org/) clients, and Grok when this file exists |
| `plugins/expo/.claude-plugin/plugin.json` | Claude Code and Cursor |

Claude Code reads `.claude-plugin/plugin.json` and `.mcp.json`. It does not read the root `plugin.json`. Grok prefers the root `plugin.json` when that file exists, and still loads MCP from `.mcp.json`. If the root manifest is absent, Grok uses the Claude manifest. Cursor looks for `.cursor-plugin/plugin.json` first, then the Claude manifest, then the root manifest, and stops at the first file that parses. This repo ships no Cursor manifest, so Cursor stops on the Claude one. That manifest does not list skills, so Cursor discovers `skills/`. For MCP, Cursor reads `.mcp.json` before `mcp.json` and keeps the first `expo` server.

### Agent Plugins manifest (`plugin.json`)

This is the manifest Codex and every other Agent Plugins client reads. Its schema is **closed** - the only permitted top-level fields are `$schema`, `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, and `extensions`. Component locations are fixed and cannot be overridden: skills come from `skills/`, MCP servers from `mcp.json`.

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of the plugin",
  "author": {
    "name": "Expo Team",
    "email": "support@expo.dev",
    "url": "https://expo.dev"
  },
  "license": "MIT",
  "extensions": {
    "com.openai": {
      "interface": {
        "displayName": "Expo Plugin"
      }
    }
  }
}
```

`$schema` and `name` are required. Client-specific data goes under a reverse-domain namespace in `extensions`; `com.openai` is Codex's namespace, and Codex reads only `interface`, `apps`, and `hooks` from it. A field outside the permitted list is a schema violation, so do not add `skills`, `mcpServers`, or a top-level `displayName`.

The MCP configuration is a sibling `mcp.json` with its own `$schema`. Remote servers use `"type": "streamable-http"`. `"http"` is not a valid Agent Plugins transport.

Claude Code, Grok, and Cursor keep using `.mcp.json`, which stays on `"type": "http"`. Codex and other Agent Plugins clients load the root `mcp.json`.

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "expo": {
      "type": "streamable-http",
      "url": "https://mcp.expo.dev/mcp"
    }
  }
}
```

### Claude Code manifest (`.claude-plugin/plugin.json`)

Claude Code is not an Agent Plugins client. It reads its own manifest and its own `.mcp.json`, and ignores the root `plugin.json`. Cursor stops on the first manifest that parses, so in this repo it reads the Claude manifest and loads MCP from `.mcp.json` before `mcp.json`. Grok prefers the root `plugin.json` when that file exists and loads MCP from `.mcp.json`.

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of the plugin",
  "author": {
    "name": "Expo Team",
    "email": "support@expo.dev"
  }
}
```

Only `name` is required. `version`, `description`, and `author` are optional.

## Skill Files

Skills teach agents how to perform specific Expo tasks. Each skill has a `SKILL.md` file with YAML frontmatter:

```markdown
---
name: skill-name
description: What the skill does and when to use it.
license: MIT
---

# Skill Title

Skill content goes here...
```

Frontmatter fields:

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Skill identifier, lowercase with hyphens, max 64 chars |
| `description` | Yes | Natural-language trigger description, max 1024 chars |
| `allowed-tools` | No | Tools Claude can use without permission, for example `"Read, Grep, Bash(node:*)"` |
| `license` | No | License identifier |

Do not add a `version` key. Anthropic and OpenAI skill validators reject it. Versioning stays on the plugin manifests.

Skill guidelines:

- Name skills `expo-*` (open-source framework) or `eas-*` (paid EAS service). Paid skills open the body with a costs/plan-limits callout. See `CONTRIBUTING.md` for the full rules.
- Keep the `SKILL.md` body under 500 lines and the `description` under 1024 characters - both are CI-enforced by `scripts/check-skill-limits.ts`.
- Move detailed material to `references/` and load it only when the skill needs it.
- Put reusable validation or fetching logic in `scripts/` instead of pasting large command blocks into the skill.
- Write descriptions that match how users naturally ask for help.
- Include keywords users are likely to mention, but do not stuff descriptions with unrelated terms.
- Prefer concrete commands, APIs, and Expo package names over vague advice.

## Supporting Files

Skills can include supporting files:

```
skills/my-skill/
├── SKILL.md
├── references/
│   ├── setup.md
│   └── examples.md
└── scripts/
    ├── fetch.js
    └── validate.js
```