◈
Skills
SKILL.md
Encode reusable procedural knowledge as YAML frontmatter + Markdown.
Skills are Markdown files with YAML frontmatter (name, description, version) that describe step-by-step procedures. They are the "how-to" guides that agents follow. The runtime loads metadata first (progressive disclosure) and only loads the full SKILL.md body when the agent activates the skill. This prevents context bloat in multi-skill environments.
Schema
SKILL.mdyaml
# skill.md — Database Migration Safety
## Purpose
Safely execute database schema migrations in production
with zero downtime and automatic rollback capability.
## When to apply
- Any schema change to production databases
- Adding, removing, or modifying columns or indexes
- Data migrations that transform existing records
## Prerequisites
- Database backup completed within last hour
- Migration tested against staging with production data copy
- Rollback script prepared and tested
## Procedure
1. Enable maintenance mode for write operations
2. Create a point-in-time snapshot of the database
3. Run migration in a transaction where supported
4. Validate schema matches expected state
5. Run smoke tests against migrated schema
6. If any test fails, execute rollback immediately
7. Disable maintenance mode
8. Monitor error rates for 30 minutes post-migration
## Verification
- All application health checks pass
- Error rate stays below 0.1% threshold
- No orphaned records or constraint violations
- Migration is recorded in the changelog
## Rollback
If any step fails after step 3:
1. Execute the rollback script
2. Restore from snapshot if rollback fails
3. Alert the on-call engineer
4. Document the failure in the incident logUsage
# Skills can reference other protocol objects
## Related tools
- database-backup (tool.yaml)
- run-migration (tool.yaml)
- health-check (tool.yaml)
## Part of capability
- database-operations (capability.yaml)Best Practices
- ✓Write procedures as numbered steps — agents follow sequences well
- ✓Include "When to apply" section so agents know when to use the skill
- ✓Always include verification steps — how to confirm success
- ✓Include rollback procedures for any destructive operations
- ✓Reference related tools and capabilities explicitly
- ✓Keep skills focused on one domain — split broad skills into parts
Anti-Patterns
- ✗Vague instructions like "make sure everything works"
- ✗Missing verification — agents cannot confirm success
- ✗No rollback plan for operations that modify state
- ✗Mixing multiple unrelated procedures in one skill
- ✗Assuming context that agents do not have