Individual skill
skill-authoring
Design and development best practices for Claude Code skills, MCP tools, and AI agent capabilities. Use when creating skills, writing SKILL.md files, designing tool descriptions, or optimizing triggers. Triggers on "create a skill", "skill template", "write skill instructions", SKILL.md, metadata.json, progressive disclosure, trigger optimization, MCP tool design, or skill testing. Does NOT cover specific frameworks or languages (use dedicated skills).
skills/.curated/skill-authoring/SKILL.md
Source commit cf93c57cac89d6fc3e4194686000411567f5caf3
What was checked
- Matches the observed repository HEAD
- Yes
- Scanner rules are current
- No
- Repository scan complete
- No
- Skill scan complete
- Yes
- Observed behavior
- Not checked yet
- Last checked
- Nov 5, 2026
These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.
Install this skill
Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.
An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.
Repository context
- Repository stars (not skill ratings)
- 222
- Repository last updated
- Aug 15, 2026
- License
- MIT
Observed agent integration: codex
Files and excerpt
File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.
Browse files
AGENTS.mddoc · 213 bytesSKILL.mdcore · 7,246 bytesassets/templates/_template.mddoc · 663 bytesmetadata.jsonasset · 1,177 bytesreferences/_sections.mddoc · 1,863 bytesreferences/desc-avoid-vague-terms.mddoc · 1,607 bytesreferences/desc-differentiate-similar-skills.mddoc · 1,845 bytesreferences/desc-include-negative-cases.mddoc · 1,725 bytesreferences/desc-length-optimization.mddoc · 2,573 bytesreferences/desc-specific-capabilities.mddoc · 1,543 bytesreferences/desc-third-person-voice.mddoc · 1,441 bytesreferences/desc-trigger-keywords.mddoc · 1,445 bytesreferences/maint-audit-security.mddoc · 1,906 bytesreferences/maint-changelog.mddoc · 1,825 bytesreferences/maint-plugin-packaging.mddoc · 1,668 bytesreferences/maint-semantic-versioning.mddoc · 1,487 bytesreferences/mcp-allowed-tools.mddoc · 1,652 bytesreferences/mcp-error-messages.mddoc · 1,638 bytesreferences/mcp-idempotent-operations.mddoc · 1,838 bytesreferences/mcp-parameter-descriptions.mddoc · 1,798 bytesreferences/mcp-tool-naming.mddoc · 1,684 bytesreferences/mcp-tool-scope.mddoc · 2,221 bytesreferences/meta-allowed-frontmatter-fields.mddoc · 2,022 bytesreferences/meta-directory-match.mddoc · 1,478 bytesreferences/meta-frontmatter-yaml-syntax.mddoc · 1,347 bytesreferences/meta-name-format.mddoc · 1,437 bytesreferences/meta-name-hyphen-boundaries.mddoc · 1,417 bytesreferences/meta-name-length.mddoc · 1,493 bytesreferences/meta-name-no-consecutive-hyphens.mddoc · 1,674 bytesreferences/meta-name-uniqueness.mddoc · 1,270 bytesreferences/meta-required-frontmatter.mddoc · 1,587 bytesreferences/prog-lazy-load-examples.mddoc · 1,846 bytesreferences/prog-mutual-exclusion.mddoc · 1,771 bytesreferences/prog-one-level-deep-links.mddoc · 1,711 bytesreferences/prog-scripts-execute-not-read.mddoc · 1,855 bytesreferences/prog-three-level-disclosure.mddoc · 2,054 bytesreferences/project-conventions.mddoc · 2,319 bytesreferences/struct-code-blocks-with-language.mddoc · 1,424 bytesreferences/struct-header-hierarchy.mddoc · 1,364 bytesreferences/struct-imperative-instructions.mddoc · 1,600 bytesreferences/struct-instructions-first.mddoc · 1,680 bytesreferences/struct-line-limit.mddoc · 1,597 bytesreferences/struct-single-responsibility.mddoc · 1,669 bytesreferences/test-edge-cases.mddoc · 1,992 bytesreferences/test-instruction-clarity.mddoc · 1,873 bytesreferences/test-negative-scenarios.mddoc · 2,188 bytesreferences/test-trigger-phrases.mddoc · 1,984 bytesreferences/trigger-error-patterns.mddoc · 1,568 bytesreferences/trigger-file-type-patterns.mddoc · 1,587 bytesreferences/trigger-slash-command-aliases.mddoc · 1,438 bytesreferences/trigger-synonym-coverage.mddoc · 1,615 bytesreferences/trigger-workflow-stages.mddoc · 1,665 bytes
Read excerpt
# 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