secondsky__claude-skills/docs/guides/CONTRIBUTING.md

Contributing to Claude Code Skills

Thank you for your interest in contributing! This guide will help you create high-quality skills for the Claude Code community.

🚀 Quick Start: Use our templates! Copy templates/skill-skeleton/ to get started in minutes. 📋 Checklist: Verify your work with ONE_PAGE_CHECKLIST.md 📖 Workflow: See QUICK_WORKFLOW.md for step-by-step process ⚠️ Avoid Mistakes: Read COMMON_MISTAKES.md

---

⚠️ Prerequisites (REQUIRED)

1. Install Official Plugin-Dev Toolkit

BEFORE creating any plugins or skills:

/plugin install plugin-dev@claude-code-marketplace

This provides the 8-phase guided workflow, 7 skills, and 3 agents for plugin fundamentals.

2. 🚨 CRITICAL: Read System Prompt Budget Documentation

⚠️ REQUIRED READING: PLUGIN_DEV_BEST_PRACTICES.md Section 4

Why this is critical:

• Claude Code has a 15,000 character TOTAL budget for ALL skill descriptions combined
• When exceeded, skills are silently omitted from the system prompt (no warnings)
• With 169 skills: 15,000 ÷ 169 = ~88 characters average per description
• Your skill will be invisible to Claude if descriptions are too long

Optimization requirements:

• ✅ Ideal: Under 100 characters
• ⚠️ Maximum: 150 characters
• ❌ Danger: 200+ characters (WILL cause silent omissions)

Example (from Section 4):

# ❌ 143 chars - Too verbose (causes omission with 169 skills)
description: This skill helps you process and analyze Excel spreadsheets with advanced formatting and data validation capabilities for business reports

# ✅ 87 chars - Optimized (works reliably)
description: Processes Excel files with formatting and validation. Use for business reports.

See PLUGIN_DEV_BEST_PRACTICES.md for:

• Complete system prompt budget documentation (Section 4)
• Detection and monitoring techniques
• Progressive disclosure optimization
• Repository-specific workflows (marketplace, installation, versioning)

---

🔒 Security hooks

This repo ships a pre-commit hook in .githooks/ that runs gitleaks secret scanning and JSON-schema validation before each commit. Hooks are opt-in: install them once per clone before your first commit:

git config core.hooksPath .githooks

CI re-runs the same checks (and more), so a skipped hook will still be caught — but installing it locally gives you instant feedback and keeps secrets out of your branch history. See .githooks/README.md for details, and SECURITY.md for the disclosure policy. Reviewers apply the checklist in docs/guides/PLUGIN_SECURITY_REVIEW.md when assessing plugin PRs.

---

🎯 Skill Development Guidelines

What Makes a Good Skill?

A good skill should:

✅ Solve a specific, repeated problem - Not a one-off solution ✅ Be well-documented - Clear README with auto-trigger keywords ✅ Include working templates - Ready-to-copy files ✅ Prevent known errors - Document common pitfalls ✅ Be production-tested - Actually used in real projects

---

📁 Skill Structure Standard

Every skill MUST follow this structure:

skills/[skill-name]/
├── README.md              # REQUIRED - Auto-trigger keywords
├── SKILL.md               # REQUIRED - Complete documentation
├── templates/             # REQUIRED - File templates
│   ├── config-file.ext
│   ├── main-file.ext
│   └── ...
├── examples/              # OPTIONAL - Working examples
│   └── example-project/
├── scripts/               # OPTIONAL - Automation scripts
│   └── setup.sh
└── reference/             # OPTIONAL - Deep-dive docs
    └── advanced-topics.md

---

📝 Required Files

1. README.md

Purpose: Quick reference with auto-trigger keywords

Required sections:

# [Skill Name]

**Status**: [Production Ready / Beta / Experimental]
**Last Updated**: YYYY-MM-DD
**Production Tested**: [Link or description]

---

## Auto-Trigger Keywords

### Primary Triggers:
- keyword1
- keyword2
- keyword3

### Secondary Triggers:
- related-term1
- related-term2

### Error-Based Triggers:
- common-error-message
- typical-problem

---

## What This Skill Does

[2-3 sentence description]

✅ Feature 1
✅ Feature 2
✅ Feature 3

---

## Known Issues This Skill Prevents

| Issue | Why It Happens | How Skill Fixes It |
|-------|---------------|-------------------|
| Error 1 | Cause | Solution |
| Error 2 | Cause | Solution |

---

## When to Use This Skill

### ✅ Use When:
- Scenario 1
- Scenario 2

### ❌ Don't Use When:
- Scenario 1
- Scenario 2

---

## Quick Usage

[Step-by-step quick start]

2. SKILL.md

Purpose: Complete documentation

Required sections:

• Detailed setup instructions
• Configuration examples
• Critical rules (Always Do / Never Do)
• Common issues & fixes
• Dependencies
• Reference links

---

🔑 Auto-Trigger Keywords

Keywords are critical for skill auto-discovery. Include:

Primary Keywords (3-5)

• Exact technology names: tailwind v4, cloudflare workers
• Common phrases: vite + react, dark mode setup

Secondary Keywords (5-10)

• Related technologies: shadcn/ui, hono routing
• Use cases: theme switching, jwt verification

Error Keywords (2-5)

• Common error messages users search for
• Typical problems: colors not working, build fails

---

📦 Template Files

Templates should be:

✅ Complete - Ready to use, not snippets ✅ Commented - Explain non-obvious parts ✅ Current - Use latest package versions ✅ Tested - Actually works in production

Example Template:

// templates/vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': '/src',  // Path alias for clean imports
    },
  },
})

---

🧪 Testing Your Skill

Before submitting, verify:

1. Auto-discovery works

   • Test that Claude finds your skill with trigger keywords
   • Verify skill is suggested when appropriate

2. Templates are complete

   • Copy templates to new project
   • Run build/dev server
   • Verify no errors

3. Documentation is clear

   • Someone unfamiliar can follow SKILL.md
   • All common errors are documented
   • Examples work

---

🚀 Submission Process

1. Create Your Skill

cd ~/Documents/claude-skills

# Create skill directory
mkdir -p skills/my-skill/{templates,examples,scripts}

# Add required files
touch skills/my-skill/README.md
touch skills/my-skill/SKILL.md

# Add templates
# ...

2. Test Locally

# Install skill (Claude Code)
/plugin install my-skill@claude-skills

# Or cross-harness (Cursor, Codex, opencode, Gemini CLI, ...)
npx skills add secondsky/claude-skills --skill my-skill

# Test auto-discovery
# Ask Claude to perform a task that should trigger your skill

3. Update Planning Doc

Update roadmap documentation if needed:

## my-skill

**Status**: Ready for review
**Priority**: [High/Medium/Low]
**Dependencies**: [Other skills needed]

4. Submit Pull Request

git checkout -b add-my-skill
git add skills/my-skill
git commit -m "Add my-skill for [use case]"
git push origin add-my-skill

Create PR with:

• Clear description of what the skill does
• Token efficiency metrics
• Production testing evidence
• Screenshots/examples

---

✅ Review Checklist

Before submitting, ensure:

• README.md has auto-trigger keywords
• SKILL.md is complete and accurate
• Templates are tested and work
• No hardcoded secrets or credentials
• Dependencies are documented
• Known issues are listed with fixes
• Token efficiency is measured
• Skill tested in ~/.claude/skills/
• Roadmap documentation updated if needed
• Examples work (if provided)

---

🤝 Community Standards

Code of Conduct

• Be respectful and constructive
• Help others learn and improve
• Share knowledge openly
• Credit sources and inspiration

Quality Over Quantity

We prefer:

• 1 excellent, well-tested skill
• Over 10 untested, incomplete skills

Maintenance

• Update skills when dependencies change
• Respond to issues promptly
• Document breaking changes
• Test with latest Claude Code versions

---

💡 Skill Ideas

Looking for ideas? We need skills for:

• Databases: Prisma, Drizzle, TypeORM
• Testing: Vitest, Playwright, Jest
• Deployment: Railway, Fly.io, Render
• APIs: tRPC, GraphQL, REST patterns
• State Management: Zustand, Jotai, Redux
• Mobile: React Native, Capacitor
• Desktop: Tauri, Electron

---

📞 Getting Help

• Issues: https://github.com/secondsky/claude-skills/issues
• Discussions: https://github.com/secondsky/claude-skills/discussions
• Email: maintainers@example.com

---

🙏 Thank You!

Your contributions make Claude Code better for everyone. We appreciate your time and effort!

---

Happy skill building! 🚀