@agent-native/core 0.152.1 → 0.153.0

package/dist/templates/workspace-core/.agents/skills/client-methods/SKILL.md

@@ -1,115 +0,0 @@
----
-name: client-methods
-description: >-
-  Client method surface rules. Use when wiring browser/client code to actions,
-  application state, framework routes, app APIs, uploads, auth, or settings.
-scope: dev
-metadata:
-  internal: true
----
-
-# Client Methods
-
-## Rule
-
-Browser/client code imports named methods, hooks, or client modules instead of
-hand-writing REST calls to framework or app routes.
-
-## Why
-
-Route shapes are transport details. If components and docs call
-`fetch("/_agent-native/...")` or template `/api/*` routes directly, every caller
-has to rediscover auth, base paths, request-source headers, JSON parsing, error
-handling, optimistic updates, sync invalidation, and route quirks. A named client
-method gives the UI, docs, and future agents one stable contract.
-
-## How
-
-1. Look for an existing client API first.
-
-   | Need | Use |
-   | --- | --- |
-   | App action reads/writes | `useActionQuery` / `useActionMutation` from `@agent-native/core/client/hooks` |
-   | Imperative action calls | `callAction` from `@agent-native/core/client/hooks` |
-   | Browser application state | `readClientAppState`, `writeClientAppState`, `setClientAppState`, `deleteClientAppState` from `@agent-native/core/client/hooks` |
-   | Navigation/app-state sync | `useAgentRouteState` / `useSemanticNavigationState` from `@agent-native/core/client/navigation` |
-   | Agent chat context | Agent chat helpers from `@agent-native/core/client/agent-chat` |
-   | Ask the user a multiple-choice question from app code | `askUserQuestion` from `@agent-native/core/client/agent-chat` (renders inline in the agent panel; answer goes to the agent — do not build a custom modal) |
-   | Live sync | `useDbSync`, `useChangeVersion`, `useChangeVersions` from `@agent-native/core/client/hooks` |
-   | Extension iframe calls | `appAction`, `appFetch`, `extensionFetch` from the extension runtime |
-
-   Action fetch behavior: every `useActionQuery` / `useActionMutation` /
-   `callAction` request is bounded by a 60s timeout, and timeouts surface as
-   errors instead of retrying silently. `useActionQuery` cancels superseded
-   requests automatically via React Query's abort signal. For imperative
-   calls, `callAction(name, params, { method, signal, timeoutMs })` accepts an
-   `AbortSignal` and a `timeoutMs` override for legitimately long operations.
-
-2. If no client API exists, add the narrowest helper at the boundary.
-
-   - Put shared framework helpers in `packages/core/src/client/*`.
-   - Put template-local helpers in `templates/<app>/app/hooks/*`,
-     `templates/<app>/app/lib/*`, or an existing local client module.
-   - Export reusable core helpers from the focused `@agent-native/core/client/*`
-     entry for their domain. Never recommend the deprecated broad
-     `@agent-native/core/client` barrel in new code.
-   - Keep raw `fetch`, `agentNativePath`, and route paths inside that helper,
-     not scattered through components or docs.
-   - Add focused tests for URL construction, headers, response parsing, error
-     shape, and any sync invalidation.
-
-3. Teach the helper, not the route.
-
-   Docs, skills, examples, and generated code should show:
-
-   ```ts
-   await setClientAppState("selection", selection, { keepalive: true });
-   ```
-
-   not:
-
-   ```ts
-   await fetch("/_agent-native/application-state/selection", {
-     method: "PUT",
-     body: JSON.stringify(selection),
-   });
-   ```
-
-## Exceptions
-
-Raw route calls are acceptable only inside low-level client helpers or for
-route-shaped protocols that cannot be hidden cleanly:
-
-- multipart uploads
-- streaming/SSE/WebSocket transports
-- OAuth redirects and callback URL construction
-- webhooks and external provider callbacks
-- extension sandbox `appFetch` / `extensionFetch`, which are themselves exposed
-  client methods
-- tests that assert route construction
-
-Even for exceptions, prefer a named helper as soon as more than one caller needs
-the behavior.
-
-## Don't
-
-- Don't put `fetch("/_agent-native/...")`, `fetch(agentNativePath(...))`, or
-  template `/api/*` calls directly in React components for normal app data,
-  actions, settings, or application state.
-- Don't document route calls as the way client code should do work.
-- Don't add pass-through `/api/*` routes just to make client fetches look
-  simpler; expose an action and call it with action hooks.
-- Don't duplicate auth/session/base-path/request-source/error parsing logic in
-  every component.
-
-## Related Skills
-
-- `actions` — app operations shared by UI and agent.
-- `context-awareness` — application-state navigation and selection helpers.
-- `real-time-sync` — keeping helper-backed UI reads fresh.
-- `server-plugins` — when a new route is actually warranted.
-
-## References
-
-- `references/legacy-client-fetch-audit-2026-06-03.md` — known legacy cleanup
-  targets found when this rule was added.

package/dist/templates/workspace-core/.agents/skills/client-methods/references/legacy-client-fetch-audit-2026-06-03.md

@@ -1,62 +0,0 @@
-# Legacy Client Fetch Audit (2026-06-03)
-
-These are known legacy client-side route calls found while adding the
-`client-methods` rule. Treat them as cleanup targets when editing the relevant
-area. Do not migrate them mechanically without reading the local action/data
-contracts; some need new actions or helper modules first.
-
-## Highest Priority
-
-- 2026-06-07 follow-up: the same high-priority route-first clusters are still
-  present. The biggest migrations remain Analytics, Calendar, Mail, Slides, and
-  Content. Do not copy these patterns into new work; when editing the relevant
-  area, add or reuse actions first, then call them with `useActionQuery`,
-  `useActionMutation`, or `callAction`.
-- `templates/analytics/app/pages/analyses/AnalysesList.tsx`,
-  `templates/analytics/app/pages/analyses/AnalysisDetail.tsx`,
-  `templates/analytics/app/components/layout/Sidebar.tsx`, and
-  `templates/analytics/app/components/layout/CommandPalette.tsx` use `/api/*`
-  for normal app data. `list-analyses` and `get-analysis` already exist; add
-  action-backed hooks/helpers for dashboard, explorer, theme, and user-pref
-  routes.
-- `templates/slides/app/context/DeckContext.tsx` and
-  `templates/slides/app/pages/Presentation.tsx` use `/api/decks` for deck CRUD.
-  `list-decks` and `get-deck` already exist; add or expose UI-safe actions for
-  upsert/delete flows before migrating.
-- `templates/mail/app/hooks/use-emails.ts`,
-  `templates/mail/app/hooks/use-scheduled-jobs.ts`,
-  `templates/mail/app/hooks/use-automations.ts`, and
-  `templates/mail/app/pages/SettingsPage.tsx` still use `/api/*` for normal
-  email/settings/automation work. Reuse existing actions where possible and add
-  missing structured actions for aliases, scheduled jobs, and automation
-  settings.
-- `templates/calendar/app/hooks/use-events.ts` bypasses existing private event
-  actions for event CRUD. Prefer `get-event`, `update-event`, `delete-event`,
-  and `rsvp-event` through action hooks or `callAction`.
-
-## Medium Priority
-
-- Raw action endpoint calls remain in several client flows, including Gmail
-  filters, calendar people search, slides import, videos composition generation,
-  and design variant flow. Prefer hooks or `callAction`.
-- Template navigation hooks duplicate application-state fetch logic. Prefer
-  `setClientAppState`, `readClientAppState`, `deleteClientAppState`, or a shared
-  navigation-state helper.
-- Mail integration credentials are written through application state in
-  `templates/mail/app/hooks/use-integrations.ts` and `use-apollo.ts`; move
-  credential values to secrets/actions instead of browser-readable app-state.
-- Content comments and versions are partially migrated. Add missing actions such
-  as `resolve-comment`, `delete-comment`, `list-document-versions`, and
-  `restore-document-version`.
-- Plans version history is the model to copy for new history/rollback work:
-  `list-plan-versions`, `get-plan-version`, and `restore-plan-version` are
-  action-native, and the UI calls them through action hooks. Do not copy
-  Content's legacy document-version `/api/*` helpers into new version panels.
-
-## Acceptable Exceptions
-
-Uploads/file transfer, exports, public/anonymous pages, OAuth/auth redirects,
-webhooks/tracking endpoints, media/blob routes, collab text endpoints,
-framework setup/status routes, low-level core helper implementations, and the
-extension bridge `appFetch` / `extensionFetch` can be route-shaped protocols.
-Prefer named helpers when more than one caller needs the behavior.

package/dist/templates/workspace-core/.agents/skills/client-side-routing/SKILL.md

@@ -1,87 +0,0 @@
----
-name: client-side-routing
-description: >-
-  How to add routes without remounting the app shell. Use when adding a new
-  route, fixing agent sidebar reloads on navigation, or choosing between
-  `root.tsx` layout and pathless `_app.tsx` layout patterns.
-scope: dev
-metadata:
-  internal: true
----
-
-# Client-Side Routing
-
-## Rule
-
-All templates are single-page apps using React Router. **Navigation must not remount the app shell.** The agent sidebar, document tree, and any other persistent chrome must survive route changes.
-
-## Why
-
-If the shell unmounts on every navigation, the agent chat reconnects/reloads, destroying in-progress work and hammering the backend.
-
-## Hard Rule
-
-**The app shell (AgentSidebar + any top-level navigation) must be mounted ONCE, above the `<Outlet />`.** Never wrap each page in its own `<AppLayout>` / `<Layout>`. React sees a different component at the outlet position on each nav and unmounts the entire subtree.
-
-## Two Correct Patterns
-
-### 1. All routes need the shell
-
-Mount `<AppLayout>` in `root.tsx` around `<Outlet />`:
-
-```tsx
-// app/root.tsx
-<AppLayout>
-  <Outlet />
-</AppLayout>
-```
-
-### 2. Mix of protected and public routes
-
-Use a React Router **pathless layout route**:
-
-```
-app/routes/
-  _app.tsx                  # renders <AppLayout><Outlet /></AppLayout>
-  _app._index.tsx           # / → under AppLayout
-  _app.settings.tsx         # /settings → under AppLayout
-  _app.team.tsx             # /team → under AppLayout
-  book.$slug.tsx            # /book/:slug → no layout (public)
-  f.$.tsx                   # /f/* → no layout (public form filler)
-```
-
-The `_` prefix on `_app.tsx` makes it a **pathless** parent — it contributes the layout but no URL segment. Route files prefixed with `_app.` nest under it and share the layout instance across navigations.
-
-## Anti-Pattern
-
-```tsx
-// ❌ BAD — each route wraps its own Layout, causing full remount on every nav
-export default function Settings() {
-  return (
-    <AppLayout>
-      <SettingsContent />
-    </AppLayout>
-  );
-}
-```
-
-If a page needs per-route data (e.g. sidebar highlighting the active document), derive it inside the layout from `useParams()` / `useLocation()` — don't pass it as a prop through every route file.
-
-## Chat-First Routes
-
-If `/` is a full-page chat such as `AgentChatHome`, keep the app shell mounted
-around it when possible so `AgentSidebar` URL sync and route warmup stay active.
-If the chat route intentionally lives outside the shell, add a tiny app-owned
-prewarm for the routes agents commonly open from that chat. In local dev,
-React Router can update the address bar before a cold Vite route chunk commits,
-which makes navigation look broken even when the URL is correct.
-
-## Adding a New Route
-
-- **Pattern #1** (AppLayout in `root.tsx`): just render page content — nothing else.
-- **Pattern #2** (pathless `_app.tsx`): name the file `_app.<segment>.tsx` for authed routes, or bare `<segment>.tsx` for public routes.
-
-## Related Skills
-
-- `adding-a-feature` — The four-area checklist referencing route layout patterns
-- `context-awareness` — Navigation state written on every route change

package/dist/templates/workspace-core/.agents/skills/composable-mini-apps/SKILL.md

@@ -1,139 +0,0 @@
----
-name: composable-mini-apps
-description: >-
-  Build many focused workspace apps that compose through agent discovery and
-  A2A. Use when designing headless mini-apps or cross-app workflows.
-scope: dev
----
-
-# Composable Mini-Apps
-
-## Rule
-
-Prefer many one-job apps in a workspace over one oversized app. A headless app
-can own a provider, dataset, workflow, or specialist action surface without a
-full UI; the main agent composes those apps through discovery and A2A.
-
-## Shape
-
-- Give each mini-app one clear job, a concise `package.json` description, and
-  action names that describe the job it owns.
-- Keep provider credentials and upstream API details in the app that owns that
-  provider or workflow. Other apps should delegate to it instead of copying its
-  integration code.
-- Use a tiny status/config screen only when users need to inspect state. A
-  pure headless app is fine when its job is invoked by agents, automations, or
-  sibling apps.
-- If two workflows only share a helper, put the helper in `packages/shared`;
-  keep the workflow actions in separate apps.
-
-## Discovery And Invocation
-
-The main agent should discover available siblings before assuming capability:
-
-- Runtime agents receive an `<available-apps>` block built from
-  `discoverAgents()`. Workspace siblings are layered in by
-  `discoverWorkspaceAgents()`. It carries one line per app — enough to know a
-  sibling exists, not enough to know what it can do.
-- Use the built-in `describe-workspace-apps` tool for actual capability.
-  It reads each peer's live `/.well-known/agent-card.json` and returns its
-  purpose plus any optional stable machine contracts; pass `app: "<id>"` for
-  one peer's full description. Call it before building something a sibling may
-  already own, before telling a user what is or is not possible across apps,
-  and whenever someone asks which app to use for a job.
-- Never hand-maintain a markdown or code list of what each workspace app does.
-  A stale catalog is worse than none: it reads as authoritative while pointing
-  at capabilities that moved or vanished. An app's purpose belongs in its own
-  `package.json` `description` (which flows into the workspace manifest and the
-  `<available-apps>` block), and its capabilities belong in its exposed
-  actions — both of which `describe-workspace-apps` reads live.
-- UI shells, headless surfaces, and scripts can read the same registry through
-  `GET /_agent-native/agents?selfAppId=<app-id>`.
-- Code or CLI callers should use the first-class message-based A2A invocation
-  path (`invokeAgent()` / `agent-native invoke`) when they need to ask an app
-  by id, name, or URL.
-- In the agent loop, use `call-agent` with the sibling app id when another app
-  owns the work or data. Never call the current app through `call-agent`; use
-  local actions instead.
-- Send a natural-language objective by default so the sibling can apply its own
-  instructions, skills, schemas, data dictionary, credentials, and tools.
-  `invokeAgentAction()` or `call-agent` with `action` + `input` is only for an
-  explicit stable semantic read contract whose complete input is already known.
-  Never expose or call an implementation action as a workaround for slow or
-  failed message delegation.
-
-Send narrow prompts to siblings: name the exact question, relevant ids, date
-ranges, and expected output shape. Preserve returned ids and URLs verbatim.
-
-## Artifact Handoff
-
-Mini-apps should hand off compact artifacts, not giant pasted transcripts or
-provider dumps. When a mini-app creates something another app may use, return
-or store an artifact with:
-
-- `artifactType` - what kind of output this is, such as `deal-set`,
-  `call-evidence`, `brief`, `dashboard`, or `report`.
-- `artifactId` - the stable app-owned id, file path, or resource id.
-- `createdAt` - an ISO timestamp.
-- `source` - provider/app/source ids used to create it.
-- `summary` - a short human-readable explanation.
-- `items` or `records` - the bounded structured data downstream apps need.
-- `links` - fully qualified URLs for user-visible artifacts.
-
-Downstream apps should receive artifact ids, URLs, and narrow follow-up
-questions. If a downstream app needs more detail, it should call back to the
-artifact-owning app instead of asking the orchestrator to paste the whole
-corpus into a prompt.
-
-Example: `hubspot-pipeline` returns `{ artifactType: "deal-set",
-artifactId: "hubspot-pipeline:deal-set:2026-06-18" }`. `deal-brief` passes
-that id to `gong-evidence`, which returns a `call-evidence` artifact id and
-URLs. `deal-brief` then synthesizes the final brief from the artifact ids and
-bounded summaries.
-
-## Provider APIs
-
-Provider-specific actions are shortcuts, not limits. When the upstream API can
-answer the question better than a first-class shortcut, call
-`provider-api-catalog` and `provider-api-docs` as needed, then
-`provider-api-request` against the real provider endpoint. For broad joins,
-searches, or absence claims, stage the bounded corpus with `stageAs` and reduce
-it with `query-staged-dataset` or code.
-
-When composing apps, make the provider-owning mini-app do those
-`provider-api-request` calls. The orchestrator should delegate a bounded job;
-it should not reimplement every provider endpoint locally.
-
-## Example
-
-For a sales-intelligence workspace, split the job into small apps:
-
-| App | Owns | Calls |
-| --- | --- | --- |
-| `hubspot-pipeline` | CRM deals, contacts, companies, associations | `provider-api-request` with provider `hubspot` |
-| `gong-evidence` | Calls, transcripts, snippets, speaker evidence | `provider-api-request` with provider `gong` |
-| `knowledge-base` | Internal docs, pricing rules, playbooks | local search/read actions |
-| `deal-brief` | Orchestration and final brief | message-based `invokeAgent()` or `call-agent` to the three apps |
-
-Flow: `deal-brief` asks `hubspot-pipeline` for the target account and open
-deals, asks `gong-evidence` for recent transcript evidence about those deals,
-asks `knowledge-base` for relevant playbook guidance, then synthesizes the
-answer. That is a HubSpot→Gong→knowledge-base chain made of focused apps,
-not a single app that clones every provider integration.
-
-## Don't
-
-- Do not clone Mail, Calendar, Analytics, Brain, Assets, or another first-party
-  app just to reuse its data. Delegate or link to the existing app.
-- Do not hide a multi-provider workflow inside a giant "misc tools" app.
-- Do not add one-off provider endpoints when `provider-api-request` can express
-  the upstream API safely.
-- Do not create wrapper routes that only re-export another app's action or A2A
-  result.
-
-## Related Skills
-
-- **a2a-protocol** - How apps expose and call A2A endpoints.
-- **actions** - How each mini-app exposes its own operation surface.
-- **external-agents** - How external MCP hosts route through workspace apps.
-- **storing-data** - How app-owned data stays SQL-backed and portable.

package/dist/templates/workspace-core/.agents/skills/context-xray/SKILL.md

@@ -1,72 +0,0 @@
----
-name: context-xray
-description: >-
-  Inspect and manage the live agent context window with Context X-Ray. Use when
-  context is getting large, the user asks what is in context, or stale tool
-  results/files should be pinned, evicted, restored, or reported by an external
-  host.
-metadata:
-  internal: true
----
-
-# Context X-Ray
-
-Context X-Ray is the framework's context garbage-collection surface. It shows
-the current thread's model-bound context as content-derived segments with token
-counts, then lets the user or agent pin, evict, or restore individual segments.
-
-## Actions
-
-| Action | When to use |
-| --- | --- |
-| `context-manifest-get` | Read the current manifest for a thread. Returns token totals, segment status, source, and whether changes are enforceable. |
-| `context-preview-get` | Compose the would-be system context for the current user/org/app without a live thread. Returns labeled system sections with provenance, governance tier, token counts, and bounded previews. Backs the Agent page Context tab. |
-| `context-pin` | Preserve a segment across future compaction/model calls. Use for task specs, acceptance criteria, user constraints, and other durable context. |
-| `context-evict` | Exclude a stale or irrelevant segment from future model calls. Eviction is reversible and never deletes chat history. |
-| `context-restore` | Undo a pin, evict, or summarize directive for a segment. |
-| `context-report` | External hosts can report their visible context inventory. These manifests are advisory unless Agent-Native owns the emitted content. |
-
-## System Sections
-
-Manifests now cover the system-prompt half of context, not just conversation
-segments. Each system section carries a `provenance` label (framework-core,
-actions-prompt, template, enterprise-workspace-core, sql-workspace,
-legacy-app-default, organization, personal, memory, db-schema, tools,
-model-overlay, runtime-context) and a `governance` tier:
-
-- `required` — framework/enterprise policy; can never be altered by the user.
-- `inherited` — template/org/workspace instructions; managed elsewhere,
-  visible here.
-- `user` — personal instructions and memory; editable through Files.
-
-System sections are display-only provenance: they cannot be pinned, evicted,
-or summarized. The persisted manifest stores source refs, scope, content
-hashes, token counts, and bounded previews (~200 chars) — never raw prompt
-bodies; full content stays behind the resource/access model. The in-chat
-X-Ray panel groups these under "System", and the Agent page Context tab
-renders the full breakdown (via `context-preview-get`) with a
-system-vs-conversation split meter. Manifests are the latest snapshot per
-thread; there is no per-iteration history.
-
-## Rules
-
-- Never evict or summarize protected segments. The manifest marks active-turn
-  user/tool/thinking context as `protected`.
-- System sections are never evictable; required/inherited tiers are locked by
-  design — do not present controls that imply otherwise.
-- Prefer pinning the user's task, requirements, and decisions before evicting
-  large stale tool results.
-- Eviction excludes content from future model calls; it does not delete the
-  canonical transcript or files.
-- In external/advisory mode, be honest: recorded directives are intent for the
-  host except for Agent-Native-originated content we can actually withhold.
-- If token counts are estimated, describe reclaim as approximate.
-
-## Typical Flow
-
-1. Call `context-manifest-get` with the active `threadId`.
-2. Sort segments by `tokenCount` and inspect large stale `Tool results` or
-   `Files read` entries.
-3. Call `context-pin` for essential specs or user instructions.
-4. Call `context-evict` for large irrelevant segments.
-5. Offer `context-restore` if the user wants undo.

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

@@ -1,195 +0,0 @@
----
-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.
-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.
-
-## Frontmatter Fields
-
-| Field         | Required | Value                                         |
-| ------------- | -------- | --------------------------------------------- |
-| `name`        | yes      | Hyphen-case, matches the directory name        |
-| `description` | yes      | What the skill covers AND when it triggers     |
-| `scope`       | no       | `both` (default) \| `runtime` \| `dev`         |
-
-For how to word a `description` and which `scope` a skill should get, follow
-**writing-agent-instructions** — it owns those rules.
-
-## Tips
-
-- **Keep SKILL.md lean (under ~500 lines)** — move detailed content to
-  `references/` files.
-- **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**).
-- **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).