claude-plugins/claude-skills-plugin/README.md

Claude Skills Plugin

Meta-skill for creating effective Agent Skills with best practices, structure guidelines, and progressive disclosure principles.

What's Included

The claude-skills skill provides comprehensive guidance for building high-quality Agent Skills that work efficiently with Claude Code and Claude.ai.

claude-skills (Skill Creator)

A comprehensive guide covering:

• Progressive disclosure - Three-layer architecture (metadata → instructions → resources)
• Trigger optimization - Writing descriptions that activate at the right time
• Token efficiency - Strategic file splitting and on-demand loading
• Development workflow - Iterative approach to skill creation
• Security considerations - Best practices for safe skill creation and usage

Includes:

• SKILL.md - Complete best practices guide
• examples.md - Working examples across different domains
• templates.md - Ready-to-use templates for common skill types
• checklist.md - Quality assurance checklist
• README.md - Skill-specific overview

When to Use This Skill

Use this skill when:

• Creating a new Agent Skill from scratch
• Improving or refactoring an existing skill
• Debugging why a skill isn't triggering correctly
• Understanding skill architecture and design patterns
• Optimizing skill structure for token efficiency

Installation

For Claude Code

Install from marketplace:

/plugin install claude-skills@claude-skills-marketplace

Or install from local directory:

/plugin install /path/to/Skills/claude-skills-plugin@local

For Claude.ai

1. Zip this plugin directory
2. Go to Settings > Capabilities > Upload skill
3. Upload the zip file
4. Enable the plugin

Usage

Once installed, the skill activates automatically when you work on skill-related tasks:

"Help me create a skill for Python testing"
"Why isn't my skill triggering?"
"How do I optimize my skill for token usage?"
"Review my skill structure"

Key Concepts

Progressive Disclosure

Skills use a three-layer architecture:

Layer 1: Metadata (Always Loaded)

• YAML frontmatter with name and description
• ~100 tokens per skill
• Used for trigger detection

Layer 2: Instructions (Triggered)

• Main SKILL.md content
• Procedural guidance and workflows
• Loaded when skill is relevant

Layer 3: Resources (On-Demand)

• Additional files, scripts, reference materials
• Loaded only when explicitly needed
• Maximizes token efficiency

Writing Effective Descriptions

The description field determines when your skill triggers:

Good Descriptions:

description: Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables. Use when working with .xlsx files, data analysis, or generating reports.

Poor Descriptions:

description: Helps with coding tasks

Skill Structure

Every skill MUST have:

---
name: Your Skill Name (max 64 chars)
description: Clear description with use cases (max 1024 chars)
---

# Skill content

What You'll Learn

From SKILL.md

• When to use progressive disclosure
• How to write effective descriptions
• Structuring content for scannability
• Token optimization techniques
• Development workflow best practices
• Security considerations

From examples.md

• Python testing with pytest
• REST API integration patterns
• Technical documentation writing
• Real-world skill structures

From templates.md

• Code framework skill template
• Workflow/process skill template
• Reference/lookup skill template
• Tool/utility skill template

From checklist.md

• Metadata requirements
• Content quality checks
• Trigger testing scenarios
• Security review items

Quick Start

Creating Your First Skill

1. Ask Claude: "Help me create a skill for [your topic]"
2. Claude will guide you through:
   • Choosing the right template
   • Writing an effective description
   • Structuring content efficiently
   • Adding concrete examples

Improving an Existing Skill

1. Ask Claude: "Review my skill at [path]"
2. Claude will analyze:
   • Trigger accuracy
   • Structure optimization
   • Content clarity
   • Best practices alignment

Best Practices Summary

DO:

• Keep SKILL.md focused and concise
• Use clear, scannable hierarchies
• Include concrete, working examples
• Reference additional files explicitly
• Start simple, expand based on need

DON'T:

• Create vague descriptions
• Add unnecessary complexity upfront
• Hardcode sensitive data
• Skip testing trigger scenarios

Development Workflow

1. Start with Evaluation - Work with Claude on tasks, identify patterns
2. Iterate Collaboratively - Let Claude help structure the skill
3. Test Triggering - Verify activation with target scenarios
4. Start Simple - Begin minimal, expand based on actual needs

Skills Checklist

Before finalizing a skill:

• Name ≤ 64 characters
• Description ≤ 1024 characters and specific
• Description includes trigger scenarios
• SKILL.md has valid YAML frontmatter
• "When to Use This Skill" section present
• At least one concrete example included
• No sensitive information hardcoded
• File references are accurate
• Tested triggering with target scenarios
• Tested NOT triggering with unrelated scenarios

Common Patterns

Code Development Skills

---
name: [Framework] Development Guide
description: Build [framework] applications following [patterns]. Use when building [type] with [requirements].
---

Workflow Skills

---
name: [Task] Workflow
description: Execute [task] following [methodology]. Use when [scenario].
---

Reference Skills

---
name: [Topic] Reference
description: Quick reference for [domain]. Use when looking up [specific aspects].
---

Resources

• Official Documentation
• Engineering Blog
• Using Skills Guide

Version History

1.0.0 (Initial Release)

• Complete best practices guide (SKILL.md)
• Working examples across domains (examples.md)
• Ready-to-use templates (templates.md)
• Quality assurance checklist (checklist.md)

Contributing

Found an issue or have improvements? See the main marketplace CONTRIBUTING.md.

License

See main marketplace repository for license information.

---

Remember: The best skills emerge from real usage patterns. Start simple, iterate based on actual needs, and prioritize clarity over comprehensiveness.