Agent skill

Skill Authoring

by pproenca in pproenca/dot-skills

Design and development best practices for Claude Code skills, MCP tools, and AI agent capabilities.

MITAuto-check passedAgent Workflows

Install Skill Authoring

skills CLI
$ npx skills add pproenca/dot-skills --skill skill-authoring -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install pproenca/dot-skills skill-authoring --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.curated/skill-authoring .claude/skills/skill-authoring && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
skill-authoring
GitHub stars
215
Token cost
~1.8k tokens
SKILL.md length
640 words
Files
52 (incl. references, assets)
Skills in repo
41
Repo updated
First seen
Licence
MIT

At a glance

Design and development best practices for Claude Code skills, MCP tools, and AI agent capabilities.

  • Works in 8 steps: Skill Metadata Design (CRITICAL) → Description Engineering (CRITICAL) → Content Structure (HIGH) → …
  • Creating skills
  • SKILL.md covers When to Apply, Core Principles, Rule Categories and Quick Reference, plus 2 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Skill Authoring is an agent skill from pproenca/dot-skills. 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).

Its SKILL.md is about 1.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 54 other files, including reference files and assets (for example `AGENTS.md`, `assets/templates/_template.md` and `metadata.json`).

It sits in Agent Workflows, covering Skill authoring and MCP servers. The repository describes itself as: A collection of AI agent skills following the Agent Skills open format. The licence is MIT.

When your agent uses it

  • Creating skills
  • Writing SKILL.md files
  • Designing tool descriptions
  • Optimizing triggers

Example prompts

  • “create a skill”
  • “skill template”
  • “write skill instructions”
  • “/skill-authoring”

Workflow steps

8 steps, taken from the step headings in SKILL.md.

  1. Skill Metadata Design (CRITICAL)
  2. Description Engineering (CRITICAL)
  3. Content Structure (HIGH)
  4. Trigger Optimization (HIGH)
  5. Progressive Disclosure (MEDIUM-HIGH)
  6. MCP Tool Design (MEDIUM)
  7. Testing and Validation (MEDIUM)
  8. Maintenance and Distribution (LOW-MEDIUM)

What it can do on your machine

Read from SKILL.md and the folder at commit cf93c57. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are yaml).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com
    • anthropic.com
    • code.claude.com
    • modelcontextprotocol.info
    • promptingguide.ai
    • leehanchung.github.io

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Skill Authoring loads about 1.8k tokens when it runs, and up to ~22k if it reads all its reference files. Until then it costs about 118 tokens; SKILL.md has 640 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~118
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~22k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from pproenca/dot-skills at commit cf93c57, republished under its MIT licence (© pproenca). 640 words, ~1,811 tokens.

Download SKILL.mdSave it as .claude/skills/skill-authoring/SKILL.md (or your agent's skills folder). This skill also uses 51 other files; get the full folder from GitHub.
name
skill-authoring
description
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).

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

PriorityCategoryImpactPrefix
1Skill Metadata DesignCRITICALmeta-
2Description EngineeringCRITICALdesc-
3Content StructureHIGHstruct-
4Trigger OptimizationHIGHtrigger-
5Progressive DisclosureMEDIUM-HIGHprog-
6MCP Tool DesignMEDIUMmcp-
7Testing and ValidationMEDIUMtest-
8Maintenance and DistributionLOW-MEDIUMmaint-

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
Show full SKILL.md (264 more words)Show less
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
  • project-conventions - Preserve repository-specific skill conventions
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 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

© pproenca, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 51 other files (references, assets) in skills/.curated/skill-authoring of pproenca/dot-skills.

  • SKILL.md
  • AGENTS.md
  • assets/templates/_template.md
  • metadata.json
  • references/_sections.md
  • references/desc-avoid-vague-terms.md
  • references/desc-differentiate-similar-skills.md
  • references/desc-include-negative-cases.md
  • references/desc-length-optimization.md
  • references/desc-specific-capabilities.md
  • references/desc-third-person-voice.md
  • references/desc-trigger-keywords.md
  • references/maint-audit-security.md
  • references/maint-changelog.md
  • references/maint-plugin-packaging.md
  • references/maint-semantic-versioning.md
  • references/mcp-allowed-tools.md
  • references/mcp-error-messages.md
  • … and 34 more

Open the folder on GitHubat commit cf93c57

Compare with similar skills

Skill Authoring next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Skill Authoring compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Skill Authoring this skillpproenca/dot-skills215—~1.8kAutomated safety check: PassMIT
Microsoft Skill CreatorMicrosoftDocs/mcp1.9k3 repos~2.1kAutomated safety check: PassCC-BY-4.0
Skill Seekers Builderyusufkaraaslan/Skill_Seekers15k—~760Automated safety check: PassMIT
Mistral Vibe Plugin Creatormistralai/mistral-vibe5.1k—~3.1kAutomated safety check: PassApache-2.0
Workflow Schema Tuningbreaking-brake/cc-wf-studio5.4k—~1.3kAutomated safety check: PassCustom licence
Muse Plugin Creatorasgeirtj/system_prompts_leaks69k—~1.8kAutomated safety check: PassCC0-1.0

Similar skills

  • Microsoft Skill Creator

    MicrosoftDocs/mcp

    Official

    Create agent skills for Microsoft technologies using official documentation.

    1.9k GitHub starsUsed in 3 repos~2.1k tokens
    Agent WorkflowsAuto-check passed
  • Skill Seekers Builder

    yusufkaraaslan/Skill_Seekers

    Detects the type of a knowledge source and uses the Skill Seekers MCP tools to turn docs, repos, PDFs or videos into packaged AI skills.

    15k GitHub stars~760 tokensUpdated 7 days ago
    Agent WorkflowsAuto-check passed
  • Mistral Vibe Plugin Creator

    mistralai/mistral-vibe

    Official

    Shows how to build a Vibe plugin package in the Agent Plugins 1.0 format, with a plugin.json manifest and optional skills, MCP servers, hooks and other components.

    5.1k GitHub stars~3.1k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Workflow Schema Tuning

    breaking-brake/cc-wf-studio

    Guides edits to cc-wf-studio's workflow schema so AI agents generate better workflows, treating schema text as prompt engineering rather than validation.

    5.4k GitHub stars~1.3k tokensUpdated yesterday
    Agent WorkflowsAuto-check passed
  • Muse Plugin Creator

    asgeirtj/system_prompts_leaks

    Creates and validates a new native Muse plugin package in the current workspace, limited to five capability families, and leaves installation to you.

    69k GitHub stars~1.8k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Codewhale Skill Creator

    codewhale-hq/Codewhale

    Guides creating or improving codewhale skills: file layout, discovery paths, writing rules and whether a need fits a skill, an MCP server, hooks or a plugin.

    41k GitHub stars~1k tokensUpdated today
    Agent WorkflowsAuto-check passed

More from pproenca/dot-skills

All 41 skills in this repo
  • Audio Voice Recovery

    pproenca/dot-skills

    Audio forensics and voice recovery guidelines for CSI-level audio analysis.

    215 GitHub stars~3.3k tokensUpdated 1 mo ago
    Auto-check passed
  • Codemod React Pipeline

    pproenca/dot-skills

    Guided, scripted pipeline for running JSX/TSX/React codemods safely across large legacy codebases.

    215 GitHub stars~1.6k tokensUpdated 1 mo ago
    Auto-check passed
  • Dev Rfc

    pproenca/dot-skills

    Create well-structured RFCs and technical proposals for software projects.

    215 GitHub stars~3.8k tokensUpdated 1 mo ago
    Auto-check passed
  • Dx Harness

    pproenca/dot-skills

    Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.

    215 GitHub stars~1.5k tokensUpdated 1 mo ago
    Auto-check passed
  • Language Spec Author

    pproenca/dot-skills

    Turn a rough idea for a language into a complete, implementable specification — a DSL, query, config/data, template, or protocol language — by interviewing the author dimension by dimension until…

    215 GitHub stars~2.4k tokensUpdated 1 mo ago
    Auto-check passed
  • Python Pep Author

    pproenca/dot-skills

    Drafting Python Enhancement Proposals (PEPs) — proposing a Python language feature, a standard library change, an interoperability standard, or an informational/process document for the Python…

    215 GitHub stars~2.1k tokensUpdated 1 mo ago
    Auto-check passed

Categories

Questions about Skill Authoring

What does Skill Authoring do?

Design and development best practices for Claude Code skills, MCP tools, and AI agent capabilities. Skill Authoring is an agent skill from pproenca/dot-skills. Design and development best practices for Claude Code skills, MCP tools, and AI agent capabilities.

When should I use Skill Authoring?

Skill Authoring fits situations like: creating skills; writing SKILL.md files; designing tool descriptions; optimizing triggers.

How do I install Skill Authoring in Claude Code?

Run `npx skills add pproenca/dot-skills --skill skill-authoring -a claude-code`. Or copy the skill folder (skills/.curated/skill-authoring in pproenca/dot-skills) into .claude/skills/skill-authoring in your project. Claude Code loads it when a task matches its description.

How do I install Skill Authoring in Codex?

Run `npx skills add pproenca/dot-skills --skill skill-authoring -a codex`. Or copy the skill folder (skills/.curated/skill-authoring in pproenca/dot-skills) into .agents/skills/skill-authoring in your project. Codex loads it when a task matches its description.

Can I use Skill Authoring in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pproenca/dot-skills --skill skill-authoring -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/skill-authoring, .gemini/skills/skill-authoring, .github/skills/skill-authoring and .opencode/skills/skill-authoring in your project.

What does Skill Authoring need to run?

SKILL.md names no scripts, command-line tools or credentials: Skill Authoring is instructions for the agent only.

Does Skill Authoring access the network?

SKILL.md names 6 domains. As links in the text: github.com, anthropic.com, code.claude.com, modelcontextprotocol.info, promptingguide.ai and leehanchung.github.io. This is read from the text; nothing was executed.

Is Skill Authoring safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Skill Authoring use?

Skill Authoring is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Skill Authoring use?

About 1.8k tokens (SKILL.md is roughly 7.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 21k tokens, read only when the agent opens those files.

What are the alternatives to Skill Authoring?

Skills that share tags, products or a category with Skill Authoring: Microsoft Skill Creator (MicrosoftDocs/mcp, 1.9k stars), Skill Seekers Builder (yusufkaraaslan/Skill_Seekers, 15k stars), Mistral Vibe Plugin Creator (mistralai/mistral-vibe, 5.1k stars) and Workflow Schema Tuning (breaking-brake/cc-wf-studio, 5.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Skill Authoring?

pproenca (a GitHub user) maintains it in pproenca/dot-skills, which has 215 GitHub stars. The repository holds 41 skills in this directory. The repository was last updated on August 15, 2026.

Source: pproenca/dot-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.