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

Background & Rationale
Prerequisites (CRITICAL)
Marketplace Management
System Prompt Budget Optimization
Quality Assurance at Scale
Repository-Specific Workflows
Production Quality Standards
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):

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

NOT needed (covered by official plugin-dev):

❌ Hook development basics
❌ MCP integration basics
❌ Agent creation basics
❌ Command development basics
❌ Plugin manifest basics
❌ Skill structure basics
❌ 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:

✅ Marketplace Management - Managing 169 skills across 58 plugins (unique to this repo)
✅ System Prompt Budget - Critical 15k character limit and optimization (production issue)
✅ Batch Operations - Quality workflows for large skill collections (169 skills)
✅ 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:

Reads global version from marketplace.json metadata
Syncs version to all 169 plugin.json files
Auto-detects category based on skill name patterns
Scans agents/ and commands/ directories → adds to plugin.json
Generates keywords from name + category + description
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`	`^(ai-\|openai-\|claude-\|google-gemini-)`	ai-sdk-core, openai-agents
`frontend`	`^(nextjs\|nuxt-\|react-\|tanstack-)`	nuxt-v4, tailwind-v4-shadcn
`auth`	`^(better-auth)`	better-auth
`database`	`^(database-\|drizzle-\|neon-\|vercel-)`	drizzle-orm-d1, vercel-kv
`api`	`^(api-\|graphql-\|rest-api-)`	api-design-principles
`testing`	`^(jest-\|mutation-\|playwright-\|vitest-)`	vitest-testing
`mobile`	`^(app-store-\|mobile-\|react-native-\|swift-)`	swift-best-practices
`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:

Name keywords: Split skill name by - (e.g., cloudflare-d1 → ["cloudflare-d1", "cloudflare"])
Category keywords: Domain-specific terms (e.g., cloudflare → ["workers", "edge", "serverless"])
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:

Context-aware decisions - Extracting content requires understanding what's essential
Quality over speed - 30min-2hrs per skill ensures quality
Judgment required - Only humans can determine "Quick Start" vs "Advanced Topics"
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):

Read entire SKILL.md - Identify sections >100 lines
Determine what stays - Quick Start, Top 3-5 errors must stay in SKILL.md
Extract to references/ - Move advanced/detailed content
Update SKILL.md - Replace with summary + pointer: "Load references/advanced.md when..."
Add "When to Load References" - Critical section for Claude to know what to load when
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
./scripts/install-skill.sh my-plugin

# 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:

./scripts/install-skill.sh my-plugin

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

Install all 169 skills:

./scripts/install-all.sh

# Takes ~2-3 minutes
# Creates symlinks to ~/.claude/skills/

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):

Check existing skills - Is this already covered?
Find official docs - Use Context7 MCP to resolve library docs
Verify package versions - Check npm for latest stable versions
Build working example - Start from scratch, document errors
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:

Anthropic Agent Skills Spec: https://github.com/anthropics/skills/blob/main/agent_skills_spec.md
Our Standards Doc: claude-code-skill-standards.md
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
./scripts/install-skill.sh my-plugin

# 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: `./scripts/install-skill.sh`
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:

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

Repository-Specific Essentials:

Marketplace: ./scripts/sync-plugins.sh (before every PR)
Descriptions: Keep under 100 chars (150 max) to avoid silent omission
Quality: Manual review required (30min-2hrs per skill)
Installation: ./scripts/install-skill.sh 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

FilesExpand file tree

PLUGIN_DEV_BEST_PRACTICES.md

Latest commit

History