create-skill - SKILL.md Agent Skill

name: create-skill description: >- How to create new skills for an agent-native app. Use when adding a new skill, documenting a pattern the agent should follow, or creating reusable guidance for the agent. scope: dev metadata: internal: true

Create a Skill

When to Use

Create a new skill when:

There's a pattern the agent should follow repeatedly.
A multi-step workflow needs reliable, step-by-step guidance.
You want to scaffold files from a template.

Don't create a skill when:

The guidance already exists in another skill — extend it instead.
You're documenting something the agent already knows (e.g., how to write TypeScript).
It's a one-off — put it in AGENTS.md (for everyone) or memory/MEMORY.md (personal, per-user). See capture-learnings.

Interview

Before writing the skill, answer these:

What should this skill enable? — The core purpose in one sentence.
Which of the four areas does it serve? — UI, actions, skills/instructions, or application state (see the adding-a-feature skill). Most skills are about how to touch one or more of these correctly.
When should it trigger? — Describe the situations in natural language. Be slightly pushy — over-triggering is better than under-triggering.
Does it involve context awareness? — Does the agent need to know what the user is looking at? If so, reference the navigation application-state key and the view-screen action pattern. See the context-awareness skill.
What type of skill? — Pattern, Workflow, or Generator (see below).
Does it need supporting files? — References (read-only context) or none. Keep it minimal; push depth into references/.

Skill Types and Templates

Pattern (architectural rule)

For documenting how things should be done:

---
name: my-pattern
description: >-
  [Under 40 words. What it covers AND when it should trigger.]
---

# [Pattern Name]

## Rule

[One sentence: what must be true]

## Why

[Why this rule exists]

## How

[How to follow it, with code examples]

## Don't

[Common violations]

## Related Skills

[Which skills compose with this one]

Workflow (step-by-step)

For multi-step implementation tasks:

---
name: my-workflow
description: >-
  [Under 40 words. What it covers AND when it should trigger.]
---

# [Workflow Name]

## Prerequisites

[What must be in place first]

## Steps

[Numbered steps with code examples]

## Verification

[How to confirm it worked]

## Troubleshooting

[Common issues and fixes]

## Related Skills

Generator (scaffolding)

For creating files from templates:

---
name: my-generator
description: >-
  [Under 40 words. What it covers AND when it should trigger.]
---

# [Generator Name]

## Usage

[How to invoke — what args/inputs are needed]

## What Gets Created

[List of files and their purpose]

## Template

[The template content with placeholders]

## After Generation

[What to do next — wire up sync, add routes, register the action, etc.]

## Related Skills

Naming Conventions

Hyphen-case only: [a-z0-9-], max 64 characters.
Pattern skills: descriptive names (storing-data, delegate-to-agent).
Workflow/generator skills: verb-noun (create-skill, capture-learnings).
The directory name must match the name in frontmatter.

Skill Scope (runtime vs dev)

An optional scope frontmatter field controls which agent loads the skill:

both (default when omitted) — loaded by connected repo agents and the in-app runtime agent. Use for any skill both audiences should follow.
runtime — loaded only by the in-app runtime agent.
dev — meant for the human's coding agent (e.g. Claude Code) only. Excluded from the runtime agent everywhere: not in the system-prompt skills block and not in docs-search results.

Use scope: dev for internal-only skills that should guide connected repo agents such as Codex or Claude Code, but should not affect the deployed production agent. Do not use metadata.internal for runtime visibility; that field is catalog/package metadata and is intentionally not treated as production exclusion.

---
name: release-checklist
description: >-
  Steps for cutting a release. Use when preparing or publishing a new version.
scope: dev
---

Leave scope off for normal skills — the default (both) keeps them loading at runtime, so this is fully backward compatible. To make a dev-only skill visible to your coding agent but hidden from the runtime agent, mark it scope: dev and optionally mirror it under .claude/skills/<name>/SKILL.md (Claude Code reads .claude/skills/ independently of the runtime's .agents/skills/).

Tips

Keep descriptions under 40 words — they load into context on every conversation. State what the skill does AND when to trigger it.
Keep SKILL.md lean (under ~500 lines) — move detailed content to references/ files (progressive disclosure).
Use standard markdown headings — no XML tags or custom formats.

Anti-Patterns

Inline LLM calls — skills must not call LLMs directly. All AI work goes through the agent chat (see delegate-to-agent).
Introducing databases — data lives in SQL via Drizzle (see storing-data).
Ignoring sync — if a skill creates data, mention wiring useDbSync / useActionQuery so the UI updates (see real-time-sync).
Vague descriptions — "Helps with development" won't trigger. Be specific about when.
Pure documentation — skills should guide action, not just explain concepts.

File Structure

.agents/skills/my-skill/
├── SKILL.md              # Main skill (required)
└── references/           # Optional supporting context
    └── detailed-guide.md

Related Skills

adding-a-feature — The four-area model every skill ultimately serves.
writing-agent-instructions — How to write AGENTS.md and skills well for apps and templates you ship to others.
capture-learnings — When a learning graduates to reusable guidance, create a skill; one-offs go to AGENTS.md or memory/MEMORY.md.
self-modifying-code — The agent can create new skills (Tier 2 modification).