How to Create Custom Skills for Agent Instructions in Agent-Native

Create a markdown file named SKILL.md inside a new directory under .agents/skills/ with YAML front-matter declaring the skill name, description, and scope, then write the instruction content using standard markdown headings.

The Agent-Native framework from BuilderIO enables AI agents to follow reusable instruction patterns through a structured skill system. To create custom skills for agent instructions in Agent-Native, you write markdown documents that define specific patterns, workflows, or generators the agent should execute. These skills reside in the .agents/skills/ directory and are automatically loaded by the runtime and development agents based on their declared scope.

Skill File Structure and Anatomy

Every custom skill follows a strict file structure defined in .agents/skills/create-skill/SKILL.md. A skill file consists of four main components:

YAML Front-Matter

The top of every SKILL.md must declare metadata between triple dashes:

---
name: my-workflow
description: >-
  Deploy a new version of the app to production.
scope: both
---

The name field uses hyphen-case, must match the containing directory name, and cannot exceed 64 characters. The scope field controls agent visibility with three valid values: both (default), runtime, or dev.

Content Body

Below the front-matter, use standard markdown headings to structure the instruction. According to the source templates in create-skill/SKILL.md, standard sections include ## When to Use, ## Steps, ## Prerequisites, and ## Verification.

References Directory

For skills requiring extensive documentation that would exceed the recommended 500-line limit for SKILL.md, place supporting files in an optional references/ subdirectory within the skill folder. The agent loads these automatically when resolving the skill.

Three Types of Custom Skills

Agent-Native supports three distinct skill archetypes, each with specific templates in the create-skill guide:

Pattern Skills

Pattern skills enforce rules the agent must follow across the codebase. Use these for linting-like constraints or architectural guardrails.

---
name: no-secrets
description: >-
  Prevent committing secret values to the repository.
---

# No Secrets

## Rule

Never commit files containing secret keys.

## Why

Secrets exposed in version control can be stolen.

## How

- Add a pre-commit hook that runs `detect-secrets`.
- Add `*.env` to `.gitignore`.

## Don't

Commit `.env` files or hard-coded keys.

Workflow Skills

Workflow skills define multi-step procedures the agent executes sequentially. These guide the agent through complex tasks like adding features or deploying applications.

---
name: add-api-action
description: >-
  Create a new server action and expose it to the agent.
---

# Add API Action

## Prerequisites

- Existing `actions/` directory.

## Steps

1. Create `actions/my-action.ts` with the handler function.
2. Export the action in `actions/index.ts`.
3. Add a client hook `useMyAction` in `app/hooks/`.

## Verification

Run `npm run test` and ensure the endpoint returns expected data.

Generator Skills

Generator skills scaffold new files from templates. These automate repetitive file creation tasks like adding new UI components or API routes.

---
name: scaffold-component
description: >-
  Generate a new shadcn/ui component from a template.
---

# Scaffold Component

## Usage

run: `npm run gen component MyButton`

## What Gets Created

- `components/MyButton.tsx`
- `components/MyButton.module.css`

Naming Conventions and Scope Configuration

Strict naming conventions ensure the agent correctly identifies and loads your custom skills.

Directory and File Naming

Create a directory under .agents/skills/ using hyphen-case (e.g., my-custom-skill). The directory name must match the name field in the front-matter exactly and contain fewer than 64 characters. Inside, the primary file must be named exactly SKILL.md.

Scope Visibility

The scope parameter in front-matter determines which agents can access the skill:

• both (default): Available to the runtime agent inside the application and the developer-side coding agent (e.g., Claude Code).
• runtime: Loaded only by the in-app runtime agent; excluded from development tools.
• dev: Visible only to the developer agent during coding sessions; explicitly excluded from production runtime environments to prevent bloating the system prompt.

As implemented in the loading logic, skills with scope: dev never appear in the aggregated system prompt used by AGENTS.md at runtime.

Step-by-Step: Creating Your First Custom Skill

Follow this exact directory structure and content to add a new skill:

1. Create the directory structure:

   mkdir -p .agents/skills/my-custom-skill/references

2. Write the SKILL.md file:

   ---
   name: my-custom-skill
   description: >-
     Describe what this skill automates.
   scope: both
   ---
   # My Custom Skill
   
   ## When to Use
   
   Trigger this skill when the user asks to...
   
   ## Steps
   
   1. Analyze the existing code in `src/`.
   2. Apply the pattern described in `references/detailed-guide.md`.
   3. Verify the output.
   
   ## References
   
   - `references/detailed-guide.md`

3. Add optional supporting documents in the references/ folder if the skill requires detailed schemas or large code templates.

4. Commit the files to version control. The agent automatically discovers new skills at startup without requiring restarts or configuration changes.

How the Agent Consumes Custom Skills

When the Agent-Native runtime initializes, it recursively scans .agents/skills/*/SKILL.md and loads all discovered skills into memory. The front-matter name provides the identifier used for prompt matching, while the scope field filters which skills populate the system prompt versus remain available only to development agents.

According to .agents/skills/writing-agent-instructions/SKILL.md, when a user request matches the "When to trigger" description defined in a skill, the agent injects that skill's content into its context window and follows the defined steps sequentially. Skills with extensive references/ directories have their reference content concatenated to the main skill body before execution.

Summary

• Create a new directory under .agents/skills/ using hyphen-case matching your skill name (max 64 characters).
• Write a SKILL.md file with YAML front-matter declaring name, description, and scope.
• Choose the appropriate archetype: Pattern for enforcement rules, Workflow for multi-step procedures, or Generator for file scaffolding.
• Configure scope as dev to keep developer-only instructions out of production runtime, or both to share across environments.
• Reference large documentation in an optional references/ subdirectory to keep SKILL.md under 500 lines.

Frequently Asked Questions

What is the maximum length for a skill name?

Skill names must not exceed 64 characters and must exactly match the containing directory name using hyphen-case (e.g., add-api-endpoint). This constraint ensures compatibility with the agent's identifier resolution system as defined in .agents/skills/create-skill/SKILL.md.

Can I use custom skills in production runtime?

Yes, but only if you set scope: both or scope: runtime in the front-matter. Skills marked with scope: dev are explicitly excluded from the production runtime system prompt to prevent unnecessary token consumption and potential security exposure of development-only instructions.

Where should I put supporting documentation for complex skills?

Place large supporting files in a references/ subdirectory within your skill folder (e.g., .agents/skills/my-skill/references/). The agent automatically loads these when processing the skill, allowing you to keep the main SKILL.md file concise while providing detailed schemas or specifications.

How does the agent decide when to apply a custom skill?

The agent matches user prompts against the description in the skill's front-matter and the "When to Use" section content. When the natural language intent aligns with these declarations, the agent loads the skill's steps into its context and executes them sequentially according to the logic defined in .agents/skills/writing-agent-instructions/SKILL.md.

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