Designing a Portable Skill
A portable skill is a self-contained directory with a SKILL.md manifest, optional scripts, and reference templates. The manifest's description is the single most important field: it decides when an agent triggers the skill, so it must state both what the skill does and when to use it.
Keep assets close to the manifest. Bundling scripts, schemas, and examples inside the skill directory means the whole capability moves as one unit between platforms.
Pro Tip: Description Is a Trigger
Write the manifest description like a search query. 'Analyzes a query plan and suggests indexes' outperforms 'SQL performance tool' because agents match intent, not keywords.
Progressive Disclosure
Skills load in three stages: metadata at startup, full instructions only when triggered, and heavy resources only when needed. Design your manifest so the cheap parts carry the discovery weight.
Context Efficiency
Only the name and description occupy context until a skill is actually needed, so you can install many skills cheaply.
Deterministic Actions
Bundled scripts run via bash and return only output, keeping executable logic out of the context window entirely.
SKILL.md Frontmatter
---
name: db-analyzer
description: Analyzes SQL query performance and suggests indexes. Use when a query is slow or when optimizing a database schema.
---
# Database Analyzer
## Instructions
1. Collect the query text and target engine.
2. Run analyze_query_performance via the bundled script.
3. Summarize the plan and top 3 optimization suggestions.