Adding skills | Indent

A skill is a reusable workflow — a repeatable procedure too narrow for 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.

.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

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

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

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