@agent-native/core 0.28.5 → 0.29.0

package/dist/templates/default/.agents/skills/create-skill/SKILL.md

@@ -12,25 +12,34 @@ description: >-
 
 Create a new skill when:
 
-- There's a pattern the agent should follow repeatedly
-- A workflow needs step-by-step guidance
-- You want to scaffold files from a template
+- 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)
-- The guidance is a one-off — put it in `AGENTS.md` or `learnings.md` instead
+- 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**.
 
-## 5-Question Interview
+## Interview
 
 Before writing the skill, answer these:
 
 1. **What should this skill enable?** — The core purpose in one sentence.
-2. **Which agent-native rule does it serve?** — Rule 1 (files), Rule 2 (delegate), Rule 3 (scripts), Rule 4 (SSE), Rule 5 (self-modify), or "utility."
-3. **When should it trigger?** — Describe the situations in natural language. Be slightly pushy — over-triggering is better than under-triggering.
-4. **What type of skill?** — Pattern, Workflow, or Generator (see templates below).
-5. **Does it need supporting files?** — References (read-only context) or none. Keep it minimal.
+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
 
@@ -42,7 +51,7 @@ For documenting how things should be done:
 ---
 name: my-pattern
 description: >-
-  [Under 40 words. When should this trigger?]
+  [Under 40 words. What it covers AND when it should trigger.]
 ---
 
 # [Pattern Name]
@@ -76,7 +85,7 @@ For multi-step implementation tasks:
 ---
 name: my-workflow
 description: >-
-  [Under 40 words. When should this trigger?]
+  [Under 40 words. What it covers AND when it should trigger.]
 ---
 
 # [Workflow Name]
@@ -108,7 +117,7 @@ For creating files from templates:
 ---
 name: my-generator
 description: >-
-  [Under 40 words. When should this trigger?]
+  [Under 40 words. What it covers AND when it should trigger.]
 ---
 
 # [Generator Name]
@@ -127,30 +136,36 @@ description: >-
 
 ## After Generation
 
-[What to do next — wire up SSE, add routes, etc.]
+[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-script`, `capture-learnings`)
+- 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.
 
 ## Tips
 
-- **Keep descriptions under 40 words** — They're loaded into context on every conversation.
-- **Keep SKILL.md under 500 lines** — Move detailed content to `references/` files.
-- **Use standard markdown headings** — No XML tags or custom formats.
+- **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 (violates Rule 2)
-- **Database patterns** — Skills must not introduce databases (violates Rule 1)
-- **Ignoring db sync** — If a skill creates data, mention wiring up `useDbSync`
-- **Vague descriptions** — "Helps with development" won't trigger. Be specific about _when_.
-- **Pure documentation** — Skills should guide action, not just explain concepts
+- **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
 
@@ -163,5 +178,9 @@ description: >-
 
 ## Related Skills
 
-- **capture-learnings** — When a learning graduates to reusable guidance, create a skill
-- **self-modifying-code** — The agent can create new skills (Tier 2 modification)
+- **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).

package/dist/templates/workspace-core/.agents/skills/create-skill/SKILL.md

@@ -12,26 +12,34 @@ description: >-
 
 Create a new skill when:
 
-- There's a pattern the agent should follow repeatedly
-- A workflow needs step-by-step guidance
-- You want to scaffold files from a template
+- 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)
-- The guidance is a one-off — put it in `AGENTS.md` or `learnings.md` instead
+- 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**.
 
-## 5-Question Interview
+## Interview
 
 Before writing the skill, answer these:
 
 1. **What should this skill enable?** — The core purpose in one sentence.
-2. **Which agent-native rule does it serve?** — Rule 1 (data in SQL), Rule 2 (delegate to agent), Rule 3 (scripts), Rule 4 (polling sync), Rule 5 (self-modify), Rule 6 (app-state in SQL), or "utility."
-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 to use this skill? If yes, the skill should reference the `navigation` app-state key and the `view-screen` script pattern. See the **context-awareness** skill.
-5. **What type of skill?** — Pattern, Workflow, or Generator (see templates below).
-6. **Does it need supporting files?** — References (read-only context) or none. Keep it minimal.
+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
 
@@ -43,7 +51,7 @@ For documenting how things should be done:
 ---
 name: my-pattern
 description: >-
-  [Under 40 words. When should this trigger?]
+  [Under 40 words. What it covers AND when it should trigger.]
 ---
 
 # [Pattern Name]
@@ -77,7 +85,7 @@ For multi-step implementation tasks:
 ---
 name: my-workflow
 description: >-
-  [Under 40 words. When should this trigger?]
+  [Under 40 words. What it covers AND when it should trigger.]
 ---
 
 # [Workflow Name]
@@ -109,7 +117,7 @@ For creating files from templates:
 ---
 name: my-generator
 description: >-
-  [Under 40 words. When should this trigger?]
+  [Under 40 words. What it covers AND when it should trigger.]
 ---
 
 # [Generator Name]
@@ -128,30 +136,36 @@ description: >-
 
 ## After Generation
 
-[What to do next — wire up SSE, add routes, etc.]
+[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-script`, `capture-learnings`)
+- 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.
 
 ## Tips
 
-- **Keep descriptions under 40 words** — They're loaded into context on every conversation.
-- **Keep SKILL.md under 500 lines** — Move detailed content to `references/` files.
-- **Use standard markdown headings** — No XML tags or custom formats.
+- **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 (violates Rule 2)
-- **Database patterns** — Skills must not introduce databases (violates Rule 1)
-- **Ignoring db sync** — If a skill creates data, mention wiring up `useDbSync`
-- **Vague descriptions** — "Helps with development" won't trigger. Be specific about _when_.
-- **Pure documentation** — Skills should guide action, not just explain concepts
+- **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
 
@@ -164,5 +178,9 @@ description: >-
 
 ## Related Skills
 
-- **capture-learnings** — When a learning graduates to reusable guidance, create a skill
-- **self-modifying-code** — The agent can create new skills (Tier 2 modification)
+- **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).

package/docs/content/creating-templates.md

@@ -282,7 +282,7 @@ Projects are the top-level resource. They contain tasks and notes.
 - For shared projects, check access through framework sharing helpers.
 ```
 
-Update `AGENTS.md` whenever you add a new action, route, state key, or recurring workflow.
+Update `AGENTS.md` whenever you add a new action, route, state key, or recurring workflow. See [Writing Agent Instructions](/docs/writing-agent-instructions) for how to keep `AGENTS.md` skimmable and word skill and tool descriptions so the agent triggers them reliably.
 
 ## Add Skills {#skills}
 

package/docs/content/skills-guide.md

@@ -180,6 +180,8 @@ The frontmatter `name` and `description` are used by the agent's tool system for
 
 Save the file at `.agents/skills/my-skill/SKILL.md`. The directory name should match the `name` in frontmatter.
 
+> **See also:** [Writing Agent Instructions](/docs/writing-agent-instructions) for how to word skill descriptions, apply progressive disclosure, and keep `AGENTS.md` lean.
+
 ## Skills vs AGENTS.md {#skills-vs-agents-md}
 
 > **AGENTS.md** — The overview. Lists all scripts, describes the data model, explains the app architecture. The agent reads this first to understand the app.

package/docs/content/writing-agent-instructions.md

@@ -0,0 +1,130 @@
+---
+title: "Writing Agent Instructions & Skills"
+description: "How to write great agent instructions for an agent-native app or template: AGENTS.md, skills, and tool descriptions."
+---
+
+# Writing Agent Instructions & Skills
+
+The agent's behavior in an agent-native app is only as good as the instructions you give it. Three surfaces carry that guidance: `AGENTS.md` (the map), skills (the deep dives), and action/tool descriptions (how the agent picks the right tool). Write each one for fast retrieval, not for prose.
+
+## Keep AGENTS.md small and skimmable {#small-agents-md}
+
+`AGENTS.md` is loaded as orientation. It should be the smallest thing that lets the agent act correctly, with everything deep pushed into skills. Aim for these sections and little else:
+
+- **Purpose line** — one sentence on what the app is and the primary workflow.
+- **Core rules** — the handful of invariants that must always hold (data in SQL, operations go through actions, AI goes through the agent chat, schema changes are additive). Short, imperative bullets.
+- **Application-state keys** — the `navigation`/selection/focus keys the agent reads to know what the user is looking at, with their shape.
+- **Action table** — a compact table of action name to purpose.
+- **Skills index** — a list of the skills that exist and when to read each one.
+
+If a section grows past a screen, it belongs in a skill. `AGENTS.md` answers "what is this app and what can I do," not "how exactly do I do the hard thing."
+
+```markdown
+# Projects App
+
+One workspace for projects, tasks, and notes. Agent and UI share the same SQL
+data and the same actions.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes.
+- All AI work goes through the agent chat; never call an LLM inline.
+- Schema changes are additive only.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                     |
+| ---------------- | --------------------------- |
+| `list-projects`  | List accessible projects    |
+| `create-project` | Create a project            |
+| `update-project` | Rename or archive a project |
+
+## Skills
+
+- `project-imports` — read before importing legacy CSV exports.
+- `sharing` — read before exposing a project to other users.
+```
+
+## Single-source AGENTS.md {#single-source}
+
+Keep one canonical instructions file: `AGENTS.md`. If a client expects `CLAUDE.md`, make it a symlink to `AGENTS.md` rather than a second copy. Two hand-maintained files drift, and the agent ends up with contradictory rules. One source of truth, linked where needed.
+
+## SKILL.md frontmatter must say what AND when {#skill-frontmatter}
+
+The `description` is the only thing the agent sees when deciding whether to read a skill. It must answer two questions: what the skill covers, and when to trigger it. A description that only describes the topic will not fire.
+
+```markdown
+---
+name: project-imports
+description: >-
+  How to import projects from the legacy CSV export. Use when the user uploads
+  a project CSV or asks to migrate projects from the old system.
+---
+```
+
+- Lead with the capability, then add an explicit **"Use when…"** clause.
+- Be slightly pushy — over-triggering beats a skill that never loads.
+- Keep it under ~40 words; it is loaded into context on every conversation.
+
+## Progressive disclosure {#progressive-disclosure}
+
+Write the `SKILL.md` as the lean, must-know layer: the rule, how to do it, the do/don't list, and pointers. Push long examples, exhaustive field references, API quirks, and edge-case tables into `references/` files the agent reads only when it needs them.
+
+```text
+.agents/skills/project-imports/
+├── SKILL.md            # rule + happy path + do/don't
+└── references/
+    └── csv-format.md   # full column spec, encodings, edge cases
+```
+
+This keeps the always-loaded surface small and lets depth scale without bloating context. See the [Skills Guide](/docs/skills-guide) for the full skill format.
+
+## Write action-oriented tables {#action-tables}
+
+The agent scans tables faster than prose. Prefer a table of name to purpose over paragraphs describing each operation. The same applies to state keys, field types, and any enumerable set. Tables are skimmable, diffable, and easy to keep in sync when you add an action.
+
+## Write clear tool descriptions {#tool-descriptions}
+
+Action descriptions are tool descriptions — they drive tool selection. Make each one a precise, single-purpose sentence:
+
+- Say what it does and what it returns, not how it's implemented.
+- Describe each parameter in its `.describe()` so the agent fills it correctly.
+- One responsibility per action. If a description needs "and also…", split it.
+- Mark read-only actions (`readOnly: true` or `http: { method: "GET" }`) so the agent knows they're safe to call freely.
+
+```ts
+defineAction({
+  description: "Create a project. Returns the new project id and title.",
+  schema: z.object({
+    title: z.string().min(1).describe("Project title shown in the sidebar"),
+  }),
+  // ...
+});
+```
+
+## Bake in anti-fabrication and verify-before-done {#anti-fabrication}
+
+App instructions should make honesty and verification the default behavior:
+
+- **Never fabricate.** If data isn't found or an action fails, say so and recover — don't invent results or claim success. Read the real value via an action or query before reporting it.
+- **Verify before declaring done.** After a change, confirm it with a read-back (re-query the row, re-read the screen via `view-screen`) instead of assuming the write worked.
+- **Recover, don't give up.** On a recoverable error (a failed query, a transient fetch), retry or fix the input rather than abandoning the task. Keep this separate from the anti-fabrication rule — don't conflate "don't make things up" with "stop at the first error."
+
+Put these as core rules in `AGENTS.md` so they apply to every turn.
+
+## What goes where {#what-goes-where}
+
+- **AGENTS.md** — applies to the whole app, every turn: purpose, core rules, state keys, action index, skills index.
+- **Skills** — reusable how-to for a specific pattern, loaded on demand. Applies to everyone working in the app.
+- **Memory (`memory/MEMORY.md`)** — per-user preferences and corrections, not authored guidance.
+
+## What's next {#whats-next}
+
+- [Skills Guide](/docs/skills-guide) — the skill file format, framework skills, and app-backed skills.
+- [Creating Templates](/docs/creating-templates) — how `AGENTS.md` and skills fit into a shippable template.
+- [Adding a Feature](/docs/adding-a-feature) — the four-area model every feature must satisfy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.28.5",
+  "version": "0.29.0",
   "type": "module",
   "engines": {
     "node": ">=22"

package/src/templates/default/.agents/skills/create-skill/SKILL.md

@@ -12,25 +12,34 @@ description: >-
 
 Create a new skill when:
 
-- There's a pattern the agent should follow repeatedly
-- A workflow needs step-by-step guidance
-- You want to scaffold files from a template
+- 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)
-- The guidance is a one-off — put it in `AGENTS.md` or `learnings.md` instead
+- 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**.
 
-## 5-Question Interview
+## Interview
 
 Before writing the skill, answer these:
 
 1. **What should this skill enable?** — The core purpose in one sentence.
-2. **Which agent-native rule does it serve?** — Rule 1 (files), Rule 2 (delegate), Rule 3 (scripts), Rule 4 (SSE), Rule 5 (self-modify), or "utility."
-3. **When should it trigger?** — Describe the situations in natural language. Be slightly pushy — over-triggering is better than under-triggering.
-4. **What type of skill?** — Pattern, Workflow, or Generator (see templates below).
-5. **Does it need supporting files?** — References (read-only context) or none. Keep it minimal.
+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
 
@@ -42,7 +51,7 @@ For documenting how things should be done:
 ---
 name: my-pattern
 description: >-
-  [Under 40 words. When should this trigger?]
+  [Under 40 words. What it covers AND when it should trigger.]
 ---
 
 # [Pattern Name]
@@ -76,7 +85,7 @@ For multi-step implementation tasks:
 ---
 name: my-workflow
 description: >-
-  [Under 40 words. When should this trigger?]
+  [Under 40 words. What it covers AND when it should trigger.]
 ---
 
 # [Workflow Name]
@@ -108,7 +117,7 @@ For creating files from templates:
 ---
 name: my-generator
 description: >-
-  [Under 40 words. When should this trigger?]
+  [Under 40 words. What it covers AND when it should trigger.]
 ---
 
 # [Generator Name]
@@ -127,30 +136,36 @@ description: >-
 
 ## After Generation
 
-[What to do next — wire up SSE, add routes, etc.]
+[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-script`, `capture-learnings`)
+- 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.
 
 ## Tips
 
-- **Keep descriptions under 40 words** — They're loaded into context on every conversation.
-- **Keep SKILL.md under 500 lines** — Move detailed content to `references/` files.
-- **Use standard markdown headings** — No XML tags or custom formats.
+- **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 (violates Rule 2)
-- **Database patterns** — Skills must not introduce databases (violates Rule 1)
-- **Ignoring db sync** — If a skill creates data, mention wiring up `useDbSync`
-- **Vague descriptions** — "Helps with development" won't trigger. Be specific about _when_.
-- **Pure documentation** — Skills should guide action, not just explain concepts
+- **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
 
@@ -163,5 +178,9 @@ description: >-
 
 ## Related Skills
 
-- **capture-learnings** — When a learning graduates to reusable guidance, create a skill
-- **self-modifying-code** — The agent can create new skills (Tier 2 modification)
+- **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).