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`
|
||||
|
||||
**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
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Getting Started
|
||||
## Target Branch: `dev`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- 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
|
||||
**All PRs must target the `dev` branch.** PRs targeting `main` will be closed automatically.
|
||||
|
||||
```bash
|
||||
# Fork the repository on GitHub first
|
||||
git clone https://github.com/YOUR_USERNAME/claude-skills.git
|
||||
cd claude-skills
|
||||
|
||||
# Add upstream remote
|
||||
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
|
||||
# Create feature branch
|
||||
git checkout -b feature/my-new-skill
|
||||
|
||||
# Or for improvements
|
||||
git checkout -b improvement/enhance-content-creator
|
||||
# Example: new engineering skill
|
||||
mkdir -p engineering/my-new-skill/scripts
|
||||
mkdir -p engineering/my-new-skill/references
|
||||
```
|
||||
|
||||
---
|
||||
### 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
|
||||
---
|
||||
name: your-skill-name
|
||||
description: What it does and when to use it. Include specific triggers and keywords.
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Your Name
|
||||
category: domain-category
|
||||
updated: 2025-10-28
|
||||
name: "my-new-skill"
|
||||
description: "Use when the user asks to [specific trigger]. Covers [key capabilities]."
|
||||
---
|
||||
```
|
||||
|
||||
**Markdown Content (required):**
|
||||
- Clear heading and overview
|
||||
- Keywords section for discovery
|
||||
- Quick start guide
|
||||
- Core workflows
|
||||
- Script documentation (if applicable)
|
||||
- Reference guide (if applicable)
|
||||
- Best practices
|
||||
- Examples
|
||||
> **Important:** Do NOT add `license`, `metadata`, `triggers`, `version`, `author`, or any other fields. See [CONVENTIONS.md](CONVENTIONS.md) for the full specification.
|
||||
|
||||
**Target Length:** 100-200 lines for SKILL.md
|
||||
- Keep core instructions lean
|
||||
- Move detailed content to references/
|
||||
- Follow progressive disclosure principle
|
||||
**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
|
||||
|
||||
### 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
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Tool Name - Brief description
|
||||
"""Tool Name — brief description."""
|
||||
|
||||
Usage:
|
||||
python tool.py input.txt [--output json]
|
||||
"""
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
|
||||
def main():
|
||||
# Implementation
|
||||
pass
|
||||
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()
|
||||
```
|
||||
|
||||
### 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
|
||||
- Real-world examples
|
||||
- Specific metrics and benchmarks
|
||||
- No generic advice
|
||||
- Professional tone
|
||||
- Proper formatting
|
||||
### 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
|
||||
```
|
||||
|
||||
## 🔄 Contribution Process
|
||||
Reference them from SKILL.md:
|
||||
```markdown
|
||||
> See [references/patterns.md](references/patterns.md) for detailed patterns.
|
||||
```
|
||||
|
||||
### Step 1: Discuss First (Recommended)
|
||||
|
||||
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
|
||||
### 5. Validate before submitting
|
||||
|
||||
```bash
|
||||
# Commit your changes
|
||||
git add .
|
||||
git commit -m "feat(domain): add new-skill with [capabilities]"
|
||||
# Structure validation
|
||||
python3 engineering/skill-tester/scripts/skill_validator.py <your-skill-path>
|
||||
|
||||
# Push to your fork
|
||||
git push origin feature/my-new-skill
|
||||
# Script testing
|
||||
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:**
|
||||
- What: What does this add/change/fix?
|
||||
- Why: Why is this valuable?
|
||||
- Testing: How was it tested?
|
||||
- Documentation: What docs were updated?
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## ✅ Quality Standards
|
||||
## Commit Messages
|
||||
|
||||
### Skill Quality Checklist
|
||||
[Conventional Commits](https://www.conventionalcommits.org/) format:
|
||||
|
||||
All new skills must meet these standards:
|
||||
|
||||
**Documentation:**
|
||||
- [ ] Clear SKILL.md with all required sections
|
||||
- [ ] Enhanced description with triggers and keywords
|
||||
- [ ] 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
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
### Markdown Documentation
|
||||
---
|
||||
|
||||
- Use headers consistently (H1 for title, H2 for sections)
|
||||
- Include code blocks with language specification
|
||||
- Use tables for comparisons
|
||||
- Add emojis sparingly for visual hierarchy
|
||||
- Keep paragraphs concise
|
||||
## PR Description Template
|
||||
|
||||
### Commit Messages
|
||||
```markdown
|
||||
## Summary
|
||||
- What: [What does this add/change/fix?]
|
||||
- Why: [Why is this valuable?]
|
||||
|
||||
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
- `feat(domain): add new capability`
|
||||
- `fix(skill): correct bug in script`
|
||||
- `docs(readme): update installation guide`
|
||||
- `refactor(skill): optimize SKILL.md length`
|
||||
- `test(tool): add test coverage`
|
||||
## 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏆 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:
|
||||
- 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
|
||||
You do NOT need to do any of these steps in your PR.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Domain-Specific Guidelines
|
||||
## Recognition
|
||||
|
||||
### Marketing Skills
|
||||
|
||||
- Include real benchmarks (CAC, conversion rates, etc.)
|
||||
- Platform-specific guidance (LinkedIn, Google, etc.)
|
||||
- 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
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## 🚫 What NOT to Contribute
|
||||
## Questions?
|
||||
|
||||
**We will not accept:**
|
||||
- Generic advice without actionable frameworks
|
||||
- Placeholder scripts (must be production-ready)
|
||||
- Skills without clear use cases
|
||||
- Duplicate capabilities of existing skills
|
||||
- Proprietary or confidential information
|
||||
- Content that violates licenses
|
||||
- Skills promoting unethical practices
|
||||
- **General:** Open a [discussion](https://github.com/alirezarezvani/claude-skills/discussions)
|
||||
- **Bugs:** Use the [issue tracker](https://github.com/alirezarezvani/claude-skills/issues)
|
||||
- **Contact:** [alirezarezvani.com](https://alirezarezvani.com)
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Code of Conduct
|
||||
|
||||
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!** 🚀
|
||||
**Full technical conventions:** [CONVENTIONS.md](CONVENTIONS.md)
|
||||
|
||||
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