# Agent skills (SKILL.md) for Claude Code, Codex and Cursor

> Agent skills use SKILL.md files to teach Claude Code, Codex, and Cursor project workflows, installed globally or per project with the CLI.

**An agent skill is an instruction bundle centered on a `SKILL.md` file that teaches Claude Code, Codex, or Cursor how to execute multi-step workflows and handle project tasks.** Each skill defines its purpose in a front-matter description, provides procedural guidance, and links to reference documentation. Coding agents read the skill on demand when a user prompt matches its description, keeping core context clear until specialized knowledge is required.

When building full-stack applications with AI coding agents, agents often guess API parameters, make incorrect assumptions about billing or webhooks, or attempt impossible tasks. Agent skills solve this by delivering the exact operational rules an agent needs directly to its environment.

## What is inside a SKILL.md bundle

An agent skill consists of a directory holding a `SKILL.md` file and an optional `references/` subdirectory. 

The `SKILL.md` file provides three core components:
1. **Name and description:** Identifies the skill and details the specific prompts, error states, or user requests that should trigger it.
2. **Workflow instructions:** Clear step-by-step procedures for the agent to follow, such as setting up a database branch, handling payments, or drafting email newsletters.
3. **Reference links:** Paths pointing into the local `references/` folder.

Each skill is served as a `.tar.gz` bundle that unpacks into `<name>/SKILL.md` and `<name>/references/`. The reference documents contain detailed operational guides generated from the same source documentation that powers the web console and CLI help. Because the references match the active platform rules, the agent avoids hallucinated flags, phantom endpoints, and outdated code conventions.

## Where Claude Code, Codex and Cursor store skills

Different coding agents look for skills in specific directories on your file system. You can install skills globally so they are available across all your repositories, or configure them locally inside a single project directory.

| Agent | Global location (all projects) | Local location (single project) |
| --- | --- | --- |
| **Claude Code** | `~/.claude/skills/<name>/SKILL.md` | `.claude/skills/<name>/SKILL.md` |
| **Codex** | `~/.agents/skills/<name>/SKILL.md` | `.agents/skills/<name>/SKILL.md` |
| **Cursor** | `~/.cursor/skills/<name>/SKILL.md` | `.cursor/skills/<name>/SKILL.md` |

When searching for project-level skills, Codex scans upward from your current working directory to the root of the repository. Cursor checks `.cursor/skills`, but also reads skills located in `.agents/skills` and `.claude/skills`. Both Claude Code and Codex monitor these folders and usually pick up new skills immediately without needing a session restart.

## How to install skills with the CLI

The quickest way to manage skills across any environment is through the `@vibiz/cli` npm package. You can install skills individually or download the full suite of operational skills at once.

To install all available skills globally for your active agent:

```bash
vibiz skills add --global
```

If you want to install skills for a specific client rather than letting the CLI auto-detect your environment, pass the `--agent` flag:

```bash
vibiz skills add --global --agent claude
vibiz skills add --global --agent codex
vibiz skills add --global --agent cursor
```

To limit an installation to the local repository, run the command inside the project root without the `--global` flag:

```bash
vibiz skills add
```

You can also install a single named skill rather than the entire collection:

```bash
vibiz skills add payments
```

To verify which skills your environment currently recognizes, run:

```bash
vibiz skills list
```

You can view the full catalog and inspect individual skill files directly through the [Agent skills documentation](https://thelastapi.dev/docs/skills).

## Setting up skills automatically with an agent playbook

You do not have to configure your CLI, skills, and model settings manually. thelastapi provides a setup playbook designed for agents to run themselves. 

Paste this instruction directly into Claude Code, Codex, or Cursor:

```text
Set up thelastapi for me: follow https://thelastapi.dev/get-started.md
```

The agent executes the setup playbook step-by-step:
1. Installs the CLI package globally (`npm install --global @vibiz/cli`).
2. Runs `vibiz login` to initiate authentication. The CLI prints an authorization link and pauses while you approve access in your browser.
3. Installs the agent skills globally across the environment (`vibiz skills add --global`).
4. Links the remote MCP server using `vibiz mcp add --clients "<your agent>"`.
5. Verifies the connection by querying `vibiz_docs` and `vibiz_project_status`, then reports a summary of the environment.

When `vibiz login` runs, you open the link in your browser and click **Authorize**. New builders without an account can create one at [thelastapi.dev/start](https://thelastapi.dev/start). Once approved, the CLI saves its own authenticated key named `cli · <computer name>`.

## Pairing skills with an MCP server

A `SKILL.md` teaches an agent *when* and *how* to take action, but the agent still needs the practical tools to run those actions. Pairing skills with the Model Context Protocol (MCP) provides the agent with full platform capabilities. For a detailed guide on remote configurations, read about how to [connect a remote MCP server to Claude, ChatGPT, Cursor and Codex](https://thelastapi.dev/blog/connect-remote-mcp-server).

When an agent skill runs a task, it frequently invokes the MCP server tools to interact with hosting, databases, and third-party resources:

- `vibiz_docs`: Reads platform facts and architecture guides on demand (`payments`, `keys`, `webhooks`, `usage`).
- `vibiz_create_project`: Creates new project containers with hosting, database, and auth resources.
- `vibiz_dev_env`: Fetches local environment values, while `write_to` writes them to `.env.development.local`.
- `vibiz_deploy`: Publishes site directories or updated file payloads directly to production.
- `vibiz_request_secret`: Generates a secure console link for the owner to input third-party credentials without passing secrets into the chat prompt.

You can connect Claude Code to the remote MCP server directly from the CLI:

```bash
vibiz mcp add --clients "Claude Code"
```

Or connect the local MCP server running from the installed package:

```bash
claude mcp add vibiz -- npx -y @vibiz/cli mcp
```

For Cursor, configure `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "vibiz": {
      "command": "npx",
      "args": ["-y", "@vibiz/cli", "mcp"],
      "env": { "VIBIZ_API_KEY": "${env:VIBIZ_API_KEY}" }
    }
  }
}
```

Learn more about managing agent environments in the [Agents documentation](https://thelastapi.dev/docs/agents) and see how to manage multiple services in [one API key for an AI agent: hosting, database, email, payments and models](https://thelastapi.dev/blog/one-api-key-for-ai-agent).

## Protecting production with Limited access keys

Autonomous agents require clear operational boundaries. When you authorize an agent or generate an API key, you control whether it runs with **Full access** or a **Limited key**.

```bash
vibiz keys create build-agent --limited
```

A Limited key allows the agent to create projects, run development database queries, deploy previews, send transactional test emails, and call AI models. However, a Limited key cannot view production secret values, export sensitive user data, remove custom domains, or initiate live financial transfers.

| Capability | Limited key | Full-access key |
| --- | --- | --- |
| Deploy apps and update code | Yes | Yes |
| Run actions, emails, and metered AI | Yes | Yes |
| Inspect development database and dev env | Yes | Yes |
| Inspect production env values | Names only (`?names=1`) | Yes |
| Live refunds, withdrawals, and payouts | No | Yes |
| Create, modify, or revoke API keys | No | Yes |

When an agent running on a Limited key attempts an operation reserved for the human owner—such as issuing a live refund or deleting a production domain—the system blocks the request:

```json
{
  "error": {
    "code": "forbidden",
    "details": {
      "reason": "owner_only",
      "permission": "payments.live:write",
      "grant_url": "https://thelastapi.dev/keys/key_123/allow?permission=payments.live:write",
      "console_url": "https://thelastapi.dev/settings/payments",
      "next_step": "Give the user grant_url to allow this permission, or open console_url to complete it yourself."
    }
  }
}
```

Instead of failing silently, the agent reads `details.next_step` and outputs the `grant_url` in the chat. You can click the link to grant that single permission (`database.production:read`, `payments.live:write`) without handing over your primary account credentials. Complete permission boundaries are documented in [Keys and environments](https://thelastapi.dev/docs/keys).

## Next step

Install the agent skills across your workstation using `vibiz skills add --global` and review the available command set in the [CLI reference](https://thelastapi.dev/docs/cli). To bootstrap a complete project with authentication, serverless Postgres, and payments, instruct your agent to run the setup playbook at `https://thelastapi.dev/get-started.md`.

## Frequently asked questions

### Do I need to restart Claude Code or Codex after adding a new skill?

No, Claude Code and Codex monitor their respective skill directories and automatically pick up new skills without a restart. If an added skill fails to register in an ongoing session, restarting the agent process refreshes the directory index.

### Can Cursor read skills created for other agents?

Yes, Cursor reads skills located in its default `.cursor/skills` folder and also searches `.agents/skills` and `.claude/skills` within the project. This allows you to share one skill directory across teams using different agent clients.

### How do skills prevent agents from hallucinating platform instructions?

Skills bundle a `SKILL.md` instruction file alongside local reference pages extracted directly from platform documentation. The agent references these precise command flags, database constraints, and API schemas on demand instead of guessing parameters.

### What should an agent do when an action returns an owner_only error?

The API returns a `403 forbidden` status with an `owner_only` reason and provides a `grant_url`. The agent outputs this URL so you can approve the specific missing permission or perform the action yourself in the console.

---

Published 2026-11-15 · https://thelastapi.dev/blog/agent-skills-skill-md
