Skill Creator

Skill Creator for Builder.io Fusion

Create and improve skills that extend what Builder.io Fusion can do in your project.

What You'll Do

Help the user through one of these workflows:

1. Create a new skill — capture intent, scaffold the directory, write the SKILL.md 2. Improve an existing skill — read it, diagnose issues, rewrite 3. Choose the right tool — help decide between a skill, AGENTS.md, or .builderrules

Creating a New Skill

Step 1: Capture Intent

Ask these questions to understand what the user needs. Adapt your language to the user's technical level — if they're non-technical, skip jargon and make decisions for them.

1. What should this skill do? What task or knowledge should it provide? 2. When should it trigger? What would someone say or ask that should activate this skill? 3. What's the output? Files, code, a report, a workflow sequence? 4. Does it need user-specific setup? (e.g., API keys, channel names, team preferences) → use the config.json pattern

Step 2: Choose the Right Tool

Before creating a skill, confirm it's the right choice:

Skills are the recommended default. Unlike AGENTS.md which is always loaded into the AI's context, skills only load when relevant. This means you can have many skills without bloating the context window. Reserve AGENTS.md for the small set of instructions the AI truly needs in every conversation.

Step 3: Scaffold the Skill

Create the skill directory at .builder/skills/<name>/SKILL.md:

project/
└── .builder/
    └── skills/
        └── <skill-name>/
            └── SKILL.md

Before writing any files:

• If .builder/ or .builder/skills/ doesn't exist, create the directories
• If a skill already exists at the target path, read it first and ask the user: update the existing skill, or pick a different name?

Naming rules:

• Lowercase letters, numbers, and hyphens only (e.g., pdf-processor, deploy-staging)
• No consecutive hyphens, no leading/trailing hyphens
• Max 64 characters
• The directory name is the skill's identifier
• Nested paths use directories: .builder/skills/office/word/SKILL.md, not office-word
• Avoid names that collide with Builder.io directories: rules, config, settings

Step 4: Write the SKILL.md

Every SKILL.md has two parts: YAML frontmatter and a markdown body.

Frontmatter

At minimum, include name and description:

---
name: my-skill
description: >
  What the skill does AND when to use it. Include trigger
  keywords and phrases. This is what the AI reads to decide
  whether to load the skill.
---

For complete field documentation, see references/frontmatter-reference.md.

Writing the Description (Critical)

The description is the single most important line in your skill. It determines whether the AI loads your skill at the right time. Get this wrong and the skill never triggers; get it right and it activates reliably.

Use the WHAT + WHEN pattern. Every description needs both:

• WHAT the skill does
• WHEN to use it (specific trigger contexts)

Bad:

description: Helps with documents
# Too vague — the AI has no activation signal

description: Extract text from PDF files
# Only says WHAT, not WHEN — the AI must guess when to trigger

description: Use when the user says "create a PDF"
# Too narrow — misses related phrasings

Good:

description: >
  Extract text and tables from PDF files, fill forms, merge
  documents. Use when working with PDF files or when the user
  mentions PDFs, forms, document extraction, or .pdf files.

description: >
  Generate commit messages by analyzing git diffs. Use when the
  user asks for help writing commit messages, reviewing staged
  changes, or preparing code for commit, even if they don't
  explicitly ask for a "commit message."

Tips for reliable triggering:

• Write in third person ("Processes files" not "I help you process files")
• Include file extensions, domain terms, and informal synonyms
• Add "even if they don't explicitly ask for X" for near-miss triggers
• Keep under 1024 characters
• The description is for the AI model, not for humans — think of it as a trigger definition
• AI agents tend to undertrigger skills, so err on the side of being specific about when to activate

Writing the Body

The markdown body is the skill's instructions. Keep it under 500 lines. Structure it clearly:

# Skill Title

## Quick Start
Immediate, actionable guidance.

## Instructions
Step-by-step procedures.

## Gotchas
Common failure points and how to avoid them.

## Examples
Concrete input/output pairs.

Writing principles:

• Don't state the obvious. The AI already knows how to code. Focus on what pushes it out of its default behavior — your project's quirks, conventions, and gotchas.
• Build a Gotchas section. This is the highest-signal content in any skill. Capture failure points as you discover them. Update over time. A good Gotchas section is worth more than pages of instructions.
• Avoid railroading. Skills are reused across many situations. Give the AI information and flexibility, not rigid step-by-step scripts. Let it adapt.
• Explain why, not just what. "Use UTC timestamps because the aggregation pipeline assumes UTC" beats "Always use UTC timestamps."
• Start small, iterate. Most successful skills began as a few lines and one gotcha. They got better as the AI hit edge cases. Don't try to write the perfect skill on the first pass.

Step 5: Add Supporting Files (If Needed)

A skill is a folder, not just a markdown file. Use the file system for progressive disclosure:

my-skill/
├── SKILL.md              # Required — main instructions (<500 lines)
├── references/            # Detailed docs, loaded on demand
│   └── api-docs.md
├── scripts/               # Executable helpers
│   └── validate.sh
└── assets/                # Templates, static files
    └── template.html

Progressive disclosure works in three levels:

Rules:

• Keep SKILL.md under 500 lines. If approaching 400, split detailed content to reference files.
• Link references from SKILL.md: "For API details, see references/api-docs.md."
• Keep references one level deep. Don't have reference files that point to other reference files — the AI may only partially read deeply nested content.
• Include templates in assets/ if your skill generates files with a consistent format.
• Include reusable scripts in scripts/ so the AI composes rather than reconstructs boilerplate.

Step 6: Advanced Patterns

Config.json for User-Specific Setup

If your skill needs context that varies per user (API keys, channel names, team settings):

my-skill/
├── SKILL.md
└── config.json

In SKILL.md, instruct: "If config.json does not exist in this skill directory, ask the user for [required settings] and save them to config.json before proceeding."

Memory and Data Storage

Skills can maintain state:

• Append-only log files (e.g., standups.log for a standup skill)
• JSON data files
• Even SQLite databases

This lets the AI reference its own history across sessions.

Composing Skills

Reference other skills by name in your instructions. The AI will invoke them if they're installed. Example: "Use the /deploy skill to push changes after verification."

Step 7: Test the Skill

After creating the skill:

1. Start a new session. Skills load at session start, so start a fresh session to pick up the new skill. 2. Try substantive prompts. Test with multi-step or specialized prompts that match your description — the more specific your prompt, the better the skill triggers. 3. Try 2-3 phrasings. Test with different ways someone might request what the skill does. 4. Check the gotchas. Deliberately try scenarios where the AI previously failed.

If the skill doesn't trigger, the description probably needs work. Revisit the WHAT + WHEN pattern and add more trigger terms.

Improving an Existing Skill

When the user wants to improve a skill:

1. Read the current SKILL.md — understand its purpose and structure 2. Diagnose the issue:

• Not triggering? → Description needs WHAT + WHEN improvement
• Triggering at wrong times? → Description is too broad, narrow the WHEN
• Producing bad output? → Instructions need gotchas or constraints
• Too slow or consuming too much context? → Split into progressive disclosure

3. Preserve the name and directory — don't rename unless the user asks 4. Show the changes — explain what you changed and why before writing

Audit Checklist

Use this checklist to verify a skill's quality:

• [ ] Frontmatter: Valid YAML with name and description
• [ ] Description: Uses WHAT + WHEN pattern, under 1024 chars
• [ ] Description: Includes specific trigger terms and contexts
• [ ] Naming: Directory name is lowercase-hyphenated, matches name field
• [ ] Size: SKILL.md is under 500 lines
• [ ] Gotchas: Has a Gotchas section (or notes to build one over time)
• [ ] Progressive disclosure: Reference files are one level deep from SKILL.md
• [ ] No obvious knowledge: Doesn't explain things the AI already knows
• [ ] Flexibility: Instructions give the AI room to adapt, not rigid scripts
• [ ] Path: Lives at .builder/skills/<name>/SKILL.md

Anti-Patterns to Avoid

• Vague descriptions — "Helps with code" tells the AI nothing about when to trigger
• Deep reference nesting — SKILL.md → A.md → B.md breaks; keep references one level deep
• Over-explaining the obvious — Don't teach the AI what a REST API is. Focus on YOUR specifics.
• Railroading — Overly rigid step-by-step scripts break when the situation varies. Give context and let the AI adapt.
• Too many options without defaults — "Use library X, Y, or Z" forces an arbitrary choice. Pick one and note alternatives.
• XML tags in the body — Use standard markdown headings, not <section> tags
• Style rules that belong in linters — Semicolons, spacing, import order → ESLint/Prettier config, not a skill

Reference Files

For detailed field documentation, see references/frontmatter-reference.md.

For complete example skills at different complexity levels, see references/examples.md.

Example Skills

Complete, copy-paste-ready skills at different complexity levels. Use these as starting points.

Example 1: Simple Skill — React Component Conventions

A basic knowledge skill. Single SKILL.md, no supporting files.

.builder/skills/react-conventions/SKILL.md

---
name: react-conventions
description: React component conventions and patterns for this project. Use when creating new React components, refactoring existing ones, or when asking about component architecture, hooks patterns, or state management in this codebase.
---

# React Conventions

## Component Structure

Use functional components with hooks. No class components.

Place components in `src/components/` organized by feature, not type.

## Naming

- Components: PascalCase (`UserProfile.tsx`)
- Hooks: camelCase with `use` prefix (`useAuth.ts`)
- Utils: camelCase (`formatDate.ts`)

## State Management

Use React Query for server state and Zustand for client state.
Do not use Redux or Context for state that React Query handles.

## Gotchas

- Always use `key` props on mapped elements — use stable IDs, never array indices
- Avoid creating new object/array literals in JSX props — they cause unnecessary re-renders
- Use `useCallback` for event handlers passed to memoized children

Why this works: Focused on what the AI wouldn't know (your project's specific conventions). Doesn't explain what React is or how hooks work. Has a Gotchas section.

---

Example 2: Workflow Skill — Deploy to Staging

A deploy workflow skill. The description makes it clear this involves deployment so users invoke it intentionally.

.builder/skills/deploy-staging/SKILL.md

---
name: deploy-staging
description: >
  Deploy the current branch to the staging environment. Runs tests,
  builds the app, and pushes to staging infrastructure. Use when the
  user wants to deploy to staging, push to staging, or test changes
  in the staging environment.
---

# Deploy to Staging

## Workflow

1. Run the full test suite: `npm test`
2. If tests fail, stop and report failures. Do not deploy broken code.
3. Build the production bundle: `npm run build`
4. Deploy to staging: `aws s3 sync dist/ s3://staging-bucket/`
5. Invalidate the CDN cache: `aws cloudfront create-invalidation --distribution-id $CF_DIST_ID --paths "/*"`
6. Verify the deployment by checking `https://staging.example.com`

## Gotchas

- Always run tests first. A previous engineer deployed untested code that took down staging for a day.
- The CloudFront invalidation takes 5-10 minutes. Don't panic if changes aren't visible immediately.
- If the S3 sync fails with permission errors, check that the AWS credentials in `.env` haven't expired.

## Rollback

If something goes wrong:

aws s3 sync s3://staging-backup/ s3://staging-bucket/

Why this works: Description clearly communicates this is a deploy action. Has clear rollback instructions. Gotchas capture real incidents.

---

Example 3: Knowledge Skill — API Patterns

Project-specific knowledge that the AI should reference when working with your API.

.builder/skills/api-patterns/SKILL.md

---
name: api-patterns
description: >
  Internal API conventions, authentication patterns, and endpoint
  structure for this project. Use when writing API routes, creating
  new endpoints, working with authentication, or modifying request
  handlers.
---

# API Patterns

## Authentication

All API routes use JWT bearer tokens. The middleware at `src/middleware/auth.ts`
handles validation. Do not implement custom auth logic in route handlers.

Token refresh is handled client-side by `src/lib/api-client.ts`. Never store
tokens in localStorage — use httpOnly cookies.

## Route Structure

src/api/ ├── routes/ │ ├── users.ts # /api/users/ │ ├── projects.ts # /api/projects/ │ └── billing.ts # /api/billing/* ├── middleware/ │ ├── auth.ts │ └── rate-limit.ts └── validators/ └── schemas.ts # Zod schemas for request validation

## Conventions

- All endpoints return `{ data, error, meta }` shape
- Use Zod schemas from `validators/schemas.ts` for request validation
- Pagination uses cursor-based pagination, not offset
- Rate limiting is configured per-route in `middleware/rate-limit.ts`

## Gotchas

- The billing routes use a DIFFERENT auth middleware (`billing-auth.ts`) that also checks Stripe webhook signatures. Don't use the standard `auth.ts` for billing routes.
- The `projects.ts` route has a N+1 query on the `members` relation. Always use `.include({ members: true })` when fetching projects.
- PUT endpoints are idempotent but POST endpoints are not. Use PUT for updates.

Why this works: Focused entirely on project-specific knowledge. The Gotchas section captures real footguns that would cause bugs.

---

Example 4: Complex Skill with Progressive Disclosure

A data analysis skill with reference files, scripts, and a config pattern.

.builder/skills/analytics/
├── SKILL.md
├── config.json
├── references/
│   └── event-schema.md
└── scripts/
    └── query-helpers.py

SKILL.md:

---
name: analytics
description: >
  Query and analyze product analytics data. Use when the user asks
  about metrics, funnels, user behavior, conversion rates, retention,
  or wants to explore event data, even if they don't mention
  "analytics" explicitly.
---

# Analytics

Query product analytics using our event data pipeline.

## Setup

If `config.json` does not exist in this skill directory, ask the user for:
- `database_url`: Connection string for the analytics database
- `default_date_range`: Default lookback period (e.g., "30d")

Save their answers to `config.json`.

## Quick Start

Use the helper functions in `scripts/query-helpers.py` to query data.
These handle connection pooling, date parsing, and common aggregations.

For the full event schema (event names, properties, types), see
[references/event-schema.md](references/event-schema.md).

## Common Queries

### Funnel Analysis
Join `signup_started` → `signup_completed` → `first_action` events.
The canonical user ID is in the `user_id` property (not `anonymous_id`).

### Retention
Use the `cohort_retention()` function from `scripts/query-helpers.py`.
It groups users by signup week and tracks return visits.

## Gotchas

- The `page_view` event fires on BOTH client and server renders. Filter by `context.source = 'client'` to avoid double-counting.
- Revenue events store amounts in CENTS, not dollars. Divide by 100 for display.
- The `anonymous_id` → `user_id` mapping is in the `identity_stitching` table, not the events table.

Why this works: Uses progressive disclosure — SKILL.md stays lean, detailed schema lives in a reference file, reusable query functions live in a script. The config.json pattern handles per-user database credentials. Gotchas capture data-specific footguns that would cause wrong numbers.

Frontmatter Reference

Complete documentation for SKILL.md frontmatter fields.

Core Fields

name

• Required: Recommended (defaults to directory name if omitted)
• Constraints: Lowercase letters, numbers, hyphens only. Max 64 characters. No consecutive hyphens (--). No leading/trailing hyphens. Must match the parent directory name.
• Example: name: pdf-processor

description

• Required: Yes
• Max length: 1024 characters
• Purpose: The primary trigger mechanism. The AI scans all skill descriptions at session start to decide which skills to load when a request matches. This is a trigger definition for the AI, not a human-readable summary.

How to write effective descriptions:

Use the WHAT + WHEN pattern:

description: [WHAT it does]. Use when [WHEN to trigger], [more trigger contexts], even if [near-miss scenario].

See the main SKILL.md for detailed good/bad examples.

Additional Fields

The Agent Skills Open Standard defines additional fields that skill-aware AI tools can use:

Invocation Control

The disable-model-invocation and user-invocable fields control how a skill is loaded:

allowed-tools with MCP Servers

When referencing MCP server tools, use the mcp__servername__toolname pattern:

allowed-tools: mcp__supabase__query, mcp__builder_cms__search_content

MCP servers are configured in mcp.json at the project root.

On-Demand Hooks

Skills can register hooks that activate only while the skill is running:

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/safety-check.sh"

Use for safety guardrails (blocking destructive commands, restricting edits) that should only apply during specific workflows.

String Substitution Variables

These variables are replaced with actual values when the skill is invoked:

Example:

---
name: fix-issue
description: Fix a GitHub issue by number
argument-hint: "[issue-number]"
---

Fix issue #$0 following our project's coding standards and test requirements.