What Is the Agent-Native Skills System?

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), 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:

# 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 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:

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: Provides the /visual-plan command for creating immutable, visual project plans using the canvas UI
• skills/visual-recap/SKILL.md: Enables /visual-recap to transform PR diffs into shareable visual summaries
• 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:

# .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	The canonical registry and source of truth for all exported skills across the ecosystem
skills/visual-plans/SKILL.md	Core definition for visual planning capabilities, including tool guidance and UI surface configuration
skills/visual-recap/SKILL.md	Instructions for converting code changes into visual recaps
skills/context-xray/SKILL.md	Context visualization skill for monitoring token limits
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 <name>
• 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 <skill-name> from your project root. This command copies the skill definition from the built-in repository or registry into .agents/skills/<skill-name>/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). 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.

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