mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-02-19 04:33:11 +08:00
docs: enhance CONTRIBUTING.md with detailed templates
- Add table of contents - Add detailed skill contribution template - Add agent contribution template with field descriptions - Add hook examples with matcher syntax - Add command template - Add PR title format and checklist
This commit is contained in:
Affaan Mustafa
427
CONTRIBUTING.md
427
CONTRIBUTING.md
@@ -1,11 +1,22 @@
|
||||
# Contributing to Everything Claude Code
|
||||
|
||||
Thanks for wanting to contribute. This repo is meant to be a community resource for Claude Code users.
|
||||
Thanks for wanting to contribute! This repo is a community resource for Claude Code users.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [What We're Looking For](#what-were-looking-for)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Contributing Skills](#contributing-skills)
|
||||
- [Contributing Agents](#contributing-agents)
|
||||
- [Contributing Hooks](#contributing-hooks)
|
||||
- [Contributing Commands](#contributing-commands)
|
||||
- [Pull Request Process](#pull-request-process)
|
||||
|
||||
---
|
||||
|
||||
## What We're Looking For
|
||||
|
||||
### Agents
|
||||
|
||||
New agents that handle specific tasks well:
|
||||
- Language-specific reviewers (Python, Go, Rust)
|
||||
- Framework experts (Django, Rails, Laravel, Spring)
|
||||
@@ -13,164 +24,385 @@ New agents that handle specific tasks well:
|
||||
- Domain experts (ML pipelines, data engineering, mobile)
|
||||
|
||||
### Skills
|
||||
|
||||
Workflow definitions and domain knowledge:
|
||||
- Language best practices
|
||||
- Framework patterns
|
||||
- Testing strategies
|
||||
- Architecture guides
|
||||
- Domain-specific knowledge
|
||||
|
||||
### Commands
|
||||
|
||||
Slash commands that invoke useful workflows:
|
||||
- Deployment commands
|
||||
- Testing commands
|
||||
- Documentation commands
|
||||
- Code generation commands
|
||||
|
||||
### Hooks
|
||||
|
||||
Useful automations:
|
||||
- Linting/formatting hooks
|
||||
- Security checks
|
||||
- Validation hooks
|
||||
- Notification hooks
|
||||
|
||||
### Rules
|
||||
|
||||
Always-follow guidelines:
|
||||
- Security rules
|
||||
- Code style rules
|
||||
- Testing requirements
|
||||
- Naming conventions
|
||||
|
||||
### MCP Configurations
|
||||
|
||||
New or improved MCP server configs:
|
||||
- Database integrations
|
||||
- Cloud provider MCPs
|
||||
- Monitoring tools
|
||||
- Communication tools
|
||||
### Commands
|
||||
Slash commands that invoke useful workflows:
|
||||
- Deployment commands
|
||||
- Testing commands
|
||||
- Code generation commands
|
||||
|
||||
---
|
||||
|
||||
## How to Contribute
|
||||
|
||||
### 1. Fork the repo
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/everything-claude-code.git
|
||||
# 1. Fork and clone
|
||||
gh repo fork affaan-m/everything-claude-code --clone
|
||||
cd everything-claude-code
|
||||
|
||||
# 2. Create a branch
|
||||
git checkout -b feat/my-contribution
|
||||
|
||||
# 3. Add your contribution (see sections below)
|
||||
|
||||
# 4. Test locally
|
||||
cp -r skills/my-skill ~/.claude/skills/ # for skills
|
||||
# Then test with Claude Code
|
||||
|
||||
# 5. Submit PR
|
||||
git add . && git commit -m "feat: add my-skill" && git push
|
||||
```
|
||||
|
||||
### 2. Create a branch
|
||||
---
|
||||
|
||||
```bash
|
||||
git checkout -b add-python-reviewer
|
||||
## Contributing Skills
|
||||
|
||||
Skills are knowledge modules that Claude Code loads based on context.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
skills/
|
||||
└── your-skill-name/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
### 3. Add your contribution
|
||||
|
||||
Place files in the appropriate directory:
|
||||
- `agents/` for new agents
|
||||
- `skills/` for skills (can be single .md or directory)
|
||||
- `commands/` for slash commands
|
||||
- `rules/` for rule files
|
||||
- `hooks/` for hook configurations
|
||||
- `mcp-configs/` for MCP server configs
|
||||
|
||||
### 4. Follow the format
|
||||
|
||||
**Agents** should have frontmatter:
|
||||
### SKILL.md Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: agent-name
|
||||
description: What it does
|
||||
tools: Read, Grep, Glob, Bash
|
||||
model: sonnet
|
||||
name: your-skill-name
|
||||
description: Brief description shown in skill list
|
||||
---
|
||||
|
||||
Instructions here...
|
||||
```
|
||||
# Your Skill Title
|
||||
|
||||
**Skills** should be clear and actionable:
|
||||
Brief overview of what this skill covers.
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
## Core Concepts
|
||||
|
||||
Explain key patterns and guidelines.
|
||||
|
||||
## Code Examples
|
||||
|
||||
\`\`\`typescript
|
||||
// Include practical, tested examples
|
||||
function example() {
|
||||
// Well-commented code
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Actionable guidelines
|
||||
- Do's and don'ts
|
||||
- Common pitfalls to avoid
|
||||
|
||||
## When to Use
|
||||
|
||||
...
|
||||
|
||||
## How It Works
|
||||
|
||||
...
|
||||
|
||||
## Examples
|
||||
|
||||
...
|
||||
Describe scenarios where this skill applies.
|
||||
```
|
||||
|
||||
**Commands** should explain what they do:
|
||||
### Skill Checklist
|
||||
|
||||
- [ ] Focused on one domain/technology
|
||||
- [ ] Includes practical code examples
|
||||
- [ ] Under 500 lines
|
||||
- [ ] Uses clear section headers
|
||||
- [ ] Tested with Claude Code
|
||||
|
||||
### Example Skills
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `coding-standards/` | TypeScript/JavaScript patterns |
|
||||
| `frontend-patterns/` | React and Next.js best practices |
|
||||
| `backend-patterns/` | API and database patterns |
|
||||
| `security-review/` | Security checklist |
|
||||
|
||||
---
|
||||
|
||||
## Contributing Agents
|
||||
|
||||
Agents are specialized assistants invoked via the Task tool.
|
||||
|
||||
### File Location
|
||||
|
||||
```
|
||||
agents/your-agent-name.md
|
||||
```
|
||||
|
||||
### Agent Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Brief description of command
|
||||
name: your-agent-name
|
||||
description: What this agent does and when Claude should invoke it. Be specific!
|
||||
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You are a [role] specialist.
|
||||
|
||||
## Your Role
|
||||
|
||||
- Primary responsibility
|
||||
- Secondary responsibility
|
||||
- What you DO NOT do (boundaries)
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Understand
|
||||
How you approach the task.
|
||||
|
||||
### Step 2: Execute
|
||||
How you perform the work.
|
||||
|
||||
### Step 3: Verify
|
||||
How you validate results.
|
||||
|
||||
## Output Format
|
||||
|
||||
What you return to the user.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: [Scenario]
|
||||
Input: [what user provides]
|
||||
Action: [what you do]
|
||||
Output: [what you return]
|
||||
```
|
||||
|
||||
### Agent Fields
|
||||
|
||||
| Field | Description | Options |
|
||||
|-------|-------------|---------|
|
||||
| `name` | Lowercase, hyphenated | `code-reviewer` |
|
||||
| `description` | Used to decide when to invoke | Be specific! |
|
||||
| `tools` | Only what's needed | `Read, Write, Edit, Bash, Grep, Glob, WebFetch, Task` |
|
||||
| `model` | Complexity level | `haiku` (simple), `sonnet` (coding), `opus` (complex) |
|
||||
|
||||
### Example Agents
|
||||
|
||||
| Agent | Purpose |
|
||||
|-------|---------|
|
||||
| `tdd-guide.md` | Test-driven development |
|
||||
| `code-reviewer.md` | Code review |
|
||||
| `security-reviewer.md` | Security scanning |
|
||||
| `build-error-resolver.md` | Fix build errors |
|
||||
|
||||
---
|
||||
|
||||
## Contributing Hooks
|
||||
|
||||
Hooks are automatic behaviors triggered by Claude Code events.
|
||||
|
||||
### File Location
|
||||
|
||||
```
|
||||
hooks/hooks.json
|
||||
```
|
||||
|
||||
### Hook Types
|
||||
|
||||
| Type | Trigger | Use Case |
|
||||
|------|---------|----------|
|
||||
| `PreToolUse` | Before tool runs | Validate, warn, block |
|
||||
| `PostToolUse` | After tool runs | Format, check, notify |
|
||||
| `SessionStart` | Session begins | Load context |
|
||||
| `Stop` | Session ends | Cleanup, audit |
|
||||
|
||||
### Hook Format
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "tool == \"Bash\" && tool_input.command matches \"rm -rf /\"",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo '[Hook] BLOCKED: Dangerous command' && exit 1"
|
||||
}
|
||||
],
|
||||
"description": "Block dangerous rm commands"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Matcher Syntax
|
||||
|
||||
```javascript
|
||||
// Match specific tools
|
||||
tool == "Bash"
|
||||
tool == "Edit"
|
||||
tool == "Write"
|
||||
|
||||
// Match input patterns
|
||||
tool_input.command matches "npm install"
|
||||
tool_input.file_path matches "\\.tsx?$"
|
||||
|
||||
// Combine conditions
|
||||
tool == "Bash" && tool_input.command matches "git push"
|
||||
```
|
||||
|
||||
### Hook Examples
|
||||
|
||||
```json
|
||||
// Block dev servers outside tmux
|
||||
{
|
||||
"matcher": "tool == \"Bash\" && tool_input.command matches \"npm run dev\"",
|
||||
"hooks": [{"type": "command", "command": "echo 'Use tmux for dev servers' && exit 1"}],
|
||||
"description": "Ensure dev servers run in tmux"
|
||||
}
|
||||
|
||||
// Auto-format after editing TypeScript
|
||||
{
|
||||
"matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\.tsx?$\"",
|
||||
"hooks": [{"type": "command", "command": "npx prettier --write \"$file_path\""}],
|
||||
"description": "Format TypeScript files after edit"
|
||||
}
|
||||
|
||||
// Warn before git push
|
||||
{
|
||||
"matcher": "tool == \"Bash\" && tool_input.command matches \"git push\"",
|
||||
"hooks": [{"type": "command", "command": "echo '[Hook] Review changes before pushing'"}],
|
||||
"description": "Reminder to review before push"
|
||||
}
|
||||
```
|
||||
|
||||
### Hook Checklist
|
||||
|
||||
- [ ] Matcher is specific (not overly broad)
|
||||
- [ ] Includes clear error/info messages
|
||||
- [ ] Uses correct exit codes (`exit 1` blocks, `exit 0` allows)
|
||||
- [ ] Tested thoroughly
|
||||
- [ ] Has description
|
||||
|
||||
---
|
||||
|
||||
## Contributing Commands
|
||||
|
||||
Commands are user-invoked actions with `/command-name`.
|
||||
|
||||
### File Location
|
||||
|
||||
```
|
||||
commands/your-command.md
|
||||
```
|
||||
|
||||
### Command Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Brief description shown in /help
|
||||
---
|
||||
|
||||
# Command Name
|
||||
|
||||
Detailed instructions...
|
||||
## Purpose
|
||||
|
||||
What this command does.
|
||||
|
||||
## Usage
|
||||
|
||||
\`\`\`
|
||||
/your-command [args]
|
||||
\`\`\`
|
||||
|
||||
## Workflow
|
||||
|
||||
1. First step
|
||||
2. Second step
|
||||
3. Final step
|
||||
|
||||
## Output
|
||||
|
||||
What the user receives.
|
||||
```
|
||||
|
||||
**Hooks** should include descriptions:
|
||||
### Example Commands
|
||||
|
||||
```json
|
||||
{
|
||||
"matcher": "...",
|
||||
"hooks": [...],
|
||||
"description": "What this hook does"
|
||||
}
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `commit.md` | Create git commits |
|
||||
| `code-review.md` | Review code changes |
|
||||
| `tdd.md` | TDD workflow |
|
||||
| `e2e.md` | E2E testing |
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
### 1. PR Title Format
|
||||
|
||||
```
|
||||
feat(skills): add rust-patterns skill
|
||||
feat(agents): add api-designer agent
|
||||
feat(hooks): add auto-format hook
|
||||
fix(skills): update React patterns
|
||||
docs: improve contributing guide
|
||||
```
|
||||
|
||||
### 5. Test your contribution
|
||||
### 2. PR Description
|
||||
|
||||
Make sure your config works with Claude Code before submitting.
|
||||
```markdown
|
||||
## Summary
|
||||
What you're adding and why.
|
||||
|
||||
### 6. Submit a PR
|
||||
## Type
|
||||
- [ ] Skill
|
||||
- [ ] Agent
|
||||
- [ ] Hook
|
||||
- [ ] Command
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Add Python code reviewer agent"
|
||||
git push origin add-python-reviewer
|
||||
## Testing
|
||||
How you tested this.
|
||||
|
||||
## Checklist
|
||||
- [ ] Follows format guidelines
|
||||
- [ ] Tested with Claude Code
|
||||
- [ ] No sensitive info (API keys, paths)
|
||||
- [ ] Clear descriptions
|
||||
```
|
||||
|
||||
Then open a PR with:
|
||||
- What you added
|
||||
- Why it's useful
|
||||
- How you tested it
|
||||
### 3. Review Process
|
||||
|
||||
1. Maintainers review within 48 hours
|
||||
2. Address feedback if requested
|
||||
3. Once approved, merged to main
|
||||
|
||||
---
|
||||
|
||||
## Guidelines
|
||||
|
||||
### Do
|
||||
|
||||
- Keep configs focused and modular
|
||||
- Keep contributions focused and modular
|
||||
- Include clear descriptions
|
||||
- Test before submitting
|
||||
- Follow existing patterns
|
||||
- Document any dependencies
|
||||
- Document dependencies
|
||||
|
||||
### Don't
|
||||
|
||||
- Include sensitive data (API keys, tokens, paths)
|
||||
- Add overly complex or niche configs
|
||||
- Submit untested configs
|
||||
- Create duplicate functionality
|
||||
- Add configs that require specific paid services without alternatives
|
||||
- Submit untested contributions
|
||||
- Create duplicates of existing functionality
|
||||
|
||||
---
|
||||
|
||||
@@ -178,14 +410,15 @@ Then open a PR with:
|
||||
|
||||
- Use lowercase with hyphens: `python-reviewer.md`
|
||||
- Be descriptive: `tdd-workflow.md` not `workflow.md`
|
||||
- Match the agent/skill name to the filename
|
||||
- Match name to filename
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
Open an issue or reach out on X: [@affaanmustafa](https://x.com/affaanmustafa)
|
||||
- **Issues:** [github.com/affaan-m/everything-claude-code/issues](https://github.com/affaan-m/everything-claude-code/issues)
|
||||
- **X/Twitter:** [@affaanmustafa](https://x.com/affaanmustafa)
|
||||
|
||||
---
|
||||
|
||||
Thanks for contributing. Let's build a great resource together.
|
||||
Thanks for contributing! Let's build a great resource together.
|
||||
|
||||
Reference in New Issue
Block a user