Create SkillCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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).

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Create Skill](https://modelsatlas.com/skills/builderio/create-skill/badge.svg)](https://modelsatlas.com/skills/builderio/create-skill/)

Not your listing, or something out of date? Claim or update your listing.