secondsky__claude-skills/docs/guides/PLUGIN_DEV_BEST_PRACTICES.md

Claude Skills Repository: Plugin Development Best Practices

Last Updated: 2025-12-28 Version: 3.0.0 Target Audience: Plugin developers contributing to the claude-skills collection

---

Table of Contents

1. Background & Rationale
2. Prerequisites (CRITICAL)
3. Marketplace Management
4. System Prompt Budget Optimization
5. Quality Assurance at Scale
6. Repository-Specific Workflows
7. Production Quality Standards
8. Integration with Official Plugin-Dev

---

Background & Rationale

Why This Document Exists

After analyzing the official Anthropic plugin-dev plugin and our repository's documentation needs, we identified a clear division of responsibilities:

✅ Official plugin-dev provides: Comprehensive plugin fundamentals (7 skills, 3 agents, 21k+ words) ✅ This document provides: Repository-specific gaps not covered by official plugin-dev

Recommendation: Install official plugin-dev@claude-code-marketplace as your primary resource, then use this document for claude-skills repository-specific workflows.

---

What Official Plugin-Dev Covers

The official plugin provides 7 comprehensive skills with ~21,000+ words of production-tested guidance:

Skill	Coverage	When to Use
hook-development	Prompt-based hooks, command hooks, all events, validation	Creating PreToolUse/PostToolUse hooks, blocking dangerous operations
mcp-integration	Server types (stdio/SSE/HTTP/WS), auth, env vars, tool usage	Adding MCP servers, OAuth configuration, WebSocket connections
plugin-structure	Directory layout, plugin.json, auto-discovery, components	Organizing plugins, configuring manifests, file naming
plugin-settings	.local.md pattern, YAML frontmatter parsing, flag files	User-configurable plugins, per-project settings
command-development	Slash commands, frontmatter, arguments, bash execution	Creating /custom-command with arguments and file references
agent-development	Agent structure, frontmatter, system prompts, AI-assisted generation	Creating autonomous agents with triggers and tools
skill-development	SKILL.md structure, progressive disclosure, trigger descriptions	Writing skills with strong auto-discovery

Plus:

• /plugin-dev:create-plugin command (8-phase guided workflow)
• 3 agents: agent-creator, plugin-validator
• 10 utility scripts for validation
• 21 reference docs (~11k words)
• 9 working examples

Total: ~21,000+ words of comprehensive, production-tested guidance

---

What We Document (Repository-Specific Gaps)

This repository has 5 critical gaps not covered by official plugin-dev:

Gap	Why It's Unique to Us	Where Documented
1. Marketplace Management	Managing 169 skills across 58 plugins with automated category detection and keyword generation	Section 3, MARKETPLACE_MANAGEMENT.md
2. System Prompt Budget	Critical 15k char limit causing silent skill omission (production issue)	Section 4
3. Batch Operations	Quality workflows for large skill collections (169 skills)	Section 5
4. Repository Workflows	Installation scripts, version sync, git standards for claude-skills	Section 6
5. Production Quality at Scale	Testing evidence requirements, package verification for 169 skills	Section 7

---

Official vs Repository: Responsibility Matrix

Area	Official Plugin-Dev	This Document
Plugin fundamentals (structure, manifest)	✅ PRIMARY	Reference only
Hooks (PreToolUse, PostToolUse, events)	✅ PRIMARY	Reference only
MCP integration (stdio, SSE, OAuth)	✅ PRIMARY	Reference only
Agents (creation, triggers, tools)	✅ PRIMARY	Reference only
Commands (slash commands, arguments)	✅ PRIMARY	Reference only
Skills (writing, triggers, discovery)	✅ PRIMARY	Reference only
Marketplace management (169 skills)	❌	✅ PRIMARY
System prompt budget (15k char limit)	❌	✅ PRIMARY
Batch operations (quality workflows)	❌	✅ PRIMARY
Repository workflows (install, sync)	❌	✅ PRIMARY
Description optimization (token limits)	❌	✅ PRIMARY

---

Critical Knowledge We Preserve

MUST document in our best practices (not in official plugin-dev):

1. ✅ System prompt budget (15,000 char limit)
2. ✅ Silent skill omission issue (no warnings when exceeded)
3. ✅ Description optimization (under 100 chars ideal)
4. ✅ Marketplace.json generation and structure
5. ✅ Category system (18 categories with auto-detection)
6. ✅ Keyword generation (3 sources: name, category, description)
7. ✅ Version synchronization (sync-plugins.sh for 169 skills)
8. ✅ Batch skill operations and quality workflows
9. ✅ Progressive disclosure optimization workflow
10. ✅ Repository-specific git workflow (secondsky vs jezweb)

NOT needed (covered by official plugin-dev):

1. ❌ Hook development basics
2. ❌ MCP integration basics
3. ❌ Agent creation basics
4. ❌ Command development basics
5. ❌ Plugin manifest basics
6. ❌ Skill structure basics
7. ❌ YAML frontmatter basics

---

Key Principle: Don't Duplicate What Anthropic Maintains

Our value-add is:

• Repository-specific workflows (marketplace, installation, versioning)
• Production insights (system prompt budget, silent omission)
• Scale management (169 skills, batch operations, quality workflows)

We defer to official plugin-dev for:

• Plugin fundamentals (structure, manifest, components)
• Advanced features (hooks, MCP, agents, commands)
• Core skill writing guidance (triggers, discovery, progressive disclosure)

Rule: If plugin-dev covers it, use plugin-dev. If it's repository-specific to claude-skills, use this doc.

---

Prerequisites (CRITICAL)

Install Official Plugin-Dev Toolkit (REQUIRED)

BEFORE creating any plugins in this repository, you MUST install the official plugin development toolkit:

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

What Official Plugin-Dev Provides

The official plugin-dev plugin is your primary resource for all plugin fundamentals:

Skill	Use When
hook-development	Creating hooks (PreToolUse, PostToolUse, etc.), validating operations
mcp-integration	Adding MCP servers (stdio, SSE, HTTP, WebSocket), OAuth, env vars
plugin-structure	Organizing plugin directories, configuring plugin.json manifest
command-development	Creating slash commands with frontmatter and arguments
agent-development	Creating autonomous agents with system prompts
skill-development	Writing skills with progressive disclosure and strong triggers

Plus:

• /plugin-dev:create-plugin command (8-phase guided workflow)
• agent-creator agent (AI-assisted agent generation)
• plugin-validator agent (structure validation)

What This Document Covers

This document focuses ONLY on repository-specific gaps not covered by official plugin-dev:

1. ✅ Marketplace Management - Managing 169 skills across 58 plugins (unique to this repo)
2. ✅ System Prompt Budget - Critical 15k character limit and optimization (production issue)
3. ✅ Batch Operations - Quality workflows for large skill collections (169 skills)
4. ✅ Repository Workflows - Installation, versioning, git standards (repo-specific)

Rule: If plugin-dev covers it, use plugin-dev. If it's repository-specific, use this doc.

Quick Decision Tree

I want to →
├─ Create plugin structure → Use: /plugin-dev:create-plugin
├─ Add hooks → Use: hook-development skill
├─ Add MCP server → Use: mcp-integration skill
├─ Create agent → Use: agent-creator agent
├─ Create command → Use: command-development skill
├─ Write skill → Use: skill-development skill
│
├─ Manage marketplace → THIS DOC: Section 2
├─ Optimize descriptions → THIS DOC: Section 3
├─ Batch review skills → THIS DOC: Section 4
└─ Install/version skills → THIS DOC: Section 5

---

Marketplace Management

Overview

The claude-skills repository maintains a marketplace registry that allows Claude Code to discover and use production-ready skills. With 169 skills organized into 58 plugins, proper marketplace management is critical.

Key Components:

• marketplace.json - Central registry listing all 169 skills
• plugin.json - Individual plugin metadata (one per skill)
• Category system - 18 categories with auto-detection
• Keyword generation - Automated from 3 sources
• Version synchronization - Global version across all plugins

For comprehensive technical details, see MARKETPLACE_MANAGEMENT.md.

Primary Script: sync-plugins.sh

Single entry point for all plugin management.

# Full sync - updates all plugin.json files and regenerates marketplace.json
./scripts/sync-plugins.sh

# Preview changes without modifying files
./scripts/sync-plugins.sh --dry-run

# Show help
./scripts/sync-plugins.sh --help

What it does:

1. Reads global version from marketplace.json metadata
2. Syncs version to all 169 plugin.json files
3. Auto-detects category based on skill name patterns
4. Scans agents/ and commands/ directories → adds to plugin.json
5. Generates keywords from name + category + description
6. Regenerates marketplace.json with updated metadata

When to run:

• After adding new skills
• After modifying skill descriptions
• After adding agents/commands to a skill
• Before releases or PRs

Category System (18 Categories)

Skills are auto-categorized based on name patterns:

Category	Pattern Match	Examples
cloudflare	^cloudflare-	cloudflare-d1, cloudflare-workers-ai
ai	^(gemini-|ml-|model-)	gemini-cli, ml-model-training
frontend	^(nextjs|nuxt-|react-|tanstack-)	nuxt-v4, tailwind-v4-shadcn
auth	^(better-auth)	better-auth
database	^drizzle-	drizzle-orm-d1
api	^(api-|graphql-|rest-api-)	api-design-principles
testing	^(jest-|mutation-|playwright-|vitest-)	vitest-testing
mobile	^(app-store-|mobile-|react-native-)	react-native-skills
tooling	Default fallback	turborepo, code-review

Distribution (Current):

• tooling: 28 skills
• cloudflare: 23 skills
• frontend: 21 skills
• ai: 20 skills
• (see MARKETPLACE_MANAGEMENT.md for complete list)

Keyword Generation (3 Sources)

Keywords are auto-generated from:

1. Name keywords: Split skill name by - (e.g., cloudflare-d1 → ["cloudflare-d1", "cloudflare"])
2. Category keywords: Domain-specific terms (e.g., cloudflare → ["workers", "edge", "serverless"])
3. Description keywords: Technical terms extracted from description

Best practices:

• Let the system auto-generate (don't manually edit)
• Keep descriptions keyword-rich for better extraction
• Run sync-plugins.sh to regenerate after description changes

Common Marketplace Operations

# Check marketplace plugin count
jq '.plugins | length' .claude-plugin/marketplace.json
# Expected: 169

# Verify all versions match
jq -r '.version' plugins/*/.claude-plugin/plugin.json | sort -u
# Expected: 3.0.0 (one version only)

# Category distribution
jq -r '.category' plugins/*/.claude-plugin/plugin.json | sort | uniq -c

# Find skills without categories (should be empty)
for f in plugins/*/.claude-plugin/plugin.json; do
  if ! jq -e '.category' "$f" > /dev/null 2>&1; then
    echo "Missing category: $f"
  fi
done

---

System Prompt Budget Optimization

The Critical 15,000 Character Limit

⚠️ CRITICAL PRODUCTION ISSUE - This is the #1 cause of skill discovery failures.

The Problem

Claude Code has a 15,000 character TOTAL budget for ALL skill descriptions in the system prompt:

Total budget = 15,000 characters (for ALL skills combined)

What happens when exceeded:

• ❌ Skills are silently omitted from the system prompt
• ❌ No warnings or errors displayed
• ❌ Claude cannot see or use omitted skills (invisible)
• ❌ User has no idea why skills don't trigger

With 169 skills, this means:

15,000 chars ÷ 169 skills = ~88 chars per skill (average)

Reality check: If descriptions average >88 characters, skills WILL be silently dropped.

Source: Claude Code Skills Not Triggering

Description Optimization Strategy

Target Lengths

Priority	Length	Use Case
Ideal	Under 100 chars	Simple, focused skills
Good	100-150 chars	Standard skills
Maximum	150-200 chars	Complex skills only
Danger Zone	200+ chars	Will cause omissions with 169 skills

Optimization Techniques

1. Remove articles ("the", "a", "an"):

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

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

2. Use active, third-person voice:

# ❌ First person (wastes chars)
description: I can help you build Cloudflare Workers with Hono

# ✅ Third person (concise)
description: Builds Cloudflare Workers with Hono framework

3. Focus on triggers, not features:

# ❌ Feature list (verbose)
description: Provides comprehensive knowledge for React Server Components, streaming, and async rendering patterns

# ✅ Trigger-based (concise)
description: React Server Components, streaming. Use when building RSC apps.

4. Omit redundant context:

# ❌ Redundant (mentions "skill" twice)
description: This skill provides guidance on API design patterns for building RESTful services

# ✅ Direct (assumes it's a skill)
description: API design patterns for RESTful services

Detection & Monitoring

Check current budget usage:

# Count total characters in all descriptions
jq -r '.plugins[].description' .claude-plugin/marketplace.json | \
  awk '{total += length} END {print "Total chars:", total, "/ 15000"}'

# Find longest descriptions (troublemakers)
jq -r '.plugins[] | "\(.name): \(.description | length) chars"' \
  .claude-plugin/marketplace.json | sort -t: -k2 -rn | head -20

Example output:

Total chars: 14,237 / 15000 (Good - 763 chars remaining)

cloudflare-durable-objects: 187 chars
better-auth: 176 chars
nextjs: 165 chars

Warning signs:

• ✅ Under 12,000 chars: Safe zone
• ⚠️ 12,000-14,000 chars: Warning - optimize long descriptions
• 🚨 14,000-15,000 chars: Danger - skills likely being omitted
• ❌ Over 15,000 chars: Critical - skills definitely omitted

Workaround: Increase Budget

Temporary workaround (until descriptions are optimized):

# Set environment variable before launching Claude Code
SLASH_COMMAND_TOOL_CHAR_BUDGET=30000 claude

This doubles the budget to 30,000 characters. However, this is a workaround, not a solution. Proper optimization is still required for:

• Performance (smaller system prompts load faster)
• Compatibility (future Claude Code versions may not respect this)
• Best practices (concise descriptions are better for discovery)

Description Review Checklist

Before committing skill changes, verify:

• Description under 150 characters (ideal: under 100)
• Third-person active voice ("Builds...", not "I can help...")
• No articles ("the", "a", "an") unless necessary
• Trigger phrases included ("Use when...", "For...")
• Technical keywords present (for discovery)
• Run sync-plugins.sh to regenerate marketplace
• Check total budget: jq -r '.plugins[].description' .claude-plugin/marketplace.json | awk '{total += length} END {print total}'

---

Quality Assurance at Scale

Batch Review Workflows

With 169 skills, quality assurance requires systematic batch workflows, not individual reviews.

Automated Baseline Validation

Status: All 169 skills passed automated validation (2025-11-20)

# Run baseline validation
./scripts/baseline-audit-all.sh

# Check compliance
# - YAML frontmatter valid
# - Required fields present (name, description)
# - File structure correct
# - No syntax errors

Result: 100% pass rate (0 critical, 0 high, 0 medium issues)

Manual Review Process

CRITICAL: Manual review is REQUIRED for quality. Do NOT automate refactoring.

Why manual:

1. Context-aware decisions - Extracting content requires understanding what's essential
2. Quality over speed - 30min-2hrs per skill ensures quality
3. Judgment required - Only humans can determine "Quick Start" vs "Advanced Topics"
4. Error prevention - Automation can introduce subtle errors that break skills

Process (Use ONE_PAGE_CHECKLIST.md):

# Manual review for individual skill
# Check against: docs/getting-started/ONE_PAGE_CHECKLIST.md
# Verify with: ./scripts/check-versions.sh

# For batch reviews:
# 1. Review Tier 1 skills first (most critical)
# 2. Then Tier 2, Tier 3, etc.
# 3. Document research findings

Time estimates:

• Simple skill (under 300 lines): 30-60 minutes
• Standard skill (300-500 lines): 1-1.5 hours
• Complex skill (over 500 lines): 1.5-2 hours

Progressive Disclosure Optimization

Goal: Keep SKILL.md under 500 lines by extracting content to references/ directory.

Process (Manual):

1. Read entire SKILL.md - Identify sections >100 lines
2. Determine what stays - Quick Start, Top 3-5 errors must stay in SKILL.md
3. Extract to references/ - Move advanced/detailed content
4. Update SKILL.md - Replace with summary + pointer: "Load references/advanced.md when..."
5. Add "When to Load References" - Critical section for Claude to know what to load when
6. Verify - Read final SKILL.md, check <500 lines, test skill triggering

Example extraction:

<!-- BEFORE (in SKILL.md) - 200 lines -->
## Advanced Configuration (200 lines)
Detailed steps for complex scenarios...
[massive wall of text]

<!-- AFTER (in SKILL.md) - 5 lines -->
## Advanced Configuration
Basic configuration for standard cases...

For complex scenarios: Load `references/advanced-configuration.md`

Example "When to Load References" section:

## When to Load References

Load the following references only when user needs them:

- **references/advanced-configuration.md** - Complex multi-region setups, custom domains
- **references/troubleshooting.md** - Error resolution, debugging patterns
- **references/migration-guide.md** - Upgrading from v1 to v2

Otherwise, use core SKILL.md instructions for standard workflows.

Compliance Verification

Before committing any skill changes:

# Quick checklist verification
# See ONE_PAGE_CHECKLIST.md for complete checklist

# Verify:
# 1. YAML frontmatter valid (name + description)
# 2. Description under 150 chars (ideally under 100)
# 3. SKILL.md under 500 lines
# 4. No [TODO:] markers remaining
# 5. Templates tested and working
# 6. References properly organized

---

Repository-Specific Workflows

Template-Based Skill Creation

Standard workflow (5 minutes):

# 1. Copy skill template
cp -r templates/skill-skeleton/ plugins/my-plugin/

# 2. Edit SKILL.md and README.md (fill TODOs)
# 3. Add resources (scripts/, references/, templates/)

# 4. Install locally for testing
/plugin install my-plugin@claude-skills

# 5. Verify discovery
# Ask Claude Code to use the skill - does it trigger?

# 6. Sync marketplace
./scripts/sync-plugins.sh

# 7. Commit
git add plugins/my-plugin .claude-plugin/marketplace.json
git commit -m "Add my-plugin skill"
git push origin <branch>

Alternative: Guided workflow:

# Use official plugin-dev guided workflow
/plugin-dev:create-plugin

# Follow 8-phase process:
# 1. Discovery
# 2. Component Planning
# 3. Detailed Design
# 4. Structure Creation
# 5. Component Implementation
# 6. Validation
# 7. Testing
# 8. Documentation

Local Installation

Install individual skill:

/plugin install my-plugin@claude-skills

# Verify
ls -la ~/.claude/skills/my-plugin

Install all skills (cross-harness):

npx skills add secondsky/claude-skills --skill '*'

# Auto-detects your agent and installs into the correct directory.

Uninstall:

# Remove symlink
rm ~/.claude/skills/my-plugin

Version Management

Global version (applies to all 169 skills):

# 1. Update version in marketplace.json metadata
jq '.metadata.version = "4.0.0"' .claude-plugin/marketplace.json > tmp.json
mv tmp.json .claude-plugin/marketplace.json

# 2. Run sync to propagate to all plugins
./scripts/sync-plugins.sh

# 3. Verify
jq -r '.version' plugins/*/.claude-plugin/plugin.json | sort -u
# Should show: 4.0.0 (one version only)

# 4. Commit
git add .
git commit -m "Bump version to 4.0.0"

Package version checking:

# Verify package versions in skill are current
./scripts/check-versions.sh plugins/my-plugin/

# Check specific package
npm view <package-name> version

Git Workflow Standards

Branch naming:

# New skill
git checkout -b add-my-plugin-skill

# Enhancement
git checkout -b enhance-cloudflare-d1

# Fix
git checkout -b fix-tailwind-v4-description

Commit messages:

# Add skill
git commit -m "Add my-plugin skill for [use case]

- Provides [feature]
- Errors prevented: X
- Package versions: <key-package>@X.Y.Z

Production tested: [evidence]"

# Update skill
git commit -m "Optimize cloudflare-d1 description length

- Reduced from 187 to 95 characters
- Maintains trigger phrases
- Improves system prompt budget"

# Sync marketplace
git commit -m "Sync marketplace metadata

- Updated global version to 3.0.0
- Regenerated keywords for 5 skills
- Added categories for 3 new skills"

PR creation (ALWAYS use secondsky repo):

# Create PR to secondsky/claude-skills
gh pr create --repo secondsky/claude-skills \
  --title "Add my-plugin skill" \
  --body "Description of changes

Production tested: [evidence]"

Research Protocol

Before building a new skill (see research-protocol.md):

1. Check existing skills - Is this already covered?
2. Find official docs - Use Context7 MCP to resolve library docs
3. Verify package versions - Check npm for latest stable versions
4. Build working example - Start from scratch, document errors
5. Document research findings - Document sources, versions, issues

---

Production Quality Standards

Production Testing Requirements

Every skill MUST be production-tested before merging:

• Built working example project from scratch using skill templates
• Documented all errors encountered (these become "Known Issues")
• Verified package versions are current (within 3 months)
• Tested skill discovery (Claude suggests skill when relevant)
• Verified templates work without modification
• Production deployment successful (if applicable)

Evidence required:

• Link to working example project
• Screenshot of Claude discovering skill
• Package version verification
• Known issues documented with GitHub issue links

Compliance Standards

Verify against official standards:

1. Anthropic Agent Skills Spec: https://github.com/anthropics/skills/blob/main/agent_skills_spec.md
2. Our Standards Doc: claude-code-skill-standards.md
3. Comparison: STANDARDS_COMPARISON.md

Key requirements:

• YAML frontmatter: name and description (required)
• Third-person descriptions ("This skill should be used when...")
• Imperative/infinitive form in instructions
• Progressive disclosure (SKILL.md < 500 lines)
• Resources organized (scripts/, references/, assets/)

Common Pitfalls

See COMMON_MISTAKES.md for comprehensive list.

Quick list:

• ❌ Missing YAML frontmatter (skill invisible)
• ❌ Verbose descriptions (>150 chars causes budget issues)
• ❌ Second-person instructions ("You should...")
• ❌ Vague descriptions (no "Use when" scenarios)
• ❌ Outdated package versions
• ❌ Untested templates
• ❌ No production validation

Package Version Verification

Quarterly maintenance (every 3 months):

# Check all package versions in a skill
./scripts/check-versions.sh plugins/my-plugin/

# Update to latest stable
npm view <package-name> version

# Update skill documentation
# Update "Last Verified" date in metadata

Breaking changes:

• Review package CHANGELOG for breaking changes
• Update skill templates
• Test thoroughly
• Document migration if needed

---

Integration with Official Plugin-Dev

Combined Workflow Example

Recommended workflow for creating a new plugin with MCP integration:

# 1. PREREQUISITES
/plugin install plugin-dev@claude-code-marketplace

# 2. STRUCTURE (Use Official)
/plugin-dev:create-plugin
# Follow 8-phase guided workflow
# Plugin-dev handles: hooks, MCP, agents, commands, structure

# 3. REPOSITORY-SPECIFIC (This Doc)
# a. Install locally
/plugin install my-plugin@claude-skills

# b. Test discovery
# Ask Claude Code to use the skill

# c. Optimize description (check length)
jq '.description | length' plugins/my-plugin/.claude-plugin/plugin.json
# Should be under 150 chars

# d. Sync marketplace
./scripts/sync-plugins.sh

# e. Verify compliance
# Check ONE_PAGE_CHECKLIST.md

# 4. COMMIT (Repository-Specific)
git add plugins/my-plugin .claude-plugin/marketplace.json
git commit -m "Add my-plugin with MCP integration"
gh pr create --repo secondsky/claude-skills

Task → Resource Mapping

Task	Resource
Create plugin structure	Official: /plugin-dev:create-plugin
Add PreToolUse hook	Official: hook-development skill
Configure MCP server	Official: mcp-integration skill
Create autonomous agent	Official: agent-creator agent
Create slash command	Official: command-development skill
Write skill with triggers	Official: skill-development skill
Validate agent structure	Official: plugin-validator agent
Review skill quality	Repository: ONE_PAGE_CHECKLIST.md
Manage marketplace	Repository: MARKETPLACE_MANAGEMENT.md
Optimize description	Repository: This doc, Section 3
Batch review workflows	Repository: This doc, Section 4
Install locally	Repository: /plugin install <name>@claude-skills (or npx skills add)
Sync versions	Repository: ./scripts/sync-plugins.sh
Check compliance	Repository: ONE_PAGE_CHECKLIST.md
Research protocol	Repository: research-protocol.md

Responsibility Matrix

Responsibility	Official Plugin-Dev	Repository Docs
Plugin fundamentals	✅ PRIMARY	Reference only
Hook development	✅ PRIMARY	Reference only
MCP integration	✅ PRIMARY	Reference only
Agent creation	✅ PRIMARY	Reference only
Command creation	✅ PRIMARY	Reference only
Skill writing	✅ PRIMARY	Reference only
Marketplace management	❌	✅ PRIMARY
System prompt budget	❌	✅ PRIMARY
Batch operations	❌	✅ PRIMARY
Repository workflows	❌	✅ PRIMARY
Description optimization	❌	✅ PRIMARY

---

Summary

Quick Reference

Prerequisites:

1. Install plugin-dev: /plugin install plugin-dev@claude-code-marketplace
2. Use plugin-dev for ALL plugin fundamentals
3. Use this doc ONLY for repository-specific gaps

Repository-Specific Essentials:

1. Marketplace: ./scripts/sync-plugins.sh (before every PR)
2. Descriptions: Keep under 100 chars (150 max) to avoid silent omission
3. Quality: Manual review required (30min-2hrs per skill)
4. Installation: /plugin install <name>@claude-skills (or npx skills add) for local testing

Critical Constraints:

• System prompt budget: 15,000 chars TOTAL for all skill descriptions
• SKILL.md length: Under 500 lines (use progressive disclosure)
• Version sync: Global version applies to all 169 skills
• Git: ALWAYS push to secondsky/claude-skills (never jezweb)

Getting Help

• Plugin fundamentals: Use official plugin-dev skills/agents
• Marketplace issues: See MARKETPLACE_MANAGEMENT.md
• Quality standards: Check ONE_PAGE_CHECKLIST.md
• Common mistakes: Review COMMON_MISTAKES.md
• Research: Follow research-protocol.md

---

Maintainers: Claude Skills Maintainers | maintainers@example.com Repository: https://github.com/secondsky/claude-skills Version: 3.0.0 | Last Updated: 2025-12-28