Initial commit from agent-native create
This commit is contained in:
agent-native
@@ -0,0 +1,221 @@
|
||||
---
|
||||
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/<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).
|
||||
Reference in New Issue
Block a user