--- 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: 1. **What should this skill enable?** — The core purpose in one sentence. 2. **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. 3. **When should it trigger?** — Describe the situations in natural language. Be slightly pushy — over-triggering is better than under-triggering. 4. **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. 5. **What type of skill?** — Pattern, Workflow, or Generator (see below). 6. **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: ```markdown --- 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: ```markdown --- 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: ```markdown --- 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. ```markdown --- 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//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).