# How to Create Custom Skills for Agent Instructions in Agent-Native > Learn to create custom skills for Agent Instructions in Agent-Native. Follow our simple guide to add powerful new abilities to your agents using markdown. - Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native) - Tags: how-to-guide - Published: 2026-06-28 --- **Create a markdown file named [`SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/create-skill/SKILL.md). A skill file consists of four main components: ### YAML Front-Matter The top of every [`SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/SKILL.md) must declare metadata between triple dashes: ```markdown --- 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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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. ```markdown --- 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. ```markdown --- 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. ```markdown --- 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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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**: ```bash mkdir -p .agents/skills/my-custom-skill/references ``` 2. **Write the SKILL.md file**: ```markdown --- 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`](https://github.com/BuilderIO/agent-native/blob/main/.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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/.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`](https://github.com/BuilderIO/agent-native/blob/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`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/writing-agent-instructions/SKILL.md).