Skills & Runbooks

import { Badge } from ‘@astrojs/starlight/components’;

An Agento Skill is a modular, self-contained pack of specialized instructions, domain workflows, and helper scripts designed to teach Agento how your team builds software.

Progressive Disclosure Architecture

Traditional AI agents suffer from permanent context bloat when instructions for dozens of tools are loaded simultaneously.

Agento solves this with a Progressive Disclosure model:

1. Lightweight Indexing: At session start, Agento indexes only the high-level metadata (name, description, file triggers) into a compact 3-line catalog.
2. On-Demand Loading: Full instructions, checklists, and templates are loaded into the prompt only when the agent or user invokes them (via /skill or matching file triggers).
3. Deterministic Scripts: Helper scripts packaged within a skill run through Agento’s plan-gated execution pipeline with full consent logging.

---

Skill Directory Structure

A skill resides in its own folder containing a SKILL.md file:

.agento/skills/<skill-name>/
├── SKILL.md          # YAML frontmatter + structured instructions
├── scripts/          # Optional deterministic helper scripts
├── templates/        # Optional file templates or boilerplate assets
└── references/       # Optional deep-dive docs loaded on demand

Standard SKILL.md Format

---
name: database-migrations
description: "Workflows and safety invariants for writing Prisma and SQL schema migrations"
version: "1.0.0"
triggers:
  globs: ["prisma/schema.prisma", "migrations/**/*.sql"]
  keywords: ["migration", "schema", "database"]
---

# Database Migration Guidelines

## Invariants
1. Never generate destructive drop table migrations without explicit human approval.
2. Always write reversible `down.sql` scripts alongside `up.sql`.

## Step-by-Step Workflow
1. Update schema definition.
2. Run `./scripts/generate-migration.sh` to generate the migration file.
3. Validate against local development database.

---

Storage Scopes & Precedence

Skills can be defined across two standard scopes:

Scope	Location	Description
Project (Highest)	<workspace>/.agento/skills/	Repository-specific runbooks and domain workflows.
Global / User	~/.config/agento/skills/	Personal cross-project skill library.

If a skill with the same name exists in both scopes, the project-level skill takes precedence.