zsp/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-03-30 13:43:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: enhance CONTRIBUTING.md with detailed templates

Browse Source 
- 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
2026-02-05 17:18:06 -08:00
parent 0f7b3081ee
commit c0fdd89c49
1 changed files with 330 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

427
CONTRIBUTING.md
View File

@@ -1,11 +1,22 @@
# Contributing to Everything Claude Code # 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 ## What We're Looking For
### Agents ### Agents
New agents that handle specific tasks well: New agents that handle specific tasks well:
- Language-specific reviewers (Python, Go, Rust) - Language-specific reviewers (Python, Go, Rust)
- Framework experts (Django, Rails, Laravel, Spring) - Framework experts (Django, Rails, Laravel, Spring)
@@ -13,164 +24,385 @@ New agents that handle specific tasks well:
- Domain experts (ML pipelines, data engineering, mobile) - Domain experts (ML pipelines, data engineering, mobile)
### Skills ### Skills
Workflow definitions and domain knowledge: Workflow definitions and domain knowledge:
- Language best practices - Language best practices
- Framework patterns - Framework patterns
- Testing strategies - Testing strategies
- Architecture guides - Architecture guides
- Domain-specific knowledge
### Commands
Slash commands that invoke useful workflows:
- Deployment commands
- Testing commands
- Documentation commands
- Code generation commands
### Hooks ### Hooks
Useful automations: Useful automations:
- Linting/formatting hooks - Linting/formatting hooks
- Security checks - Security checks
- Validation hooks - Validation hooks
- Notification hooks - Notification hooks
### Rules ### Commands
Slash commands that invoke useful workflows:
Always-follow guidelines: - Deployment commands
- Security rules - Testing commands
- Code style rules - Code generation commands
- Testing requirements
- Naming conventions
### MCP Configurations
New or improved MCP server configs:
- Database integrations
- Cloud provider MCPs
- Monitoring tools
- Communication tools
--- ---
## How to Contribute ## Quick Start
### 1. Fork the repo
```bash ```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 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 ## Contributing Skills
git checkout -b add-python-reviewer
Skills are knowledge modules that Claude Code loads based on context.
### Directory Structure
```
skills/
└── your-skill-name/
└── SKILL.md
``` ```
### 3. Add your contribution ### SKILL.md Template
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:
```markdown ```markdown
--- ---
name: agent-name name: your-skill-name
description: What it does description: Brief description shown in skill list
tools: Read, Grep, Glob, Bash
model: sonnet
--- ---
Instructions here... # Your Skill Title
```
**Skills** should be clear and actionable: Brief overview of what this skill covers.
```markdown ## Core Concepts
# Skill Name
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 ## When to Use
... Describe scenarios where this skill applies.
## How It Works
...
## Examples
...
``` ```
**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 ```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 # 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 | Command | Purpose |
{ |---------|---------|
"matcher": "...", | `commit.md` | Create git commits |
"hooks": [...], | `code-review.md` | Review code changes |
"description": "What this hook does" | `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 ## Testing
git add . How you tested this.
git commit -m "Add Python code reviewer agent"
git push origin add-python-reviewer ## Checklist
- [ ] Follows format guidelines
- [ ] Tested with Claude Code
- [ ] No sensitive info (API keys, paths)
- [ ] Clear descriptions
``` ```
Then open a PR with: ### 3. Review Process
- What you added
- Why it's useful 1. Maintainers review within 48 hours
- How you tested it 2. Address feedback if requested
3. Once approved, merged to main
--- ---
## Guidelines ## Guidelines
### Do ### Do
- Keep contributions focused and modular
- Keep configs focused and modular
- Include clear descriptions - Include clear descriptions
- Test before submitting - Test before submitting
- Follow existing patterns - Follow existing patterns
- Document any dependencies - Document dependencies
### Don't ### Don't
- Include sensitive data (API keys, tokens, paths) - Include sensitive data (API keys, tokens, paths)
- Add overly complex or niche configs - Add overly complex or niche configs
- Submit untested configs - Submit untested contributions
- Create duplicate functionality - Create duplicates of existing functionality
- Add configs that require specific paid services without alternatives
--- ---
@@ -178,14 +410,15 @@ Then open a PR with:
- Use lowercase with hyphens: `python-reviewer.md` - Use lowercase with hyphens: `python-reviewer.md`
- Be descriptive: `tdd-workflow.md` not `workflow.md` - Be descriptive: `tdd-workflow.md` not `workflow.md`
- Match the agent/skill name to the filename - Match name to filename
--- ---
## Questions? ## 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.