Contributing Skills

Contributing Skills

Resources

**Official Anthropic documentation (always check these first):**

• Claude Code Plugins
• Agent Skills
• Best Practices
• Skill Authoring Best Practices — progressive disclosure, degrees of freedom, workflow checklists
• The Complete Guide to Building Skills (text) — evaluation-driven development, iterative testing

**Reference skills** - learn by example at different complexity levels:

Complexity	Skill	What It Demonstrates
Basic	ask-questions-if-underspecified	Minimal frontmatter, simple guidance
Intermediate	constant-time-analysis	Python package, references/, language-specific docs
Advanced	culture-index	Scripts, workflows/, templates/, PDF extraction, multiple entry points

**When in doubt, copy one of these and adapt it.**

**Deep dives on skill authoring:**

• Claude Skills Deep Dive - Comprehensive analysis of skill architecture

**Example plugins worth studying:**

• superpowers - Advanced workflow patterns, TDD enforcement, multi-skill orchestration
• compound-engineering-plugin - Production plugin structure
• getsentry/skills — Production Sentry skills; security-review is a standout routing + progressive disclosure example

**For Claude:** Use the `claude-code-guide` subagent for plugin/skill questions - it has access to official documentation.

Technical Reference

Codex Compatibility

This repository now supports both Claude plugin discovery and Codex-native skill discovery.

Rules:

• If a plugin adds skills//SKILL.md, it must also remain reachable through .codex/skills/.
• If a plugin is command/hook/agent-only and has no skills/ directory, add an explicit Codex wrapper skill under .codex/skills//SKILL.md or document why no Codex equivalent is intended.
• Before submitting, run:

python3 .github/scripts/validate_codex_skills.py

• If this check fails in CI, the remediation path should be local and mechanical: run the installer or update the .codex/skills/ mapping, then commit the resulting changes.

Plugin Structure

plugins/
  /
    .claude-plugin/
      plugin.json         # Plugin metadata (name, version, description, author)
    commands/