Skill Authoring

If you're building skills for Claude Code or MCP tools, this gives you the actual engineering practices that make them work reliably. It's 46 rules across metadata design, description engineering, and trigger optimization, the stuff that determines whether your skill activates when users need it or just sits there. The core insight is solid: descriptions drive activation, so you need specific capabilities and keywords upfront, not buried in implementation details. Progressive disclosure is broken down into a three-level system (overview, references, execution) that keeps token usage reasonable. Most valuable for the trigger optimization and testing sections, they're specific about covering synonyms and negative cases. Think of it as the missing manual for why some skills work and others don't.

skills.sh installs: 330
GitHub stars: 222
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add pproenca/dot-skills --skill skill-authoring --agent claude-code

Installs into .claude/skills of the current project.

Files

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.

SKILL.md on GitHub