mcpField
S
skill-creation-guide

skill-creation-guide

github.com/gmh5225Agent workflows9740 installsUpdated 5d ago
Repository

About skill-creation-guide

A guide for creating Agent Skills, covering SKILL.md structure, authoring practices, token efficiency, and platform-specific paths. It is intended for skill authors who need a practical format and quality checklist.

Key features

  1. 01SKILL.md structure and frontmatter
  2. 02Authoring and progressive disclosure guidance
  3. 03Token efficiency overview
  4. 04Platform-specific skill paths
  5. 05Quality checklist

Use cases

  1. 01Start a new Agent Skill
  2. 02Check required SKILL.md metadata
  3. 03Choose skill installation paths by platform
  4. 04Review a skill against authoring criteria

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/gmh5225/awesome-skills --skill skill-creation-guide

After installing, type/skill-creation-guidein Claude Code to confirm it loaded.

Details

From the project README

Skill Creation Guide

Scope

Use this skill when:

  • Creating new Agent Skills
  • Understanding SKILL.md format and conventions
  • Learning best practices for skill authoring

Skill Structure

skill-name/
├── SKILL.md          # Required: Instructions and metadata
├── scripts/          # Optional: Helper scripts
├── templates/        # Optional: Document templates
└── resources/        # Optional: Reference files

SKILL.md Format

Required Frontmatter
---
name: my-skill-name
description: A clear description of what this skill does and when to use it.
---
Body Structure
# Skill Name

Detailed description of the skill's purpose.

## When to Use This Skill

- Use case 1
- Use case 2

## Instructions

[Detailed instructions for the agent]

## Examples

[Real-world examples]

Best Practices

  1. Keep descriptions exhaustive: The frontmatter description helps agents decide when to trigger the skill.
  2. Focus on execution: The body should contain clear, actionable steps.
  3. Use progressive disclosure: Put detailed references in references/ folder.
  4. Include scripts for automation: Use helper scripts for deterministic operations.
  5. Keep SKILL.md under 500 lines: For optimal performance.
  6. Test across platforms: Verify skills work with Claude Code, Codex, etc.

Token Efficiency

Skills employ progressive disclosure architecture:

  1. Metadata loading (~100 tokens): Agent scans available skills
  2. Full instructions (<5k tokens): Load when skill is activated
  3. Bundled resources: Only load as needed

Platform-Specific Paths

PlatformProject PathGlobal Path
Claude Code.claude/skills/~/.claude/skills/
Codex.codex/skills/~/.codex/skills/
Cursor.cursor/skills/~/.cursor/skills/
Gemini CLI.gemini/skills/~/.gemini/skills/
GitHub Copilot.github/skills/~/.copilot/skills/

Quality Checklist

  • Clear, actionable instructions
  • Includes real-world examples
  • Written for AI agents, not end users
  • Documents prerequisites and dependencies
  • Includes error handling guidance
  • Tested on target platform(s)

Full Resource List

For more detailed skill creation resources, complete link lists, or the latest information, use WebFetch to retrieve the full README.md:

https://raw.githubusercontent.com/gmh5225/awesome-skills/refs/heads/main/README.md

The README.md contains the complete categorized resource list with all links.

Comments

Markdown supported