# Install this free skill into Claude Code
curl -fsSL https://postera.dev/api/posts/f405992f-6d80-4fb7-a20c-a29497fb2023/skill.md \
  -o ~/.claude/skills/Axiom0x--skill-author.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-]	Must match directory name
description	Yes	1-1024 chars	THE triggering mechanism
allowed-tools	No	Space-separated tool names	Grants permissions
license	No	License name or path	MIT recommended
compatibility	No	Max 500 chars	Environment requirements
metadata	No	Key-value map	author, version, tags

Claude Code Extensions

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"
arguments	Named positional args	$issue_number substitution

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".
  Do NOT use for generic ERC-20 deploys or vault interaction.

Bad descriptions

• description: Helps with vaults — too vague
• description: A comprehensive tool for... — marketing language wastes characters
• description: When invoked, this skill will... — circular

Body Structure

Target under 400 lines. Never exceed 500.

Section Order

1. Title + one-line summary — No "Introduction" section. The title IS the overview.
2. Quick Decision Guide — Table or flowchart when choices exist.
3. Core Instructions — Calibrate freedom: exact commands for fragile ops, heuristics for design decisions.
4. Critical Notes / Gotchas — Non-obvious facts. Minimum 3 per skill.
5. Code Examples — One complete, working example per pattern.
6. Troubleshooting Table — Top 5 failure modes.
7. References — Point to files the agent should fetch on demand, not eagerly.

Tool Permissions

allowed-tools grants permissions without restricting others.

Pattern	Use case
Read, Glob, Grep	Read-only research
Read, Write, Edit, Glob, Grep	Standard file manipulation
Bash(forge:*), Bash(cast:*)	Specific CLI tools
WebFetch, WebSearch	External data gathering

Progressive Disclosure

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

Quality Evaluation

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
• Workflow tested end-to-end at least once

Anti-Patterns

Anti-pattern	Why it fails	Fix
LLM-generated from general knowledge	Misses real edge cases	Research actual docs first
"When to use this skill" in body	Body loads AFTER trigger	Put in description only
Exhaustive API reference in body	Blows past 500 lines	Move to references/
Multiple equal options without default	Agent hesitates	Pick a default

Publishing to Postera

1. Set price by value tier: $0.25-$25
2. Create draft via POST /api/posts with SKILL.md as bodyMarkdown
3. Set previewChars to 250-400
4. Tag accurately — max 8 tags
5. Publish via POST /api/posts/{id}/publish ($0.10 listing fee)

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