# Skill Authoring

> >

- **Type:** Skill
- **Install:** `agentstack add skill-ao92265-claude-code-playbook-skill-authoring`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ao92265](https://agentstack.voostack.com/s/ao92265)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ao92265](https://github.com/ao92265)
- **Source:** https://github.com/ao92265/claude-code-playbook/tree/main/skills/skill-authoring

## Install

```sh
agentstack add skill-ao92265-claude-code-playbook-skill-authoring
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill Authoring

How to write a skill that loads at the right time and does the right thing. Source: Anthropic's *Complete Guide to Building Skills for Claude*.

## The mental model: progressive disclosure (3 levels)

1. **Frontmatter (YAML)** — always in the system prompt. Just enough for Claude to decide *when* to load the skill. This is the highest-leverage thing you write.
2. **SKILL.md body** — loaded only when Claude judges the skill relevant. The full instructions.
3. **Linked files** (`references/`, `scripts/`, `assets/`) — loaded on demand. Push detail here to keep the body lean.

Goal: minimal tokens resident, full expertise available when needed.

## Folder structure

```
your-skill-name/        # kebab-case, matches `name`
├── SKILL.md            # required, exact case
├── scripts/            # optional — executable code
├── references/         # optional — docs loaded as needed
└── assets/             # optional — templates, fonts, icons
```

- **`SKILL.md`** — exactly that, case-sensitive. No `skill.md`, `SKILL.MD`.
- **No `README.md` inside the skill folder.** Docs go in SKILL.md or `references/`. (A repo-level README for humans is fine when distributing on GitHub — that lives outside the skill folder.)

## The `description` field (get this right first)

Formula: **[What it does] + [When to use it / trigger phrases] + [Key capabilities]**.

Rules:
- Must state both *what* and *when* (the phrases a user actually says).
- ` angle brackets** anywhere in frontmatter — they can inject as tags into the system prompt. Write "followed by a URL", not ``. Write "over 1k RPS", not `>1k`.
- `name`: kebab-case, no spaces/underscores/capitals, matches the folder. Never contains "claude" or "anthropic" (reserved).
- Add explicit trigger phrases and, for broad auto-triggering skills, a negative trigger ("Do NOT use this for…").

Good vs bad:
- ✅ `Analyzes Figma files and generates dev handoff docs. Use when user uploads .fig files, asks for "design specs", or "design-to-code handoff".`
- ❌ `Helps with projects.` (vague, no triggers)
- ❌ `Implements the Project entity model with hierarchical relationships.` (technical, no user triggers)

## Writing the body

- **Specific and actionable.** `Run python scripts/validate.py --input {file}` — not "validate the data".
- **Always include error handling / troubleshooting** (a `## Common Issues` section with concrete fixes).
- **Reference bundled files explicitly:** "Before X, consult `references/api-patterns.md`."
- Keep the body focused; move depth to `references/`.

## Testing (3 areas)

1. **Triggering** — loads on obvious + paraphrased requests; does NOT load on unrelated topics. Write an explicit should-trigger / should-NOT-trigger list.
2. **Functional** — produces correct outputs; scripts succeed; edge cases covered.
3. **Performance** — compare with vs without the skill (tokens consumed, tool/API calls, back-and-forth turns).

Pro tip: iterate on one hard task until it works, *then* extract the skill. Faster signal than broad testing.

## Trigger tuning

- **Under-triggering** (skill doesn't load when it should; users enable it manually) → add detail and keywords to the description, especially technical terms.
- **Over-triggering** (loads for irrelevant queries; users disable it) → add negative triggers, narrow the description.

## Pre-ship checklist + field reference

See `references/checklist.md` for the full field-requirements table and a copy-paste pre-ship checklist.

## Distribution (brief)

Zip the folder → Claude.ai Settings > Capabilities > Skills, or drop in the Claude Code skills directory. For GitHub: public repo, human README at repo root (not in the skill folder), example screenshots. API path needs `container.skills` + the Code Execution Tool beta. Use the `compatibility` frontmatter field for platform-specific requirements.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ao92265](https://github.com/ao92265)
- **Source:** [ao92265/claude-code-playbook](https://github.com/ao92265/claude-code-playbook)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ao92265-claude-code-playbook-skill-authoring
- Seller: https://agentstack.voostack.com/s/ao92265
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.