# Skills: example scenario

A skill packages the five-step "change the database schema safely" procedure for ticket-service, with a check script the model runs on demand.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/skills/example-scenario

## Scenario

In `ticket-service`, "add a column" goes wrong in different ways: the agent edits an old migration, forgets `pnpm db:generate`, or never checks that the migration applies. The procedure has five steps and is needed only when the schema changes, so it is too long and too rarely used to sit in the always-loaded [instruction file](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files).

This page shows one way to fix that: a skill named `add-migration` that bundles the steps, a check script and the naming rules.

## Before → after

| | Before | After |
|---|---|---|
| Consistency | Each run improvises the procedure | Every run follows the same five steps |
| Context cost | The steps sit in the instruction file on every turn | Only a one-sentence description is always loaded |
| Risk | A broken or edited migration is found in review | A script checks it before the agent reports back |
| Effort | You re-explain the steps each time | You say "add a priority column to tickets" |

## Design

**Diagram:** The description is always in context; the instructions load when the task matches; the reference and script load or run only on demand.

- Metadata — name and description, always loaded
- → task matches
- add-migration — SKILL.md instructions
- → if called for
- On demand:
  - Reference — drizzle-conventions.md
  - Script — check-migration.sh

Generic layout of the skill (file and folder names differ per agent):

```text
add-migration/
├── SKILL.md                            instructions + metadata
├── scripts/check-migration.sh          deterministic check
└── references/drizzle-conventions.md   naming rules, read when needed
```

Generic `SKILL.md`:

```text
---
name: add-migration
description: Change the ticket-service database schema safely: edit
  src/db/schema.ts, generate a migration with pnpm db:generate, and
  verify it. Use for any new table, column or index.
---
Requested change: <argument>
Existing migrations: <output of `ls src/db/migrations`>
1. Read references/drizzle-conventions.md.
2. Edit src/db/schema.ts for the requested change.
3. Run `pnpm db:generate`. Never edit files in src/db/migrations/.
4. Run scripts/check-migration.sh and fix what it reports.
5. Summarize the new migration file and its SQL.
```

Where the agent supports pre-injected data, the migration list is filled in when the skill loads; otherwise the instructions tell the model to run `ls src/db/migrations` first. You invoke the skill automatically (the model matches your task to the description) or explicitly, for example `/add-migration add a priority column to tickets`; the exact syntax differs per agent.

The script:

```bash
#!/usr/bin/env bash
# Fails if an existing migration was edited or the new one does not apply.
set -euo pipefail
changed=$(git diff --name-only --diff-filter=M HEAD -- src/db/migrations)
if [ -n "$changed" ]; then
  echo "Existing migrations were edited: $changed" >&2; exit 1
fi
pnpm db:migrate
pnpm test
echo "Migration OK"
```

## What happens at runtime

<steps>

<step title="Task arrives">

You type "add a priority column to tickets". The context holds the skill's name and description, nothing more.

</step>

<step title="Description matches">

The model sees that the task fits the description, or you invoke the skill yourself. The harness loads `SKILL.md`, with your request and the migration list filled in.

</step>

<step title="Model edits and generates">

The model reads the conventions file, edits `src/db/schema.ts` and runs `pnpm db:generate`.

</step>

<step title="Script runs">

The model runs `check-migration.sh`. The harness executes it, and the script's output, pass or fail, returns to the model.

</step>

<step title="Model reports">

The model fixes what the script reported, then summarizes the new migration file and its SQL.

</step>

</steps>

## What can go wrong

| Failure | How you notice | What to do |
|---|---|---|
| Vague description: the skill never triggers, or triggers on unrelated tasks | The agent improvises a migration, or the procedure appears during other work | Name the task and the trigger words in the description; invoke it explicitly while you tune it |
| The script needs a database the environment lacks | `pnpm db:migrate` fails on connection, not on the change | Give the environment a test database, or make the script fail with a clear message |
| A skill from someone else runs code with your permissions | A script you did not write or read executes | Read skills before installing them; see the [security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model) |
| Instructions drift from `package.json` scripts | The skill calls a renamed or missing script | Update the skill in the same pull request that changes the scripts |
| The model skips the script | The summary arrives with no script output in the transcript | The skill is still guidance; for a guarantee, enforce the check with a [hook](https://ai-sw-factory.mellicci.dev/fundamentals/hooks) |