Skills Guide

Skills are Markdown files that give the agent deep knowledge about specific patterns and workflows. Instead of cramming every rule into one system prompt, you split knowledge into focused files the agent loads only when a task actually needs them — keeping the default context small while still letting the agent go deep on demand.

What are skills

Skills live at .agents/skills/<name>/SKILL.md and contain detailed guidance for the agent. Each skill focuses on one concern — how to store data, how to sync state, how to delegate work to the agent chat.

Every skill's frontmatter name and description are always injected into the system prompt's skills block so the agent knows what skills exist. The full skill body is loaded on demand when the agent decides a skill is relevant to the task (it is also surfaced via docs-search). This is why keeping descriptions short and trigger-specific matters: the description is the only thing the agent reads before deciding whether to load the rest.

Progressive disclosure

Always in the system prompt

storing-data — add data models…real-time-sync — wire polling…create-skill — add a skill…

just name + description (cheap)

task matches a descriptionload on demand

Full SKILL.md body
rules, code, do/don't

Only the name + description of every skill is always in context. The full body loads on demand when the task matches.

Reference sub-files

A skill directory can hold more than SKILL.md — extra Markdown, text, or JSON files under a references/ (or similar) subfolder that the main file points to instead of inlining everything. The agent always sees the list of extra files in a skill's directory. Text sub-files under a size cap (64KB per file, 256KB total per skill) are also inlined and independently readable through docs-search, at a skill-<name>--<subpath> slug — a references/api.md file inside my-skill resolves as skill-my-skill--references-api. Sub-files over the cap, or non-text files (images, scripts), are still listed but not inlined; read them from the filesystem directly in Code mode.

.agents/skills/my-skill/
  SKILL.md
  references/
    api.md          # inlined — readable via docs-search as skill-my-skill--references-api
    diagram.png     # listed only — not readable via docs-search

Framework skills

These are the skills bundled with the default template. The exact set available in any given app depends on the template you scaffolded from — check that template's .agents/skills/ directory for what it actually ships.

Skill	When to use
`storing-data`	Adding data models, reading/writing config or state
`real-time-sync`	Wiring polling sync, debugging UI not updating
`delegate-to-agent`	Delegating AI work from UI or actions to the agent
`actions`	Creating or running agent actions
`self-modifying-code`	Editing app source, components, or styles
`create-skill`	Adding new skills for the agent
`capture-learnings`	Recording corrections and patterns
`frontend-design`	Building or styling any web UI, components, or pages
`adding-a-feature`	The four-area checklist: UI, actions, skills, app-state
`internationalization`	Updating localized UI copy, language catalogs, and RTL-safe styles
`shadcn-ui`	Using shadcn/ui primitives and components
`security`	Auth, access control, and secret handling
`real-time-collab`	Multi-user collaborative editing
`agent-engines`	Swapping or configuring the underlying agent engine
`notifications`	In-app and push notification patterns
`progress`	Tracking and surfacing background task progress
`inline-embeds`	Embedding apps or iframes inside the agent chat
`agent-native-docs`	Finding version-matched framework docs and source in `node_modules`
`agent-native-toolkit`	Ownership rules for shared workspace UI (chrome, settings, nav, sharing)
`app-branding`	Renaming or rebranding the app consistently across every surface
`app-permissions`	Enabling browser permissions (camera, mic, geolocation, etc.)
`customizing-agent-native`	Configuring, composing, or ejecting framework features into app code
`feature-flags`	Declaring, evaluating, and removing framework feature flags
`integration-webhooks`	Handling messaging integration webhooks on serverless hosts
`onboarding`	Registering setup steps for the sidebar setup checklist
`secrets`	Registering API keys/credentials for the settings UI and onboarding
`upgrade-agent-native`	Updating `@agent-native/core` or fixing a broken upgrade

context-awareness and a2a-protocol are framework-level skills available in the .agents/skills/ directory at the repo root — see each template's own .agents/skills/ for what it inherits.

Domain skills

Templates include skills specific to their domain. These live in the same .agents/skills/ directory but cover template-specific patterns. See each template's .agents/skills/ directory for the full list; a representative sample:

Mail template — email-drafts, draft-queue
Forms template — form-building, form-publishing, form-responses
Analytics template — adhoc-analysis, bigquery, cross-source-analysis, dashboard-management, data-querying, provider-api, gong, hubspot, prometheus
Slides template — create-deck, deck-management, design-systems, slide-editing, slide-images

Domain skills follow the same format as framework skills. They encode patterns specific to the template that the agent needs to follow.

App-backed skills

App-backed skills package an agent-native app as a skill marketplace artifact. The bundle can include agent instructions, exported skills, MCP connector metadata, hosted/local launch instructions, and UI surfaces such as MCP Apps.

Current app-backed skills include visual-plan, visual-recap, and visualize-repo from Plan, visual-edit from Design, assets from Assets, and content for repo-backed docs/blog/MDX editing.

Full details below: the mechanics of app-backed skills (manifest format, CLI commands, marketplace adapters, auto-update hashing) are covered in App-backed skills — full details.

Creating custom skills

Create a 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

Don't create a skill when:

The guidance already exists in another skill — extend it instead
The guidance is a one-off — put it in AGENTS.md or agent memory instead

Skill format

Each skill is a Markdown file with YAML frontmatter:

Anatomy of a SKILL.md

.agents/skills/project-imports/SKILL.md

1---

2name: project-imports

3description: >-

4 How to import projects from the legacy CSV export. Use when the user uploads

5 a project CSV or asks to migrate projects from the old system.

6---

8# Project Imports

10## Rule

12Always validate the CSV header row before writing any rows. Reject unknown

13columns rather than silently dropping them.

15## How

171. Call `get-import-schema` to fetch the expected columns.

182. Parse the first CSV row and diff against the schema.

193. If any required columns are missing, return an error — do not proceed.

204. Stream remaining rows through `create-project-item` in batches of 50.

22## Don't

24- Don't hold all rows in memory — stream them.

25- Don't create duplicate projects; check for an existing name first.

27## Related Skills

29- **storing-data** — SQL schema and write patterns for new rows

30- **sharing** — exposing a project to other users after import

Line 2Discovery key

The name matches the folder; it is how the skill is invoked as /project-imports.

Lines 3–5The trigger

This description is the only text always in context. Make it state precisely when the skill applies.

Lines 9–14Rules first

Lead with the hard rule and the why; the agent reads the body only once the task matches.

Lines 27–30Cross-link

Point at related skills so the agent can chain them instead of re-deriving guidance.

The frontmatter name and description are used by the agent's tool system for skill discovery. The description should state when the skill triggers — be specific about the situations.

Save the file at .agents/skills/my-skill/SKILL.md. The directory name should match the name in frontmatter.

See also: Writing Agent Instructions for how to word skill descriptions, apply progressive disclosure, and keep AGENTS.md lean. Both pages use the project-imports skill as a running example.

Skill scope: runtime vs dev

An optional scope frontmatter field controls which agent a skill is for:

`scope`	Loaded by the runtime agent?	Use for
`both`	Yes (default)	Skills useful to the in-app agent. This is the default when `scope` is omitted.
`runtime`	Yes	Skills meant only for the in-app runtime agent.
`dev`	No	Skills meant only for the human's coding agent (e.g. Claude Code).

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

When scope is absent (or set to an unrecognized value) it defaults to both, so every existing skill keeps loading at runtime — this field is fully backward compatible. A scope: dev skill is invisible to the runtime agent everywhere: it is excluded from the skills block injected into the system prompt and from docs-search results.

Hiding a skill from the `/` picker

A separate user-invocable frontmatter field controls whether a skill shows up in the /-command picker — independent of scope, which controls whether the runtime agent loads the skill at all.

---
name: learn
description: >-
  Review the conversation and save structured memories for future sessions.
user-invocable: true
---

`user-invocable`	Appears in the `/` picker?	Still loaded and usable by the agent?
(unset, default)	Yes	Yes
`true`	Yes	Yes
`false`	No	Yes — the agent can still invoke it on its own initiative

Use user-invocable: false for a skill that should stay fully loaded and available to the agent, but isn't something a user should type /skill-name to trigger directly.

Exposing a dev-only skill to your coding agent

The agent-native runtime reads skills from .agents/skills/. Claude Code reads skills from .claude/skills/ independently. To make a skill available to your coding agent but hidden from the runtime agent:

Mark it scope: dev in .agents/skills/<name>/SKILL.md so the runtime agent never loads it, and/or
Place or mirror the skill under .claude/skills/<name>/SKILL.md so Claude Code picks it up.

This replaces the old hack of relying on Claude Code only reading .claude/skills — scope: dev makes the dev-vs-runtime split a first-class, explicit choice.

Which agent loads which skill

.agents/skills/

scope: bothdefault

scope: runtime

scope: dev

Runtime agent
reads both + runtime

Coding agent
Claude Code reads .claude/skills/ + dev

scopedecides whether the in-app runtime agent sees a skill.dev skills are visible only to your coding agent.

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.

Skills — Deep dives. Each skill focuses on one pattern with detailed rules, code examples, and do/don't lists. The agent reads these when it needs to follow a specific pattern.

AGENTS.md tells the agent what the app does. Skills tell the agent how to do specific things correctly. Both are needed — AGENTS.md for orientation, skills for execution.

Skills vs memory

Skills — Authored, reusable how-to guides. Apply to every user, invoked on demand when the task matches.

Memory (LEARNINGS.md / memory/MEMORY.md) — Shared project learnings and personal structured memory loaded every turn.

If the knowledge applies to everyone working in the app ("always prefer CTEs over subqueries"), it's a skill or shared LEARNINGS.md. If it's about this particular user ("Steve likes concise answers"), it belongs in memory/MEMORY.md. See Agent Resources — Memory for the full treatment.

Skills vs SQL resources

This page frames a skill as a file at .agents/skills/<name>/SKILL.md. Agent Resources frames the same skill as a SQL resource at path skills/<slug>/SKILL.md, scoped workspace/shared/personal. These are the same concept from two angles: Code mode reads and writes the file directly; App mode stores it as a resource row so it works without a filesystem. Author the content using this page's format either way.

App-backed skills — full details

The manifest format, CLI commands, marketplace adapters, and auto-update hashing behind app-backed skills in full:

Each app-backed skill starts with agent-native.app-skill.json at the app root:

{
  "schemaVersion": 1,
  "id": "assets",
  "hosted": {
    "url": "https://assets.agent-native.com",
    "mcpUrl": "https://assets.agent-native.com/mcp"
  },
  "mcp": { "serverName": "agent-native-assets" },
  "skills": [
    {
      "path": ".agents/skills/asset-generation",
      "visibility": "both",
      "exportAs": "assets"
    }
  ]
}

Skill visibility controls what ships:

Visibility	Meaning
`internal`	Used by the app's own agent, not exported to marketplaces.
`exported`	Exported to marketplaces, but not needed by the app internally.
`both`	Used internally and exported.

Hosted is the default install path. Local launch is explicit for customization, offline work, or privacy-sensitive use.

# Happy path: exported instructions plus hosted MCP connector.
npx @agent-native/core@latest skills add visual-plan
npx @agent-native/core@latest skills add visualize-repo
npx @agent-native/core@latest skills add visual-edit
npx @agent-native/core@latest skills add assets

# Repo-first Content docs/blog/MDX editing.
npx @agent-native/core@latest skills add content --mode local-files --scope project

# Vercel/open Skills CLI: exported instructions only, no MCP config.
npx skills@latest add BuilderIO/agent-native --skill assets

# Register a hosted MCP connector for local agent clients.
npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json

# Materialize and run editable local source.
npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local

# Build marketplace adapters: Codex plugin, Claude marketplace, Vercel skills,
# plain/Claude skills, and MCP configs.
npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill

# Install a local exported bundle with the Vercel/open Skills CLI.
npx skills@latest add ./dist/assets-skill --skill assets -a codex -y

# Add the generated Claude Code marketplace, then install its Assets plugin.
claude plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace
claude plugin install agent-native-assets@agent-native-apps

Keep secrets out of skill files. The manifest should contain URL-only connector metadata; OAuth/device setup happens in the MCP host or through the app's normal settings flow.

The Vercel Labs skills adapter is a portable skills/<name>/SKILL.md bundle for npx skills@latest add ..., but the raw skills CLI installs instructions only. It does not run repo-defined postinstall scripts or register MCP connectors. Keep the Agent-Native CLI as the default docs path for local agents because it also registers the MCP connector. BuilderIO/agent-native is a real GitHub repository source for the Vercel/open Skills CLI; skills.sh is a discovery and leaderboard directory, not an npm-style package namespace.

app-skill pack also emits a standard Agent Plugin at the bundle root: plugin.json, mcp.json, and the exported skills/ directories. Import that portable bundle into an Agent-Native workspace with:

npx @agent-native/core@latest plugin import ./dist/assets-skill --into . --yes

The importer namespaces Skills under skills/<plugin>/<skill>, maps remote Streamable HTTP MCP servers into mcp.config.json, and ignores package headers so they cannot become workspace credentials. Stdio and SSE servers are reported and skipped. Authentication remains an app or host Connections concern.

The Claude Code marketplace adapter writes adapters/claude-marketplace/.claude-plugin/marketplace.json plus a nested plugin directory containing skills/<name>/SKILL.md and .mcp.json. In Claude Code, add the marketplace, install agent-native-assets@agent-native-apps, reload plugins, then authenticate the URL-only MCP connector from /mcp.

Generated plugin manifests are set up to auto-update: the Claude Code marketplace entry sets autoUpdate: true (with commit-SHA versioning) and the Codex plugin version embeds a content hash of the bundled skills and MCP endpoint, so installed plugins pick up skill changes without re-packing. The Plan app is published this way as a ready-to-add marketplace at the repo root — see Plan plugin & marketplace for the end-to-end install and auto-update flow.

For users who install copied skills through the universal CLI instead of a plugin marketplace, use the CLI freshness commands:

npx @agent-native/core@latest skills status visual-plan
npx @agent-native/core@latest skills update visual-plan

skills update scans known Codex/Claude project and user skill folders, compares the copied folder hash to the latest bundled skill, and rewrites stale folders in place. Newly copied Agent-Native skills include an agent-native-skill.json marker so future status output can identify the source and hash.

Generated Agent-Native apps and workspaces also include framework-provided skills under .agents/skills (or packages/shared/.agents/skills in a workspace). Refresh those scaffolded skills from the current/latest CLI with:

npm run skills:update
# or, without relying on the local package script:
npx @agent-native/core@latest skills update scaffold --project

AGENTS.md and .agents/skills stay canonical. The update command also repairs Claude compatibility links (CLAUDE.md and .claude/skills) so Claude Code sees the same instructions without maintaining a second copy.

What's next

Writing Agent Instructions — word skill descriptions and split guidance across AGENTS.md, skills, and memory
Agent Resources — where skills live as SQL resources in App mode
Agent Mentions — the /-command trigger that invokes a skill in chat
Plan plugin & marketplace — a real app-backed skill's end-to-end install and auto-update flow