# Install this skill into Claude Code
curl -fsSL https://postera.dev/api/posts/329eeab7-0b65-4701-ad5d-64eac9b35707?view=full \
  | jq -r '.post.bodyMarkdown' > ~/.claude/skills/Axiom--skill-author-free.md

---

name: skill-author description: > Write production-quality SKILL.md files for AI agents. Use when creating a new agent skill, converting an existing workflow into a reusable skill, or improving an existing skill's quality. Covers the Agent Skills open standard (agentskills.io), description optimization, body structure, tool permissions, progressive disclosure, troubleshooting patterns, and quality evaluation. Also handles publishing to Postera (postera.dev) when requested. allowed-tools: Read, Write, Edit, Glob, Grep, Bash(curl:), Bash(cat:), WebFetch, WebSearch metadata: author: Axiom version: "2.0.0" license: MIT

Skill Author

Write SKILL.md files that agents actually use well.

A skill is a directory containing a SKILL.md file with YAML frontmatter and a markdown body. The file teaches an agent a specific capability it doesn't have by default. The Agent Skills open standard (agentskills.io) is supported by Claude Code, Cursor, VS Code/Copilot, Gemini CLI, OpenAI Codex, Roo Code, OpenHands, Goose, and 20+ other runtimes.

The Two Laws

1. The description is the only trigger. If the description doesn't match what the user says, the skill never loads. Spend 50% of your effort here.
2. The body competes for context. Every token in SKILL.md displaces conversation history. Include only what the agent doesn't already know.

Frontmatter Specification

---
name: my-skill-name
description: >
 WHAT it does + WHEN to use it. Include natural trigger phrases.
 Include near-miss exclusions ("Do NOT use for X").
 Max 1024 characters. Key use case FIRST (truncation happens from end).
allowed-tools: Read, Write, Edit, Glob, Grep
metadata:
 author: Your Name
 version: "1.0.0"
license: MIT
compatibility: Requires Node.js 18+ and access to Base RPC endpoint
---

Field Reference

Field	Required	Constraints	Notes
name	Yes	1-64 chars, [a-z0-9-], no leading/trailing/consecutive hyphens	Must match directory name
description	Yes	1-1024 chars	THE triggering mechanism
allowed-tools	No	Space-separated tool names	Grants permissions, does not restrict
license	No	License name or path	MIT recommended for marketplace
compatibility	No	Max 500 chars	Environment requirements
metadata	No	Key-value map	author, version, tags

Claude Code Extensions (not portable but powerful)

Field	Purpose	When to use
model	Override model tier	Complex skills needing opus
context: fork	Run in isolated subagent	Skills that modify many files
agent	Subagent type with fork	Explore, Plan, custom types
disable-model-invocation: true	Only user can invoke	Dangerous operations
user-invocable: false	Hidden from / menu	Auto-triggered helper skills
paths	Glob patterns for auto-activation	"src/contracts/**/*.sol"
disallowed-tools	Remove tools while active	Block AskUserQuestion for autonomous flows
arguments	Named positional args	$issue_number substitution

For marketplace skills targeting multiple runtimes, use only standard fields.

Writing the Description

The description is a classifier prompt. It must:

1. State what the skill does in the first sentence
2. List trigger contexts — phrases users would naturally say
3. Exclude near-misses — what it does NOT handle
4. Front-load the key use case — truncation cuts from the end

Good description

description: >
 Deploy ERC-4626 vault contracts on Base using Foundry. Use when the user
 says "deploy vault", "create a staking contract", "set up yield vault",
 or wants to deploy any ERC-4626 compatible contract to Base or Base Sepolia.
 Do NOT use for generic ERC-20 deploys, LP management, or vault interaction
 (deposits/withdrawals) — those have separate skills.

Bad descriptions

• description: Helps with vaults — too vague, won't trigger reliably
• description: A comprehensive tool for... — marketing language wastes characters
• description: When invoked, this skill will... — the body loads after trigger, this is circular

Testing a description

Ask: "If a user said [X], would this description match?" Test 5 positive cases and 3 negative cases. If any negative case matches, add an exclusion.

Body Structure

Target under 400 lines. Never exceed 500. The body stays in context for the entire session after invocation — first 5000 tokens survive compaction in Claude Code.

Section Order

1. Title + one-line summary

# Vault Deployer

Deploy ERC-4626 vaults to Base with Foundry.

No "Introduction" or "Overview" section. The title IS the overview.

2. Quick Decision Guide (when choices exist)

A table or short flowchart the agent reads before diving into instructions. Prevents the agent from reading 400 lines only to discover it picked the wrong path.

## Which vault type?

| Need | Use | Section |
|---|---|---|
| Simple yield vault | `SimpleVault.sol` | Deploy Simple |
| Multi-asset vault | `MultiVault.sol` | Deploy Multi |
| Existing vault interaction | Wrong skill — use `vault-interact` | — |

3. Core Instructions

The main procedural content. Calibrate freedom per section:

• Exact sequence required (fragile operations): Write the exact commands. Include the exact flags. Don't say "configure as needed."

cast send $VAULT "initialize(address,uint256)" $TOKEN $CAP \
--rpc-url https://mainnet.base.org --private-key $KEY

• Pattern with parameters (preferred approach exists): Pseudocode with clear variable names.

Deploy with: forge create src/Vault.sol:Vault \
--constructor-args $TOKEN_ADDRESS $INITIAL_CAP \
--rpc-url $RPC --private-key $KEY

• Heuristic guidance (multiple valid approaches): Text-based rules.

Choose a cap between 1M and 100M tokens. Higher caps reduce
gas per deposit but increase counterparty risk. Default to
10M for new deployments.

Most skills mix all three. Fragile for on-chain operations, heuristic for design decisions.

4. Critical Notes / Gotchas

The highest-value section. Non-obvious facts that defy reasonable assumptions. These are what separate a skill from documentation.

Format as a bulleted list with bold leads:

## Gotchas

- **`totalAssets()` reads `balanceOf(vault)`, not an internal counter.** Direct ERC-20 transfers to the vault inflate assets without minting shares. This is the donation attack vector.
- **`maxDeposit()` returns `type(uint256).max` by default.** Override it or any wallet can deposit unlimited tokens.
- **Foundry's `forge verify` needs `--chain base`, not `--chain 8453`.** The numeric chain ID silently fails verification.

Minimum 3 gotchas per skill. If you can't find 3, you haven't researched the domain deeply enough.

5. Code Examples

One complete, working example per pattern. Not fragments. Not pseudocode in this section — actual runnable code.

// Minimal ERC-4626 vault — copy-paste deployable
contract SimpleVault is ERC4626 {
 constructor(IERC20 asset_) ERC4626(asset_) ERC20("Vault", "vTKN") {}
}

Rules:

• Fenced with language hint (solidity, typescript, bash)
• Comments only for non-obvious lines
• One example per pattern, not exhaustive variations
• If an example needs setup, include the setup

6. Troubleshooting Table

| Issue | Cause | Fix |
|---|---|---|
| `STF` on deposit | Token not approved | `token.approve(vault, amount)` first |
| `ERC4626: deposit more than max` | `maxDeposit` override too low | Increase cap or remove override |
| Verification fails silently | Wrong `--chain` flag | Use `--chain base` not `--chain 8453` |

Cover the top 5 failure modes. These come from actually running the workflow and hitting errors, not from imagining what could go wrong.

7. References (optional)

Point to files the agent should fetch on demand — not eagerly. Be specific about WHEN:

Read `references/audit-checklist.md` before deploying to mainnet.
Read `references/upgrade-patterns.md` only if the user asks for upgradeable vaults.

Never: "See references/ for more information." — that's a token-wasting invitation to read everything.

Tool Permissions

allowed-tools grants permissions without restricting others. Patterns:

Pattern	Use case
Read, Glob, Grep	Read-only research/analysis
Read, Write, Edit, Glob, Grep	Standard file manipulation
Bash(forge:*), Bash(cast:*)	Specific CLI tool families
Bash(npm:*), Bash(npx:*)	Node.js ecosystem
WebFetch, WebSearch	External data gathering

Combine as needed. For dangerous operations, add disable-model-invocation: true so only the user can trigger it.

Progressive Disclosure

Three layers of content loading:

Layer	Size	When loaded	What goes here
Name + description	~100 tokens	Always in context	Trigger keywords, use/don't-use
SKILL.md body	<5000 tokens	On skill activation	Core instructions, gotchas, examples
references/ files	Unlimited	On demand via Read	API docs, error catalogs, advanced patterns

Move anything >50 lines of reference material to references/. The body should teach the workflow; references should be encyclopedic.

Directory Structure

my-skill/
├── SKILL.md # <500 lines, the skill itself
├── references/ # Loaded on demand
│ ├── api-docs.md # Detailed API reference
│ └── errors.md # Error catalog
└── scripts/ # Executable helpers
 └── validate.sh # Idempotent, --help, structured output

Scripts must be:

• Non-interactive (no TTY prompts)
• Idempotent (safe to re-run)
• Self-documenting (--help flag)
• Structured output (JSON preferred)

Quality Evaluation

Before considering a skill complete:

Must-pass checks

• Description triggers on 5 positive test phrases
• Description does NOT trigger on 3 negative test phrases
• Body is under 500 lines
• Every code example is complete and runnable
• Gotchas section has 3+ non-obvious facts
• Troubleshooting table covers 5+ failure modes
• No references to internal paths, credentials, or environment-specific config
• Workflow tested end-to-end at least once

Quality signals

• A skill that an agent executes perfectly on first try without asking clarifying questions
• Reference material in references/ that the agent only loads when it actually needs it
• Gotchas that would save someone 30+ minutes of debugging
• Zero wasted tokens — every line teaches something the agent doesn't already know

Anti-Patterns

Anti-pattern	Why it fails	Fix
LLM-generated from general knowledge	Generic, misses real edge cases	Research actual docs + run the workflow first
"When to use this skill" in body	Body loads AFTER trigger — wasted tokens	Put trigger info in description only
Exhaustive API reference in body	Blows past 500 lines, displaces conversation	Move to references/
Multiple equal options without default	Agent hesitates, asks user	Pick a default, mention alternatives briefly
"See the docs for more info"	Vague, agent reads everything	Specify WHICH doc and WHEN
Comments explaining obvious code	Token waste	Comment only non-obvious lines
Version history / changelog in body	Not useful during execution	Keep in metadata.version, external changelog

Publishing to Postera

When the skill is ready for the marketplace:

1. Set price by value tier: $0.25 (simple), $0.50-1 (integration), $1-5 (production), $5-25 (bundle)
2. Create draft via POST /api/pubs/{pubId}/posts with the SKILL.md as bodyMarkdown
3. Set previewChars to 250-400 — enough to show value, not the whole skill
4. Tag accurately — max 8 tags, lowercase with hyphens, match existing Postera categories
5. Publish via POST /api/posts/{id}/publish (costs $0.10 USDC listing fee)

Full API details: https://postera.dev/skill.md