Writing high-quality protocol skills
This guide follows the same documentation style used by strong skills on skills.sh: clear scope, structured references, and actionable rules. Your job is not to expose every SDK detail. Your job is to teach the agent where to look, what to trust, and what sequence to execute.
Reference anchor: vercel-react-best-practices
When to apply
- Use protocol skills when implementation accuracy matters more than generic code generation.
- Use them for transaction flows, risk checks, endpoint selection, and production-ready defaults.
- Assume agents can handle common tasks, but nuanced protocol behavior needs explicit instruction.
Guide format (recommended)
| Section | What it must include |
|---|---|
| Purpose | What this skill solves and when to invoke it |
| Trusted sources | Official endpoints, verified docs, and repo links |
| Execution flow | Ordered steps with validation checkpoints |
| Landing guidance | Compute budget, fees, Jito path, retries |
| Failure handling | Known failure modes and mitigations |
Quick reference: Jupiter swap skill
For a “build swap transaction with Jupiter API” skill, include the high-signal pieces below. This is the difference between a useful skill and “figure it out from SDK docs”.
- Quote endpoint and swap endpoint with request/response expectations.
- Verified token source and required token-mint validation checks.
- Transaction landing context: compute unit strategy, priority fee defaults, and Jito guidance when useful.
- Failure handling for slippage limits, stale quote windows, and simulation errors.
- Security notes: signer assumptions, token allowlists, and replay-safe behavior.
How to use in your skill repo
Keep the top-level `SKILL.md` concise and link to focused rule files. Each rule file should include:
- Why this rule exists
- Bad example (what to avoid)
- Good example (preferred approach)
- Links to official protocol references
Anti-patterns to avoid
- Dumping SDK methods without flow control and decision logic
- Forcing the agent to infer protocol-specific nuances from raw docs
- Skipping endpoint trust model and validation requirements
- Ignoring tx-landing strategy (compute budget, fees, and retries)
Minimal template
# <Protocol Skill Name> ## When to Apply - ... ## Trusted Endpoints - quote: ... - swap: ... - verified tokens: ... ## Flow 1. Validate inputs 2. Fetch quote 3. Build transaction 4. Simulate and verify 5. Send with landing strategy ## Failure Modes - stale quote: ... - slippage exceeded: ... - simulation fail: ...