# Skill Authoring > Guide for creating and maintaining user-facing agent skills Use when this capability is needed. - Skill: `tomevault-io/skill-authoring-5` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/skill-authoring-5` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/skill-authoring-5/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/skill-authoring-5 --- # Skill Authoring Guide This skill guides you through creating user-facing agent skills. For the canonical reference, see [agentskills.io](https://agentskills.io/home). ## Skill Structure A skill is a folder containing a `SKILL.md` file with metadata and instructions: ``` my-skill/ ├── SKILL.md # Required: instructions + metadata ├── scripts/ # Optional: executable code ├── references/ # Optional: additional documentation └── assets/ # Optional: templates, resources ``` ## SKILL.md Format ### Required Frontmatter ```yaml --- name: skill-name description: Brief description of what the skill does --- ``` - **name**: Unique identifier (lowercase, hyphens) - **description**: One-line summary (loaded at startup for all skills - a maximum of 1000 characters) ### Instructions Body The body contains markdown instructions that tell the agent how to perform the task. ```markdown --- name: my-skill description: Does something useful --- # Skill Title Brief overview of what this skill helps accomplish. ## When to Use Describe scenarios when this skill applies. ## How to Use Step-by-step instructions or patterns. ## Examples Concrete examples demonstrating usage. ## Reference - [Detailed Reference](references/REFERENCE.md) - Link to additional docs ``` ## Progressive Disclosure Structure skills for efficient context usage: | Layer | Token Budget | When Loaded | |-------|--------------|-------------| | Metadata | ~100 tokens | At startup (all skills) | | Instructions | < 5000 tokens | When skill activated | | References | As needed | On demand | ### Guidelines 1. **Keep SKILL.md under 500 lines** - Move detailed content to references 2. **Front-load key information** - Put most important patterns first 3. **Use tables for quick reference** - Easy to scan 4. **Link to references** - Don't inline everything ## Optional Directories ### scripts/ Executable code that agents can run: ``` scripts/ ├── validate.sh # Validation script ├── generate.py # Code generator └── setup.js # Setup helper ``` Scripts should: - Be self-contained or document dependencies - Include helpful error messages - Handle edge cases gracefully ### references/ Additional documentation loaded on demand: ``` references/ ├── PATTERNS.md # Common patterns ├── API.md # API reference └── EXAMPLES.md # Extended examples ``` Keep individual reference files focused. Smaller files = less context usage. ### assets/ Static resources: ``` assets/ ├── template.xml # File templates ├── schema.json # Schemas └── diagram.png # Visual aids ``` ## File References Use relative paths from the skill root: ```markdown See [the reference guide](references/REFERENCE.md) for details. Run the setup script: scripts/setup.sh ``` Keep references one level deep. Avoid deeply nested chains. ## Skill Categories ### Developer Skills (`.claude/skills/`) Skills for contributors working on this codebase: - Command development patterns - Testing approaches - API client patterns - Documentation standards ### User-Facing Skills (`plugins/*/skills/`) Skills for users of the tool: - CLI command usage - Platform-specific patterns (B2C Commerce) - Integration guides ## Writing Effective Skills ### 1. Start with the User's Goal ```markdown ## Overview This skill helps you [accomplish X] by [doing Y]. ``` ### 2. Provide Quick Reference Tables ```markdown | Command | Description | |---------|-------------| | `cmd1` | Does X | | `cmd2` | Does Y | ``` ### 3. Show Concrete Examples ```markdown ## Examples ### Basic Usage \`\`\`bash b2c command --flag value \`\`\` ### Advanced Usage \`\`\`bash b2c command --complex-flag \`\`\` ``` ### 4. Explain When NOT to Use ```markdown ## When NOT to Use - Scenario A (use skill-x instead) - Scenario B (manual approach better) ``` ### 5. Link to Authoritative Sources Reference official documentation rather than duplicating it: ```markdown ## Reference For complete API documentation, see [Official Docs](https://example.com/docs). ``` ## Validation Checklist Before publishing a skill: - [ ] Frontmatter has `name` and `description` - [ ] SKILL.md under 400 lines - [ ] Key information appears early - [ ] Examples are concrete and runnable - [ ] Reference links are valid - [ ] No deeply nested reference chains - [ ] Tested with target agent ## Detailed Reference - [Patterns and Examples](references/PATTERNS.md) - Patterns from B2C skills --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/taurgis) — claim your Tome and manage your conversions.