docs: add CONVENTIONS.md and rewrite CONTRIBUTING.md
CONVENTIONS.md: Mandatory technical rules for all contributors (human and AI). Covers SKILL.md format, plugin.json schema, Python script standards, sub-skill rules, cross-platform sync, and what NOT to contribute. CONTRIBUTING.md: Rewritten to reference CONVENTIONS.md. Fixed outdated guidance that contradicted actual repo conventions (was recommending license/metadata in frontmatter, wrong line limits, missing anti-patterns/cross-refs requirements). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Reza Rezvani
509
CONTRIBUTING.md
509
CONTRIBUTING.md
@@ -1,421 +1,236 @@
|
|||||||
# Contributing to Claude Skills Library
|
# Contributing to Claude Code Skills
|
||||||
|
|
||||||
Thank you for your interest in contributing to the Claude Skills Library! This repository aims to democratize professional expertise through reusable, production-ready skill packages for Claude AI.
|
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).
|
||||||
|
|
||||||
## ⚠️ Important: Always Target `dev`
|
**Before you start:** Read [CONVENTIONS.md](CONVENTIONS.md) — it contains the mandatory technical rules that every contribution must follow. PRs that violate conventions will be closed.
|
||||||
|
|
||||||
**All PRs must target the `dev` branch.** PRs targeting `main` will be automatically closed.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Fork the repo, then:
|
|
||||||
git checkout -b feat/my-new-skill origin/dev
|
|
||||||
# ... make your changes ...
|
|
||||||
# Open PR → base: dev (NOT main)
|
|
||||||
```
|
|
||||||
|
|
||||||
The `main` branch is reserved for releases and is maintained by the project owner.
|
|
||||||
|
|
||||||
## 🎯 Ways to Contribute
|
|
||||||
|
|
||||||
### 1. Create New Skills
|
|
||||||
|
|
||||||
Add domain expertise in your field:
|
|
||||||
- Marketing, sales, customer success
|
|
||||||
- Engineering specializations
|
|
||||||
- Business functions (finance, HR, operations)
|
|
||||||
- Industry-specific skills (FinTech, EdTech, etc.)
|
|
||||||
|
|
||||||
### 2. Enhance Existing Skills
|
|
||||||
|
|
||||||
Improve current skills with:
|
|
||||||
- Better frameworks and templates
|
|
||||||
- Additional Python automation tools
|
|
||||||
- Updated best practices
|
|
||||||
- More reference materials
|
|
||||||
- Real-world examples and case studies
|
|
||||||
|
|
||||||
### 3. Improve Documentation
|
|
||||||
|
|
||||||
Help others use skills effectively:
|
|
||||||
- Clearer how-to guides
|
|
||||||
- Additional usage examples
|
|
||||||
- Better README files
|
|
||||||
- Translations to other languages
|
|
||||||
|
|
||||||
### 4. Fix Bugs
|
|
||||||
|
|
||||||
Report or fix issues in:
|
|
||||||
- Python scripts
|
|
||||||
- Documentation errors
|
|
||||||
- Broken links
|
|
||||||
- Outdated information
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🚀 Getting Started
|
## Target Branch: `dev`
|
||||||
|
|
||||||
### Prerequisites
|
**All PRs must target the `dev` branch.** PRs targeting `main` will be closed automatically.
|
||||||
|
|
||||||
- Python 3.7+ (for running/testing scripts)
|
|
||||||
- Git and GitHub account
|
|
||||||
- Claude AI or Claude Code account (for testing skills)
|
|
||||||
- Familiarity with the skill domain you're contributing to
|
|
||||||
|
|
||||||
### Fork and Clone
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Fork the repository on GitHub first
|
|
||||||
git clone https://github.com/YOUR_USERNAME/claude-skills.git
|
git clone https://github.com/YOUR_USERNAME/claude-skills.git
|
||||||
cd claude-skills
|
cd claude-skills
|
||||||
|
|
||||||
# Add upstream remote
|
|
||||||
git remote add upstream https://github.com/alirezarezvani/claude-skills.git
|
git remote add upstream https://github.com/alirezarezvani/claude-skills.git
|
||||||
|
git fetch upstream dev
|
||||||
|
git checkout -b feature/my-skill upstream/dev
|
||||||
```
|
```
|
||||||
|
|
||||||
### Create a Branch
|
---
|
||||||
|
|
||||||
|
## 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
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Create feature branch
|
# Example: new engineering skill
|
||||||
git checkout -b feature/my-new-skill
|
mkdir -p engineering/my-new-skill/scripts
|
||||||
|
mkdir -p engineering/my-new-skill/references
|
||||||
# Or for improvements
|
|
||||||
git checkout -b improvement/enhance-content-creator
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### 2. Write SKILL.md
|
||||||
|
|
||||||
## 📝 Skill Creation Guidelines
|
**Frontmatter — only `name` and `description`:**
|
||||||
|
|
||||||
### Following Anthropic's Official Spec
|
|
||||||
|
|
||||||
All skills must follow [Anthropic's Agent Skills Specification](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/overview).
|
|
||||||
|
|
||||||
### Required Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
your-skill-name/
|
|
||||||
├── SKILL.md (required)
|
|
||||||
│ ├── YAML frontmatter (name, description, license, metadata)
|
|
||||||
│ └── Markdown content (instructions, examples, workflows)
|
|
||||||
├── scripts/ (optional but recommended)
|
|
||||||
│ ├── tool1.py
|
|
||||||
│ ├── tool2.py
|
|
||||||
│ └── tool3.py
|
|
||||||
├── references/ (optional but recommended)
|
|
||||||
│ ├── framework.md
|
|
||||||
│ ├── best-practices.md
|
|
||||||
│ └── examples.md
|
|
||||||
└── assets/ (optional)
|
|
||||||
└── templates/
|
|
||||||
```
|
|
||||||
|
|
||||||
### SKILL.md Requirements
|
|
||||||
|
|
||||||
**YAML Frontmatter (required):**
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
name: your-skill-name
|
name: "my-new-skill"
|
||||||
description: What it does and when to use it. Include specific triggers and keywords.
|
description: "Use when the user asks to [specific trigger]. Covers [key capabilities]."
|
||||||
license: MIT
|
|
||||||
metadata:
|
|
||||||
version: 1.0.0
|
|
||||||
author: Your Name
|
|
||||||
category: domain-category
|
|
||||||
updated: 2025-10-28
|
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
**Markdown Content (required):**
|
> **Important:** Do NOT add `license`, `metadata`, `triggers`, `version`, `author`, or any other fields. See [CONVENTIONS.md](CONVENTIONS.md) for the full specification.
|
||||||
- Clear heading and overview
|
|
||||||
- Keywords section for discovery
|
|
||||||
- Quick start guide
|
|
||||||
- Core workflows
|
|
||||||
- Script documentation (if applicable)
|
|
||||||
- Reference guide (if applicable)
|
|
||||||
- Best practices
|
|
||||||
- Examples
|
|
||||||
|
|
||||||
**Target Length:** 100-200 lines for SKILL.md
|
**Content must be:**
|
||||||
- Keep core instructions lean
|
- Under 500 lines (move detailed content to `references/`)
|
||||||
- Move detailed content to references/
|
- Opinionated (recommend specific approaches)
|
||||||
- Follow progressive disclosure principle
|
- Actionable (agent can execute, not just advise)
|
||||||
|
- Include anti-patterns and cross-references sections
|
||||||
|
|
||||||
### Python Script Standards
|
### 3. Write Python scripts (optional but valuable)
|
||||||
|
|
||||||
**Quality Requirements:**
|
|
||||||
- Production-ready code (not placeholders)
|
|
||||||
- Standard library preferred (minimal dependencies)
|
|
||||||
- CLI-first design with --help support
|
|
||||||
- JSON output option for automation
|
|
||||||
- Clear docstrings and comments
|
|
||||||
- Error handling and validation
|
|
||||||
|
|
||||||
**Example:**
|
|
||||||
```python
|
```python
|
||||||
#!/usr/bin/env python3
|
#!/usr/bin/env python3
|
||||||
"""
|
"""Tool Name — brief description."""
|
||||||
Tool Name - Brief description
|
|
||||||
|
|
||||||
Usage:
|
import argparse
|
||||||
python tool.py input.txt [--output json]
|
import json
|
||||||
"""
|
import sys
|
||||||
|
|
||||||
def main():
|
def main():
|
||||||
# Implementation
|
parser = argparse.ArgumentParser(description="Tool description")
|
||||||
pass
|
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__":
|
if __name__ == "__main__":
|
||||||
main()
|
main()
|
||||||
```
|
```
|
||||||
|
|
||||||
### Documentation Standards
|
**Script rules:** stdlib-only, argparse, `--help`, `--json`, proper exit codes (0/1/2). See [CONVENTIONS.md](CONVENTIONS.md) for full requirements.
|
||||||
|
|
||||||
- Clear, actionable guidance
|
### 4. Add reference docs (optional)
|
||||||
- Real-world examples
|
|
||||||
- Specific metrics and benchmarks
|
|
||||||
- No generic advice
|
|
||||||
- Professional tone
|
|
||||||
- Proper formatting
|
|
||||||
|
|
||||||
---
|
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
|
||||||
|
```
|
||||||
|
|
||||||
## 🔄 Contribution Process
|
Reference them from SKILL.md:
|
||||||
|
```markdown
|
||||||
|
> See [references/patterns.md](references/patterns.md) for detailed patterns.
|
||||||
|
```
|
||||||
|
|
||||||
### Step 1: Discuss First (Recommended)
|
### 5. Validate before submitting
|
||||||
|
|
||||||
For major contributions:
|
|
||||||
1. Open an issue describing your idea
|
|
||||||
2. Discuss approach with maintainers
|
|
||||||
3. Get feedback before investing time
|
|
||||||
4. Avoid duplicate efforts
|
|
||||||
|
|
||||||
### Step 2: Develop Your Contribution
|
|
||||||
|
|
||||||
Follow the guidelines above for:
|
|
||||||
- New skills
|
|
||||||
- Python tools
|
|
||||||
- Documentation
|
|
||||||
- Bug fixes
|
|
||||||
|
|
||||||
### Step 3: Test Thoroughly
|
|
||||||
|
|
||||||
**For New Skills:**
|
|
||||||
- [ ] YAML frontmatter valid (no syntax errors)
|
|
||||||
- [ ] Description triggers Claude correctly
|
|
||||||
- [ ] All Python scripts work with --help
|
|
||||||
- [ ] All reference links work
|
|
||||||
- [ ] Skill activates when expected
|
|
||||||
- [ ] Tested with Claude AI or Claude Code
|
|
||||||
|
|
||||||
**For Python Tools:**
|
|
||||||
- [ ] Runs without errors
|
|
||||||
- [ ] Handles edge cases
|
|
||||||
- [ ] Provides helpful error messages
|
|
||||||
- [ ] JSON output works (if applicable)
|
|
||||||
- [ ] Dependencies documented
|
|
||||||
|
|
||||||
### Step 4: Submit Pull Request
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Commit your changes
|
# Structure validation
|
||||||
git add .
|
python3 engineering/skill-tester/scripts/skill_validator.py <your-skill-path>
|
||||||
git commit -m "feat(domain): add new-skill with [capabilities]"
|
|
||||||
|
|
||||||
# Push to your fork
|
# Script testing
|
||||||
git push origin feature/my-new-skill
|
python3 engineering/skill-tester/scripts/script_tester.py <your-skill-path> --verbose
|
||||||
|
|
||||||
# Create pull request on GitHub
|
# Security audit
|
||||||
|
python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py <your-skill-path> --strict
|
||||||
```
|
```
|
||||||
|
|
||||||
**PR Title Format:**
|
---
|
||||||
- `feat(domain): add new skill for [purpose]`
|
|
||||||
- `fix(skill-name): correct issue with [component]`
|
|
||||||
- `docs(domain): improve documentation for [topic]`
|
|
||||||
- `refactor(skill-name): optimize [component]`
|
|
||||||
|
|
||||||
**PR Description Must Include:**
|
## PR Checklist
|
||||||
- What: What does this add/change/fix?
|
|
||||||
- Why: Why is this valuable?
|
Before submitting your PR, verify:
|
||||||
- Testing: How was it tested?
|
|
||||||
- Documentation: What docs were updated?
|
- [ ] **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
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ✅ Quality Standards
|
## Commit Messages
|
||||||
|
|
||||||
### Skill Quality Checklist
|
[Conventional Commits](https://www.conventionalcommits.org/) format:
|
||||||
|
|
||||||
All new skills must meet these standards:
|
```
|
||||||
|
feat(engineering): add browser-automation skill
|
||||||
**Documentation:**
|
fix(self-improving-agent): use absolute path for hooks
|
||||||
- [ ] Clear SKILL.md with all required sections
|
improve(tdd-guide): add per-language examples
|
||||||
- [ ] Enhanced description with triggers and keywords
|
docs: update CONTRIBUTING.md
|
||||||
- [ ] Keywords section for discovery
|
|
||||||
- [ ] Quick start guide with 2-3 examples
|
|
||||||
- [ ] Professional metadata (license, version, author)
|
|
||||||
- [ ] Domain-specific README updated (if applicable)
|
|
||||||
|
|
||||||
**Python Tools (if included):**
|
|
||||||
- [ ] Production-ready code (not placeholders)
|
|
||||||
- [ ] CLI with --help support
|
|
||||||
- [ ] Proper error handling
|
|
||||||
- [ ] Clear docstrings
|
|
||||||
- [ ] Dependencies minimal and documented
|
|
||||||
|
|
||||||
**References (if included):**
|
|
||||||
- [ ] Actionable frameworks and templates
|
|
||||||
- [ ] Specific guidance (not generic advice)
|
|
||||||
- [ ] Real-world benchmarks and examples
|
|
||||||
- [ ] Properly linked from SKILL.md
|
|
||||||
|
|
||||||
**Testing:**
|
|
||||||
- [ ] Skill activates correctly with Claude
|
|
||||||
- [ ] All scripts execute without errors
|
|
||||||
- [ ] All links work
|
|
||||||
- [ ] No broken references
|
|
||||||
|
|
||||||
**ROI:**
|
|
||||||
- [ ] Demonstrates measurable value
|
|
||||||
- [ ] Time savings quantified
|
|
||||||
- [ ] Quality improvements specified
|
|
||||||
- [ ] Clear use cases documented
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎨 Style Guide
|
|
||||||
|
|
||||||
### Python Code
|
|
||||||
|
|
||||||
**Follow PEP 8:**
|
|
||||||
- 4 spaces for indentation
|
|
||||||
- Max line length: 100 characters
|
|
||||||
- Clear variable names
|
|
||||||
- Docstrings for functions
|
|
||||||
|
|
||||||
**Example:**
|
|
||||||
```python
|
|
||||||
def analyze_content(text: str, keywords: list) -> dict:
|
|
||||||
"""
|
|
||||||
Analyze text content for keyword density and readability.
|
|
||||||
|
|
||||||
Args:
|
|
||||||
text: Content to analyze
|
|
||||||
keywords: List of keywords to check
|
|
||||||
|
|
||||||
Returns:
|
|
||||||
dict: Analysis results with scores and recommendations
|
|
||||||
"""
|
|
||||||
pass
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Markdown Documentation
|
---
|
||||||
|
|
||||||
- Use headers consistently (H1 for title, H2 for sections)
|
## PR Description Template
|
||||||
- Include code blocks with language specification
|
|
||||||
- Use tables for comparisons
|
|
||||||
- Add emojis sparingly for visual hierarchy
|
|
||||||
- Keep paragraphs concise
|
|
||||||
|
|
||||||
### Commit Messages
|
```markdown
|
||||||
|
## Summary
|
||||||
|
- What: [What does this add/change/fix?]
|
||||||
|
- Why: [Why is this valuable?]
|
||||||
|
|
||||||
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
## Checklist
|
||||||
|
- [x] Targets dev branch
|
||||||
- `feat(domain): add new capability`
|
- [x] SKILL.md frontmatter: name + description only
|
||||||
- `fix(skill): correct bug in script`
|
- [x] Under 500 lines
|
||||||
- `docs(readme): update installation guide`
|
- [x] Scripts pass --help
|
||||||
- `refactor(skill): optimize SKILL.md length`
|
- [x] Security audit: 0 critical/high findings
|
||||||
- `test(tool): add test coverage`
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🏆 Recognition
|
## After Your PR is Merged
|
||||||
|
|
||||||
### Contributors
|
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
|
||||||
|
|
||||||
All contributors will be:
|
You do NOT need to do any of these steps in your PR.
|
||||||
- Listed in CHANGELOG.md for their contributions
|
|
||||||
- Mentioned in release notes
|
|
||||||
- Credited in PR merge messages
|
|
||||||
- Acknowledged in the community
|
|
||||||
|
|
||||||
### Significant Contributions
|
|
||||||
|
|
||||||
Major contributions may result in:
|
|
||||||
- Co-author credit in commits
|
|
||||||
- Feature attribution in documentation
|
|
||||||
- Highlighted in README
|
|
||||||
- Social media recognition
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📋 Domain-Specific Guidelines
|
## Recognition
|
||||||
|
|
||||||
### Marketing Skills
|
Contributors are credited via:
|
||||||
|
- `Co-Authored-By:` in commit messages
|
||||||
- Include real benchmarks (CAC, conversion rates, etc.)
|
- PR merge messages and changelogs
|
||||||
- Platform-specific guidance (LinkedIn, Google, etc.)
|
- Attribution in SKILL.md when skills are improved from community submissions
|
||||||
- B2B or B2C focus clearly stated
|
|
||||||
- International market considerations
|
|
||||||
|
|
||||||
### Engineering Skills
|
|
||||||
|
|
||||||
- Include tech stack in metadata
|
|
||||||
- Provide architecture patterns
|
|
||||||
- Add code quality standards
|
|
||||||
- Performance benchmarks
|
|
||||||
|
|
||||||
### Product Skills
|
|
||||||
|
|
||||||
- Include frameworks (RICE, OKR, etc.)
|
|
||||||
- Real-world metrics and KPIs
|
|
||||||
- Template-heavy with examples
|
|
||||||
- Integration points with tools
|
|
||||||
|
|
||||||
### Regulatory/Quality Skills
|
|
||||||
|
|
||||||
- Cite specific standards (ISO, FDA, EU MDR)
|
|
||||||
- Compliance frameworks clear
|
|
||||||
- Industry-specific (HealthTech, MedTech)
|
|
||||||
- Regulatory jurisdiction specified
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🚫 What NOT to Contribute
|
## Questions?
|
||||||
|
|
||||||
**We will not accept:**
|
- **General:** Open a [discussion](https://github.com/alirezarezvani/claude-skills/discussions)
|
||||||
- Generic advice without actionable frameworks
|
- **Bugs:** Use the [issue tracker](https://github.com/alirezarezvani/claude-skills/issues)
|
||||||
- Placeholder scripts (must be production-ready)
|
- **Contact:** [alirezarezvani.com](https://alirezarezvani.com)
|
||||||
- Skills without clear use cases
|
|
||||||
- Duplicate capabilities of existing skills
|
|
||||||
- Proprietary or confidential information
|
|
||||||
- Content that violates licenses
|
|
||||||
- Skills promoting unethical practices
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🤝 Code of Conduct
|
**Full technical conventions:** [CONVENTIONS.md](CONVENTIONS.md)
|
||||||
|
|
||||||
By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
||||||
|
|
||||||
Expected behavior:
|
|
||||||
- Be respectful and inclusive
|
|
||||||
- Provide constructive feedback
|
|
||||||
- Focus on what's best for the community
|
|
||||||
- Show empathy and kindness
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📞 Questions?
|
|
||||||
|
|
||||||
- **General Questions:** Open a [discussion](https://github.com/alirezarezvani/claude-skills/discussions)
|
|
||||||
- **Bug Reports:** Use [bug report template](https://github.com/alirezarezvani/claude-skills/issues/new?template=bug_report.md)
|
|
||||||
- **Feature Ideas:** Use [feature request template](https://github.com/alirezarezvani/claude-skills/issues/new?template=feature_request.md)
|
|
||||||
- **Contact:** [alirezarezvani.com](https://alirezarezvani.com) or [medium.com/@alirezarezvani](https://medium.com/@alirezarezvani)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🙏 Thank You!
|
|
||||||
|
|
||||||
Your contributions help make world-class expertise accessible to everyone through Claude AI. Every skill added, bug fixed, or documentation improved makes a difference.
|
|
||||||
|
|
||||||
**Happy contributing!** 🚀
|
|
||||||
|
|||||||
289
CONVENTIONS.md
Normal file
289
CONVENTIONS.md
Normal file
@@ -0,0 +1,289 @@
|
|||||||
|
# Repository Conventions
|
||||||
|
|
||||||
|
**Mandatory conventions for the claude-code-skills repository.** Every contributor — human or AI coding agent — must follow these rules. PRs that violate them will be closed.
|
||||||
|
|
||||||
|
For contribution workflow and how to submit PRs, see [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Skill Structure
|
||||||
|
|
||||||
|
Every skill is a directory under one of the 9 domain folders:
|
||||||
|
|
||||||
|
```
|
||||||
|
<domain>/<skill-name>/
|
||||||
|
├── SKILL.md # Required — main skill file
|
||||||
|
├── .claude-plugin/
|
||||||
|
│ └── plugin.json # Optional — for standalone installs
|
||||||
|
├── scripts/ # Optional — Python CLI tools
|
||||||
|
│ └── *.py
|
||||||
|
├── references/ # Optional — detailed reference docs
|
||||||
|
│ └── *.md
|
||||||
|
└── assets/ # Optional — templates, examples
|
||||||
|
```
|
||||||
|
|
||||||
|
### Domains
|
||||||
|
|
||||||
|
| Directory | Category | Current Count |
|
||||||
|
|-----------|----------|---------------|
|
||||||
|
| `engineering/` | POWERFUL-tier advanced engineering | 35 |
|
||||||
|
| `engineering-team/` | Core engineering roles | 30 |
|
||||||
|
| `marketing-skill/` | Marketing & growth | 43 |
|
||||||
|
| `c-level-advisor/` | Executive advisory | 28 |
|
||||||
|
| `product-team/` | Product management | 14 |
|
||||||
|
| `ra-qm-team/` | Regulatory & quality | 13 |
|
||||||
|
| `project-management/` | PM tools | 6 |
|
||||||
|
| `business-growth/` | Sales & business dev | 4 |
|
||||||
|
| `finance/` | Financial analysis | 2 |
|
||||||
|
|
||||||
|
Place your skill in the domain that best fits. If unsure, open an issue to discuss.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. SKILL.md Format
|
||||||
|
|
||||||
|
### Frontmatter (YAML)
|
||||||
|
|
||||||
|
**Only two fields are allowed:**
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
name: "skill-name"
|
||||||
|
description: "One-line description of when to use this skill. Be specific about trigger conditions."
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
**Do NOT include:** `license`, `metadata`, `triggers`, `version`, `author`, `category`, `updated`, or any other fields. PRs with extra frontmatter fields will be rejected.
|
||||||
|
|
||||||
|
### Content Requirements
|
||||||
|
|
||||||
|
| Requirement | Rule |
|
||||||
|
|-------------|------|
|
||||||
|
| **Line limit** | Under 500 lines. Move detailed content to `references/` files. |
|
||||||
|
| **Opinionated** | Recommend specific approaches. Don't just list options. |
|
||||||
|
| **Actionable** | The agent must be able to execute, not just advise. |
|
||||||
|
| **Anti-patterns** | Include a section on what NOT to do. |
|
||||||
|
| **Cross-references** | Link to related skills in the repo. |
|
||||||
|
| **Code examples** | Include concrete examples where helpful. |
|
||||||
|
|
||||||
|
### Required Sections
|
||||||
|
|
||||||
|
At minimum, every SKILL.md should include:
|
||||||
|
|
||||||
|
1. **Title** (H1) — skill name
|
||||||
|
2. **Overview** — what it does, when to use it
|
||||||
|
3. **Core content** — workflows, patterns, instructions
|
||||||
|
4. **Anti-Patterns** — common mistakes to avoid
|
||||||
|
5. **Cross-References** — related skills in this repo
|
||||||
|
|
||||||
|
Reference detailed material from `references/` files:
|
||||||
|
```markdown
|
||||||
|
> See [references/detailed-guide.md](references/detailed-guide.md) for full patterns.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. plugin.json Format
|
||||||
|
|
||||||
|
If your skill includes a `.claude-plugin/plugin.json`, use this **exact schema**:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "skill-name",
|
||||||
|
"description": "One-line description matching SKILL.md",
|
||||||
|
"version": "2.1.2",
|
||||||
|
"author": {
|
||||||
|
"name": "Alireza Rezvani",
|
||||||
|
"url": "https://alirezarezvani.com"
|
||||||
|
},
|
||||||
|
"homepage": "https://github.com/alirezarezvani/claude-skills/tree/main/<domain>/<skill>",
|
||||||
|
"repository": "https://github.com/alirezarezvani/claude-skills",
|
||||||
|
"license": "MIT",
|
||||||
|
"skills": "./"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rules:**
|
||||||
|
- `author` **must be an object**, never a string. String format causes install errors.
|
||||||
|
- `version` must match the current repo version (`2.1.2`).
|
||||||
|
- No extra fields (`commands`, `hooks`, `triggers`, `tags`, `category`).
|
||||||
|
- Not every skill needs a plugin.json — skills roll up into their domain's parent plugin automatically.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Python Scripts
|
||||||
|
|
||||||
|
All scripts in `scripts/` must follow these rules:
|
||||||
|
|
||||||
|
| Rule | Requirement |
|
||||||
|
|------|-------------|
|
||||||
|
| **Standard library only** | No pip dependencies. Use `argparse`, `json`, `os`, `re`, `sys`, etc. |
|
||||||
|
| **CLI-first** | Must support `python3 script.py --help` |
|
||||||
|
| **JSON output** | Must support `--json` flag for machine-readable output |
|
||||||
|
| **Exit codes** | `0` = success, `1` = warnings, `2` = critical errors |
|
||||||
|
| **No LLM calls** | Scripts must be deterministic — no API calls to AI services |
|
||||||
|
| **No hardcoded secrets** | Use environment variables for credentials |
|
||||||
|
| **Main guard** | Include `if __name__ == "__main__":` |
|
||||||
|
|
||||||
|
**Example skeleton:**
|
||||||
|
```python
|
||||||
|
#!/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("--json", action="store_true", help="Output as JSON")
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
result = {"status": "ok"}
|
||||||
|
|
||||||
|
if args.json:
|
||||||
|
print(json.dumps(result, indent=2))
|
||||||
|
else:
|
||||||
|
print("Result: ok")
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Sub-Skills
|
||||||
|
|
||||||
|
Some skills contain sub-skills in a nested `skills/` directory:
|
||||||
|
|
||||||
|
```
|
||||||
|
engineering-team/playwright-pro/
|
||||||
|
├── SKILL.md ← Parent skill
|
||||||
|
└── skills/
|
||||||
|
├── generate/SKILL.md ← Sub-skill
|
||||||
|
├── fix/SKILL.md ← Sub-skill
|
||||||
|
└── migrate/SKILL.md ← Sub-skill
|
||||||
|
```
|
||||||
|
|
||||||
|
**Sub-skill rules:**
|
||||||
|
- Sub-skills are documented within their parent's docs page, NOT as standalone pages.
|
||||||
|
- Sub-skills do NOT get their own Codex/Gemini symlinks.
|
||||||
|
- Sub-skills do NOT count toward the official skill total.
|
||||||
|
- Do not create new sub-skill structures unless extending an existing compound skill.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. What NOT to Contribute
|
||||||
|
|
||||||
|
The following will be **immediately closed**:
|
||||||
|
|
||||||
|
| Type | Why |
|
||||||
|
|------|-----|
|
||||||
|
| Links to external repos/tools in README | We don't link 3rd party projects |
|
||||||
|
| Skills that require paid API keys | Must work without external dependencies |
|
||||||
|
| Skills that call LLMs in scripts | Scripts must be deterministic |
|
||||||
|
| PRs that change the official skill count (205) | This number is curated |
|
||||||
|
| PRs targeting `main` instead of `dev` | All PRs must target `dev` |
|
||||||
|
| PRs with bloated diffs (merge history from forks) | Rebase on `dev` HEAD first |
|
||||||
|
| PRs that modify marketplace.json counts | We handle count updates |
|
||||||
|
| PRs that modify codex/gemini index files | These are auto-generated |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Cross-Platform Sync
|
||||||
|
|
||||||
|
Platform copies are handled by automated scripts. **Do not create or modify these manually:**
|
||||||
|
|
||||||
|
| Platform | Directory | Script |
|
||||||
|
|----------|-----------|--------|
|
||||||
|
| Codex CLI | `.codex/skills/` | `python3 scripts/sync-codex-skills.py` |
|
||||||
|
| Gemini CLI | `.gemini/skills/` | `python3 scripts/sync-gemini-skills.py` |
|
||||||
|
| Cursor/Aider/etc. | `integrations/` (gitignored) | `scripts/convert.sh --tool all` |
|
||||||
|
|
||||||
|
After your skill is merged, maintainers run these scripts to sync all platforms.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Docs Site
|
||||||
|
|
||||||
|
Docs pages are auto-generated by `python3 scripts/generate-docs.py`. After your skill is merged, maintainers will:
|
||||||
|
|
||||||
|
1. Run the docs generator
|
||||||
|
2. Add your skill to `mkdocs.yml` nav (alphabetical within domain)
|
||||||
|
3. Deploy via GitHub Pages
|
||||||
|
|
||||||
|
You do NOT need to create docs pages in your PR.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Git Conventions
|
||||||
|
|
||||||
|
### Branch Naming
|
||||||
|
|
||||||
|
```
|
||||||
|
feature/<skill-name> → New skill
|
||||||
|
fix/<description> → Bug fix
|
||||||
|
improve/<skill-name> → Enhancement
|
||||||
|
docs/<description> → Documentation
|
||||||
|
```
|
||||||
|
|
||||||
|
### Commit Messages
|
||||||
|
|
||||||
|
[Conventional Commits](https://www.conventionalcommits.org/) 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
|
||||||
|
chore: sync codex/gemini indexes
|
||||||
|
```
|
||||||
|
|
||||||
|
### PR Requirements
|
||||||
|
|
||||||
|
- **Target branch:** `dev` (never `main`)
|
||||||
|
- **One concern per PR** — don't bundle unrelated changes
|
||||||
|
- **Clean diff** — rebase on `dev` HEAD, no merge commit history
|
||||||
|
- **Description** — explain what, why, and how you tested
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Quality Validation
|
||||||
|
|
||||||
|
Before submitting, verify your skill passes these checks:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Structure validation
|
||||||
|
python3 engineering/skill-tester/scripts/skill_validator.py <your-skill-path> --json
|
||||||
|
|
||||||
|
# Quality scoring
|
||||||
|
python3 engineering/skill-tester/scripts/quality_scorer.py <your-skill-path> --json
|
||||||
|
|
||||||
|
# Script testing (if you have scripts)
|
||||||
|
python3 engineering/skill-tester/scripts/script_tester.py <your-skill-path> --json
|
||||||
|
|
||||||
|
# Security audit
|
||||||
|
python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py <your-skill-path> --strict
|
||||||
|
```
|
||||||
|
|
||||||
|
**Minimum requirements:**
|
||||||
|
- Structure score ≥ 75/100
|
||||||
|
- All scripts pass `--help`
|
||||||
|
- Zero CRITICAL or HIGH security findings
|
||||||
|
- SKILL.md under 500 lines
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| What | Rule |
|
||||||
|
|------|------|
|
||||||
|
| Frontmatter fields | `name` + `description` only |
|
||||||
|
| SKILL.md max lines | 500 |
|
||||||
|
| Python dependencies | stdlib only |
|
||||||
|
| PR target branch | `dev` |
|
||||||
|
| plugin.json author | Object `{"name": "...", "url": "..."}`, never string |
|
||||||
|
| External links in README | Not accepted |
|
||||||
|
| Skill count | 205 (do not change) |
|
||||||
|
| Commit format | Conventional commits |
|
||||||
|
| Script output | Must support `--json` |
|
||||||
Reference in New Issue
Block a user