---
title: "Adding skills"
description: "Package a reusable workflow as a committed SKILL.md so Indent pulls it in when a task matches."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.indent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding skills

A skill is a reusable workflow — a repeatable procedure too narrow for
[AGENTS.md](/learning/agents-md) but too important to explain every time.

## Where they live

Commit skills under `.agents/skills/` in your repository. Each skill gets its own directory, one
level deep, containing a `SKILL.md` and any supporting files it needs.

```text
.agents/
  skills/
deploy/
  SKILL.md
  scripts/
    deploy.sh
db-migration/
  SKILL.md
incident-triage/
  SKILL.md
  references/
    runbook.md
```

Because skills are committed to the repository, they are versioned and reviewed in pull requests
alongside your code.

## What goes in SKILL.md

Every `SKILL.md` must start with YAML frontmatter, or Indent skips the skill. The frontmatter needs:

- `name` — a path-safe identifier matching `^[a-z0-9_-]+$`.
- `description` — a non-empty line describing when the skill applies.

After the frontmatter, write when to use the skill and the steps to follow. The more concrete the
instructions, the more reliably Indent executes the workflow.

### Example: deploy

```md
---
name: deploy
description: Deploy a service to staging or production.
---

# Deploy

## When to use

When deploying a service to staging or production.

## Steps

1. Run `pnpm build` and confirm it succeeds
2. Run `pnpm test` — do not deploy if tests fail
3. For staging: push to the `staging` branch
4. For production: create a pull request to the `release` branch
   - Title format: `release: <service> <version>`
   - Wait for CI to pass before merging
5. After merge, monitor the Datadog dashboard "Service Health" for 10 minutes before confirming the
   deploy is stable

## Notes

- Never force-push to `release`
- If a deploy needs to be rolled back, revert the merge commit and push to `release` again
```

### Example: db-migration

```md
---
name: db-migration
description: Add or change the database schema safely.
---

# Database migration

## When to use

When a task requires changes to the database schema.

## Steps

1. Create the migration with `pnpm prisma migrate dev --name <description>`
2. Check that the generated SQL in `prisma/migrations/` looks correct
3. If the migration is destructive (dropping columns, changing types), add a two-phase approach:
   - First pull request: make the column nullable or add the new column
   - Second pull request: backfill data and remove the old column
4. Run `pnpm test:integration` to verify against a real database
5. Note in the pull request description that this includes a migration

## Notes

- Migrations run automatically on deploy — they must be backward-compatible with the currently
  running code
- Never edit a migration that has already been applied to staging or production
```

### Example: incident-triage

```md
---
name: incident-triage
description: Investigate a production incident or alert.
---

# Incident triage

## When to use

When investigating a production incident or alert.

## Steps

1. Check the Datadog dashboard for the affected service
2. Pull recent error logs from Sentry for the relevant time window
3. Identify whether the issue correlates with a recent deploy — check the last 3 merged pull
   requests on the `release` branch
4. If a deploy caused it, draft a revert pull request
5. If not deploy-related, investigate the error stack trace and check for recent changes to the
   affected code paths
6. Write up findings as a comment in the incident thread

## References

- See `references/runbook.md` for service-specific escalation paths
```

## When Indent picks up a change

Indent reads skills from the repository's default branch and refreshes them within a few minutes of
a push. A skill on another branch isn't picked up until it merges.

A `SKILL.md` whose frontmatter is missing or invalid is skipped without an error, so if a new skill
never gets used, check `name` and `description` first. A repository can hold up to 256 skills.

## AGENTS.md, memory, and skills

`AGENTS.md`, memory, and skills all give Indent context that persists, but each fits a different
kind of guidance.

- **[`AGENTS.md`](/learning/agents-md)** holds repository facts that stay true across most tasks.
  You write it and commit it to the repository, so it is versioned, reviewed in pull requests, and
  read in full at the start of every session that includes that repository. Use it for setup,
  architecture, conventions, testing, and deployment.
- **[Memory](/learning/memory)** holds what Indent should carry across sessions but isn't tied to
  one repository. Indent writes memory as it works, and you can ask it to remember something
  directly. Each note is filed as personal to you or shared with your organization. Use it for your
  preferences, conventions that span repositories, and facts you teach Indent in passing.
- **Skills** hold a specific, repeatable procedure that's too narrow for `AGENTS.md`. You commit a
  skill to the repository, and Indent pulls it in only when a task matches. Use it for a workflow
  like deploying one service or triaging a class of incident.

Source: https://docs.indent.com/learning/skills/index.mdx