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.
On this page 8 sections
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:
- Name and description: Identifies the skill and details the specific prompts, error states, or user requests that should trigger it.
- 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.
- 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:
vibiz skills add --globalIf you want to install skills for a specific client rather than letting the CLI auto-detect your environment, pass the --agent flag:
vibiz skills add --global --agent claude
vibiz skills add --global --agent codex
vibiz skills add --global --agent cursorTo limit an installation to the local repository, run the command inside the project root without the --global flag:
vibiz skills addYou can also install a single named skill rather than the entire collection:
vibiz skills add paymentsTo verify which skills your environment currently recognizes, run:
vibiz skills listYou can view the full catalog and inspect individual skill files directly through the Agent skills documentation.
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:
Set up thelastapi for me: follow https://thelastapi.dev/get-started.mdThe agent executes the setup playbook step-by-step:
- Installs the CLI package globally (
npm install --global @vibiz/cli). - Runs
vibiz loginto initiate authentication. The CLI prints an authorization link and pauses while you approve access in your browser. - Installs the agent skills globally across the environment (
vibiz skills add --global). - Links the remote MCP server using
vibiz mcp add --clients "<your agent>". - Verifies the connection by querying
vibiz_docsandvibiz_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. 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.
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, whilewrite_towrites 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:
vibiz mcp add --clients "Claude Code"Or connect the local MCP server running from the installed package:
claude mcp add vibiz -- npx -y @vibiz/cli mcpFor Cursor, configure .cursor/mcp.json in your project root:
{
"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 and see how to manage multiple services in one API key for an AI agent: hosting, database, email, payments and models.
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.
vibiz keys create build-agent --limitedA 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:
{
"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.
Next step
Install the agent skills across your workstation using vibiz skills add --global and review the available command set in the CLI reference. 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.