Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
236 lines (170 loc) · 6.62 KB

CONTRIBUTING.md

File metadata and controls

236 lines (170 loc) · 6.62 KB

Contributing to Claude Code Skills

Thank you for your interest in contributing! This repository is the largest open-source Claude Code skills & agent plugins library (6,800+ stars, 205 production-ready skills).

Before you start: Read CONVENTIONS.md — it contains the mandatory technical rules that every contribution must follow. PRs that violate conventions will be closed.

Target Branch: dev

All PRs must target the dev branch. PRs targeting main will be closed automatically.

git clone https://github.com/YOUR_USERNAME/claude-skills.git
cd claude-skills
git remote add upstream https://github.com/alirezarezvani/claude-skills.git
git fetch upstream dev
git checkout -b feature/my-skill upstream/dev

What We Accept

New Skills

Add domain expertise that doesn't already exist in the repo:

  • Engineering tools and workflows
  • Marketing, sales, customer success patterns
  • Product management frameworks
  • Regulatory and compliance (ISO, SOC, GDPR, FDA)
  • Business functions (finance, HR, operations)

Before building: Check existing skills to avoid overlap. Open an issue to discuss if unsure.

Improvements to Existing Skills

  • Better workflows and actionable patterns
  • Additional Python automation scripts
  • New reference material
  • More code examples and cross-references
  • Bug fixes in scripts or documentation

Bug Fixes

  • Python scripts that fail --help
  • Broken cross-references between skills
  • Incorrect information in reference docs

What We Do NOT Accept

Type Reason
Links to external repos/tools in README No 3rd party promotion
Skills requiring paid API keys Must work without external services
Scripts with pip dependencies stdlib-only Python
PRs that change the skill count (205) Curated number
PRs modifying .codex/, .gemini/, marketplace.json Auto-generated files
Bloated diffs with fork merge history Rebase on dev first
Generic advice without actionable frameworks Must be executable by an AI agent

Skill Creation Guide

1. Create the directory

# Example: new engineering skill
mkdir -p engineering/my-new-skill/scripts
mkdir -p engineering/my-new-skill/references

2. Write SKILL.md

Frontmatter — only name and description:

---
name: "my-new-skill"
description: "Use when the user asks to [specific trigger]. Covers [key capabilities]."
---

Important: Do NOT add license, metadata, triggers, version, author, or any other fields. See CONVENTIONS.md for the full specification.

Content must be:

  • Under 500 lines (move detailed content to references/)
  • Opinionated (recommend specific approaches)
  • Actionable (agent can execute, not just advise)
  • Include anti-patterns and cross-references sections

3. Write Python scripts (optional but valuable)

#!/usr/bin/env python3
"""Tool Name — brief description."""

import argparse
import json
import sys

def main():
    parser = argparse.ArgumentParser(description="Tool description")
    parser.add_argument("input", help="Input file or value")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--verbose", action="store_true", help="Verbose output")
    args = parser.parse_args()

    # Your logic here
    result = {"status": "ok"}

    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print(f"Result: {result['status']}")

if __name__ == "__main__":
    main()

Script rules: stdlib-only, argparse, --help, --json, proper exit codes (0/1/2). See CONVENTIONS.md for full requirements.

4. Add reference docs (optional)

Place detailed material in references/:

my-new-skill/references/
├── patterns.md          # Detailed patterns and examples
├── best-practices.md    # Best practices guide
└── decision-matrix.md   # Comparison tables

Reference them from SKILL.md:

> See [references/patterns.md](references/patterns.md) for detailed patterns.

5. Validate before submitting

# Structure validation
python3 engineering/skill-tester/scripts/skill_validator.py <your-skill-path>

# Script testing
python3 engineering/skill-tester/scripts/script_tester.py <your-skill-path> --verbose

# Security audit
python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py <your-skill-path> --strict

PR Checklist

Before submitting your PR, verify:

  • Targets dev branch (not main)
  • SKILL.md frontmatter has only name + description
  • SKILL.md under 500 lines (detailed content in references/)
  • All scripts pass python3 script.py --help
  • Scripts use stdlib only (no pip dependencies)
  • Scripts support --json output
  • Anti-patterns section included in SKILL.md
  • Cross-references to related skills included
  • No modifications to .codex/, .gemini/, marketplace.json, or index files
  • No 3rd party links added to README
  • Clean diff — rebased on dev, no merge commit history
  • Security audit passes with zero CRITICAL/HIGH findings

Commit Messages

Conventional Commits format:

feat(engineering): add browser-automation skill
fix(self-improving-agent): use absolute path for hooks
improve(tdd-guide): add per-language examples
docs: update CONTRIBUTING.md

PR Description Template

## Summary
- What: [What does this add/change/fix?]
- Why: [Why is this valuable?]

## Checklist
- [x] Targets dev branch
- [x] SKILL.md frontmatter: name + description only
- [x] Under 500 lines
- [x] Scripts pass --help
- [x] Security audit: 0 critical/high findings

After Your PR is Merged

Maintainers will handle:

  1. Running sync scripts (Codex, Gemini, integrations)
  2. Generating docs pages
  3. Updating mkdocs.yml navigation
  4. Updating domain plugin.json counts
  5. Updating marketplace.json
  6. Merging dev → main for deployment

You do NOT need to do any of these steps in your PR.

Recognition

Contributors are credited via:

  • Co-Authored-By: in commit messages
  • PR merge messages and changelogs
  • Attribution in SKILL.md when skills are improved from community submissions

Questions?

Full technical conventions: CONVENTIONS.md
⚡