# Skill Authoring

> AI Agent Skills Best Practices

- Skill: `comeonoliver/skill-authoring` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/skill-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/skill-authoring/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/comeonoliver/skill-authoring

---

# AI Agent Skills Best Practices

Design and development guide for AI agent skills, including Claude Code skills and MCP tools. Contains 46 rules across 8 categories, prioritized by impact to guide skill creation, review, and optimization.

## When to Apply

- Creating new Claude Code skills or MCP tools
- Writing or reviewing SKILL.md metadata and descriptions
- Optimizing skill trigger reliability
- Structuring content for progressive disclosure
- Testing skill activation and behavior
- Designing tool interfaces for agent workflows

## Core Principles

**1. Descriptions drive activation.** Claude selects skills based on description matching against user intent. Include specific capabilities, trigger keywords, and negative cases. A skill with a vague description activates inconsistently or never.

**2. Front-load critical instructions.** Claude may truncate long content. Place non-negotiable rules in the first 100 lines. Bury important constraints at the end and they get ignored.

**3. Progressive disclosure saves tokens.** Load detailed content only when needed. A 2000-line skill wastes context on every activation. Structure as: SKILL.md (overview) → references/ (details) → scripts/ (execution).

**4. Test activation, not just execution.** A skill that works perfectly but never triggers provides zero value. Test with real user phrases, synonyms, and edge cases before deployment.

**5. One skill per domain.** Overlapping skills create activation conflicts. Split by clear boundaries (language, framework, workflow stage) with distinct trigger keywords.

## Rule Categories

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Skill Metadata Design | CRITICAL | `meta-` |
| 2 | Description Engineering | CRITICAL | `desc-` |
| 3 | Content Structure | HIGH | `struct-` |
| 4 | Trigger Optimization | HIGH | `trigger-` |
| 5 | Progressive Disclosure | MEDIUM-HIGH | `prog-` |
| 6 | MCP Tool Design | MEDIUM | `mcp-` |
| 7 | Testing and Validation | MEDIUM | `test-` |
| 8 | Maintenance and Distribution | LOW-MEDIUM | `maint-` |

## Quick Reference

### 1. Skill Metadata Design (CRITICAL)

- `meta-name-format` - Use lowercase hyphenated skill names
- `meta-name-hyphen-boundaries` - Never start or end names with hyphens
- `meta-name-no-consecutive-hyphens` - Avoid consecutive hyphens in names
- `meta-name-uniqueness` - Ensure skill names are globally unique
- `meta-required-frontmatter` - Include all required frontmatter fields
- `meta-allowed-frontmatter-fields` - Use only allowed frontmatter fields
- `meta-frontmatter-yaml-syntax` - Use valid YAML frontmatter syntax
- `meta-name-length` - Keep skill names under 64 characters
- `meta-directory-match` - Match skill name to directory name

### 2. Description Engineering (CRITICAL)

- `desc-specific-capabilities` - Name specific capabilities in description
- `desc-trigger-keywords` - Include user trigger keywords in description
- `desc-third-person-voice` - Write descriptions in third person
- `desc-length-optimization` - Optimize description length for discovery
- `desc-avoid-vague-terms` - Avoid vague terms in descriptions
- `desc-differentiate-similar-skills` - Differentiate similar skills with distinct triggers
- `desc-include-negative-cases` - Include negative cases for precision

### 3. Content Structure (HIGH)

- `struct-header-hierarchy` - Use consistent header hierarchy
- `struct-instructions-first` - Put critical instructions early in content
- `struct-imperative-instructions` - Write instructions in imperative mood
- `struct-code-blocks-with-language` - Specify language in code blocks
- `struct-line-limit` - Keep SKILL.md under 500 lines
- `struct-single-responsibility` - One skill per domain

### 4. Trigger Optimization (HIGH)

- `trigger-slash-command-aliases` - Include slash command aliases in description
- `trigger-file-type-patterns` - Include file type patterns in description
- `trigger-workflow-stages` - Reference workflow stages in description
- `trigger-error-patterns` - Include error patterns in debugging skills
- `trigger-synonym-coverage` - Cover synonyms and alternate phrasings

### 5. Progressive Disclosure (MEDIUM-HIGH)

- `prog-three-level-disclosure` - Implement three-level progressive disclosure
- `prog-one-level-deep-links` - Limit reference links to one level deep
- `prog-scripts-execute-not-read` - Execute scripts instead of reading code
- `prog-lazy-load-examples` - Lazy load examples and reference material
- `prog-mutual-exclusion` - Separate mutually exclusive contexts

### 6. MCP Tool Design (MEDIUM)

- `mcp-tool-naming` - Use clear action-object tool names
- `mcp-parameter-descriptions` - Document all tool parameters
- `mcp-error-messages` - Return actionable error messages
- `mcp-tool-scope` - Design single-purpose tools
- `mcp-allowed-tools` - Use allowed-tools for safety constraints
- `mcp-idempotent-operations` - Design idempotent tool operations

### 7. Testing and Validation (MEDIUM)

- `test-trigger-phrases` - Test skill activation with real user phrases
- `test-edge-cases` - Test skills with edge case inputs
- `test-negative-scenarios` - Test that skills do NOT trigger on unrelated requests
- `test-instruction-clarity` - Test instructions with fresh context

### 8. Maintenance and Distribution (LOW-MEDIUM)

- `maint-semantic-versioning` - Use semantic versioning for skill releases
- `maint-changelog` - Maintain a changelog for skill updates
- `maint-plugin-packaging` - Package skills as plugins for distribution
- `maint-audit-security` - Audit skills before installing from external sources

## Creating Rules

Copy [assets/templates/_template.md](assets/templates/_template.md) and follow the frontmatter schema:

```yaml
---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified impact (e.g., "2-10x improvement")
tags: prefix, technique, related-concepts
---
```

Reference files use the pattern: `references/{prefix}-{slug}.md`

## References

- [skills-ref specification](https://github.com/agentskills/agentskills/tree/main/skills-ref)
- [Anthropic Engineering: Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
- [Anthropic Skills Repository](https://github.com/anthropics/skills)
- [MCP Best Practices](https://modelcontextprotocol.info/docs/best-practices/)
- [Prompt Engineering Guide: LLM Agents](https://www.promptingguide.ai/research/llm-agents)
- [Claude Skills Deep Dive](https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/)