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).

228 stars 19 forksSkill & Plugin Authoring

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add pproenca/dot-skills --skill skill-authoring
Manual install
git clone --depth 1 https://github.com/pproenca/dot-skills.git /tmp/dot-skills
mkdir -p ~/.claude/skills
cp -r /tmp/dot-skills/skills/.curated/skill-authoring ~/.claude/skills/skill-authoring

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# 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.
Read the full skill on GitHub

Details

Skill name
skill-authoring
Path
skills/.curated/skill-authoring/SKILL.md
License
MIT
Repo updated
15 August 2026

FAQ

What does the Skill Authoring skill do?

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).

How do I install the Skill Authoring skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add pproenca/dot-skills --skill skill-authoring. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Skill Authoring popular?

It lives in pproenca/dot-skills, which has 228 GitHub stars and 19 forks.

Related skills

12 Factor App

228

pproenca/dot-skills

The Twelve-Factor App methodology for building scalable, maintainable cloud-native applications. Use when designing backend services, APIs, microservices, or any software-as-a-service application. Triggers on deployment patterns, configuration management, process architecture, logging, and infrastructure decisions.

Software Development19

37signals Rails

228

pproenca/dot-skills

37signals Rails coding principles and conventions from DHH, Jorge Manrubia, and the Fizzy/Basecamp/HEY codebase. This skill should be used when writing, reviewing, or refactoring Ruby on Rails code following the 37signals philosophy — vanilla Rails, CRUD controllers, rich domain models, concerns, no service objects, Hotwire, Turbo, Stimulus, Solid Queue, Solid Cache, Solid Cable, multi-tenancy, Minitest, custom auth, or DHH conventions.

Software Development19

Acceptance Pipeline Catalog

228

pproenca/dot-skills

Use when implementing, reviewing, or debugging a Gherkin acceptance-test pipeline with mutation testing. Covers parser, JSON IR, generator, runtime, step handlers, test runner, mutator, value mutation rules, execution, result classification, reporting, project layout, conformance, and agent setup. Based on Uncle Bob's Acceptance Pipeline Specification. Trigger even when the user mentions Gherkin parsing, acceptance test generation, mutation testing for acceptance tests, or building a portable test pipeline.

Testing & QA19

Skill Builder

191

jwynia/agent-skills

Build new agent skills. Use when creating diagnostic frameworks, CLI tools, or data-driven generators that follow the established skill patterns.

Skill & Plugin Authoring24

Skill Authoring Coach

110

microsoft/cat-agent-skills

Use this skill when the user asks to create, improve, review, package, genericise, or submit an Agent Skill, SKILL.md file, skill metadata, or reusable agent instruction bundle.

Skill & Plugin Authoring122

Skill Cutter

201

swyxio/skills

Critically audit or explicitly trim an existing agent skill to its behavioral core, including narrowing over-broad trigger metadata. Use when the user asks to cut, simplify, shorten, de-slop, or reduce the context cost or trigger aggressiveness of a SKILL.md or skill folder. Do not trigger merely because a skill is long or is being edited for another purpose.

Skill & Plugin Authoring12

Browse the most popular Claude skills, all skill & plugin authoring skills, or write your own with the skills generator.