# What Is the Agent-Native Skills System? > Learn about the Agent-Native skills system, a flexible framework that empowers coding agents with reusable capabilities using markdown and slash commands. Enhance your agent's functionality with this extensible system. - Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native) - Tags: deep-dive - Published: 2026-06-28 --- **The Agent-Native skills system is a declarative, extensible framework that equips coding agents with reusable capabilities through markdown-based instruction files stored in `.agents/skills/` and invoked via slash commands.** The Agent-Native skills system lives at the core of the BuilderIO/agent-native repository, providing a data-driven layer that transforms standard AI agents into UI-aware collaborators. Unlike traditional plugin architectures that require code compilation, this system uses pure markdown definitions to declare tools, UI surfaces, and best-practice workflows that agents can discover and execute at runtime. ## How the Skills Architecture Works At its foundation, the skills system operates on a simple contract: **SKILL.md** files contain human-readable instructions that the agent parses dynamically, determining which tools to call and how to render results. ### The SKILL.md Contract Structure Each skill resides in a dedicated directory as a markdown file containing structured frontmatter and executable guidance. According to the source implementation, every SKILL.md includes: - **Frontmatter metadata**: `name`, `description`, and `metadata.visibility` (set to `exported` for global access or private for local use) - **Instruction body**: Step-by-step guidance telling the agent when to invoke specific tools (e.g., `create-visual-plan`, `get-plan-blocks`) - **References**: Links to supporting documentation, wireframes, or example implementations These files live in two locations: the global **`skills/`** directory for built-in capabilities (such as [`skills/visual-plans/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/skills/visual-plans/SKILL.md)), or the local **`.agents/skills/`** directory for project-specific extensions. ### Runtime Execution Flow When a skill is invoked, the agent follows a deterministic pipeline: 1. **Discovery**: The agent queries the skill catalog via `get-plan-blocks` or reads the local `.agents/skills/` directory 2. **Loading**: Instructions are parsed from the SKILL.md, identifying permitted MCP tools and UI configurations 3. **Execution**: The agent calls declared tools (e.g., `create-visual-plan` for visual planning or `update-visual-plan` for applying patches) 4. **Rendering**: Output surfaces are shaped according to the skill's UI directives—whether canvas-first, prototype, or document views ## Installing and Registering Skills The system provides a **self-service CLI** for skill management that requires no manual configuration file editing. ### Installing Built-in Skills To add a capability to your local agent, run the installation command targeting the skill name: ```bash # Installs the visual-plan skill and registers its MCP connector npx @agent-native/core@latest skills add visual-plan ``` This command copies the skill's markdown definition into [`.agents/skills/visual-plan/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/visual-plan/SKILL.md) and creates the corresponding **slash command** (`/visual-plan`) available in Codex, Claude Code, Cursor, and other supported clients. ### Updating Skills Because skill definitions are versioned with the repository, you can synchronize the latest instructions using: ```bash npm run skills:update ``` This pulls the latest markdown definitions from the upstream `skills/` directory without requiring source code changes. ## Built-in Skills and Capabilities The repository ships with several production-ready skills defined in the `skills/` directory: - **[`skills/visual-plans/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/skills/visual-plans/SKILL.md)**: Provides the `/visual-plan` command for creating immutable, visual project plans using the canvas UI - **[`skills/visual-recap/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/skills/visual-recap/SKILL.md)**: Enables `/visual-recap` to transform PR diffs into shareable visual summaries - **[`skills/context-xray/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/skills/context-xray/SKILL.md)**: Offers the `/context-xray` command to visualize token usage and context limits in Codex/Claude Code sessions Each skill declares its **tool guidance** explicitly—for example, the visual-plan skill specifies when to call `create-visual-plan` versus `get-plan-feedback`, ensuring the agent follows discipline-specific workflows. ## Creating Custom Skills Adding domain-specific capabilities requires only markdown authorship, no TypeScript compilation or package building. ### Custom Skill Skeleton Create a new directory under `.agents/skills/` with the following structure: ```text # .agents/skills/my-audit/SKILL.md --- name: my-audit description: >- Audits recent file changes for security patterns. metadata: visibility: exported --- When the user requests an audit, call the `list-actions` tool with filter type 'security', then format results as a markdown table with severity indicators. ``` Setting `metadata.visibility` to `exported` makes the skill available to all agents in the workspace, while omitting or setting it to `private` keeps it local to the current project context. ## Key Properties of the System The Agent-Native skills system exhibits six defining characteristics that distinguish it from traditional agent extensions: - **Declarative**: Skills are pure data (markdown); the agent interprets instructions at runtime without code compilation - **Composable**: Skills can chain into other skills, share MCP tools, and combine into complex workflows - **Client-agnostic**: The same skill definition works across Codex, Claude Code, Cursor, and Open Code after a single `skills add` installation - **Version-controlled**: SKILL.md files live in Git, enabling audit trails and iterative improvement alongside application code - **Visibility-controlled**: The `metadata.visibility` field determines whether a skill is exported to the global catalog or kept private - **Self-service**: Users install capabilities via single CLI commands without modifying agent source code ## Repository Structure and Key Files Understanding the file layout is essential for navigating the skills ecosystem in BuilderIO/agent-native: | File Path | Purpose | |-----------|---------| | [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md) | The canonical registry and source of truth for all exported skills across the ecosystem | | [`skills/visual-plans/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/skills/visual-plans/SKILL.md) | Core definition for visual planning capabilities, including tool guidance and UI surface configuration | | [`skills/visual-recap/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/skills/visual-recap/SKILL.md) | Instructions for converting code changes into visual recaps | | [`skills/context-xray/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/skills/context-xray/SKILL.md) | Context visualization skill for monitoring token limits | | [`packages/skills/README.md`](https://github.com/BuilderIO/agent-native/blob/main/packages/skills/README.md) | Documentation for the `@agent-native/skills` package and CLI usage patterns | | `.agents/skills/` | Local repository path where installed skills are stored per-project | ## Summary - The Agent-Native skills system uses **markdown-based SKILL.md files** to declare agent capabilities without requiring code changes - Skills are stored in `.agents/skills/` locally or `skills/` for built-in sets, and registered via `npx @agent-native/core@latest skills add ` - Each skill provides **slash commands** (e.g., `/visual-plan`), **tool guidance**, and **UI surface shaping** through declarative frontmatter and instructions - The system is **data-driven**, **version-controlled**, and **client-agnostic**, working across Codex, Claude Code, Cursor, and other supported agents - **Custom skills** require only creating a SKILL.md with appropriate `name`, `description`, and `metadata.visibility` fields ## Frequently Asked Questions ### How do I install a skill in my project? Run `npx @agent-native/core@latest skills add ` from your project root. This command copies the skill definition from the built-in repository or registry into `.agents/skills//SKILL.md`, registers the slash command with your local agent, and configures any required MCP connectors so the skill works across all supported AI clients. ### What is the difference between exported and private skills? **Exported skills** (`metadata.visibility: exported`) are discoverable by all agents in your workspace and appear in the global skill catalog ([`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md)). **Private skills** omit this flag or set it to `private`, restricting availability to the specific repository where the `.agents/skills/` directory resides. Use exported skills for reusable team capabilities and private skills for project-specific workflows. ### Can I use the same skill across different AI clients like Claude Code and Cursor? Yes. The Agent-Native skills system is **client-agnostic**. Once installed via the CLI, the SKILL.md instructions and registered MCP connectors work identically across Codex, Claude Code, Cursor, Pi, and Open Code. The slash command interface (e.g., `/visual-plan --open`) remains consistent regardless of which client hosts the agent. ### How do I update skills when the repository changes? Execute `npm run skills:update` in your project directory. This synchronizes your local `.agents/skills/` directory with the latest markdown definitions from the upstream repository, ensuring your agents have access to the most recent tool guidance and best practices without requiring manual file replacements or code redeployment.