Skills & Reusable Workflows

What Skills Are

A skill is a reusable, task-specific instruction bundle that an agent activates when the current task matches the skill’s description. Skills are structured natural language — not compiled code or deterministic scripts. They give the agent a playbook (context, constraints, steps, scoped tools) while the agent retains discretion over execution.

Skills solve a scaling problem: root instruction files define project-wide behavior, but embedding every specialized workflow (migrations, deployments, code review, releases) bloats context and reduces signal. Skills decompose specialized workflows into self-contained units that load only when relevant.

Universal Skill Structure

graph TD
    S["SKILL.md<br/><i>Instructions + YAML frontmatter</i><br/><b>Always loaded on activation</b>"]
    SC["scripts/<br/><i>Executable automation</i>"]
    RF["references/<br/><i>Docs loaded on demand</i><br/>NOT in main context"]
    AS["assets/<br/><i>Templates, boilerplate</i>"]

    S --> SC
    S --> RF
    S --> AS

    T["Task matches description"] -->|"auto-activate"| S
    U["/skill-name"] -->|"manual invoke"| S

    style S fill:#eef2ff,stroke:#c7d2fe
    style RF fill:#fefce8,stroke:#fde68a

SKILL.md is the only required file — metadata in YAML frontmatter, step-by-step instructions in the body. scripts/ contains deterministic operations the agent should run rather than improvise. references/ holds detailed documentation the agent pulls in selectively, keeping SKILL.md lean. assets/ stores templates and boilerplate the skill’s instructions reference as starting points.

Cross-Platform Mapping

Key Properties

• Auto-Activation: Skills declare a natural-language description; the agent matches tasks semantically and activates the skill without explicit invocation. Description quality directly determines activation accuracy.
• Manual Override: Users can force-activate with /skill-name. Skills can set disable-model-invocation: true to require explicit invocation — critical for dangerous workflows like production deployments.
• On-Demand Loading: Only SKILL.md loads on activation. The agent pulls in references/ files selectively when deeper context is needed, keeping the context window lean.
• Isolation: Skills with context: fork run in a sub-agent with their own context window, preventing long executions from polluting the main conversation.
• Scoped Tools: The allowed-tools field restricts which tools the agent may use during execution, enforcing least privilege mechanically.
• Path-Specific Activation: The paths field (glob patterns) restricts activation to matching files — essential in monorepos where directories have different tooling.

SKILL.md Anatomy

A complete SKILL.md has YAML frontmatter defining metadata and behavior, followed by markdown instructions defining the workflow.

---
name: db-migration
description: >
  Generate and validate database migration files for PostgreSQL schema changes.
  Handles column additions, table creation, index management, and enum
  modifications. Always generates both up and down migrations.
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash(alembic *)
  - Bash(psql *)
  - Bash(make db-*)
context: fork
paths:
  - "services/api/models/**/*.py"
  - "services/api/migrations/**/*.py"
disable-model-invocation: false
---

# Database Migration

## Pre-flight

1. Read the current model definitions in `services/api/models/`.
2. Run `!alembic heads` to confirm migration chain is linear. If multiple heads
   exist, stop and report the conflict.
3. Load the schema conventions reference if the change involves enums, partial
   indexes, or composite keys:
   @references/schema-conventions.md

## Generate Migration

4. Create the migration with `alembic revision --autogenerate -m "<description>"`.
5. Open the generated migration file and verify:
   - The `upgrade()` function matches the intended schema change.
   - The `downgrade()` function correctly reverses the change.
   - No unintended changes were captured by autogenerate.
6. If the migration includes data transformations, add them manually. Alembic
   autogenerate does not detect data migrations.

## Validate

7. Run `make db-migrate-test` to apply the migration against a test database.
8. Run `make db-rollback-test` to verify the downgrade path.
9. Run `make test` to confirm no existing tests break.

## Output

10. Report: migration file path, summary of changes, test results.

Best Practices

• Write specific, matchable descriptions. Include task types handled, technologies involved, and scope boundaries. The agent uses semantic similarity, so natural phrasing beats keyword stuffing. Vague descriptions cause false positives; overly narrow ones cause false negatives.
• Keep SKILL.md lean — move details to references/. SKILL.md should read like an executive briefing. Detailed conventions and long checklists belong in references/ and load conditionally. A 60-line SKILL.md referencing detailed docs outperforms a 300-line monolith.
• Use allowed-tools for least privilege. Every skill should declare the minimum tool set required. Start with none and add as the skill fails — over-permissioning is harder to diagnose.
• Compose skills through instruction files. Skills can reference other skills in their instructions (e.g., a release skill invokes /run-tests, then /changelog, then /deploy-staging in sequence), building complex workflows from simple, tested units.