From c0fdd89c4957c2abcbe5cfe424027398b8e65fd1 Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Thu, 5 Feb 2026 17:18:06 -0800 Subject: [PATCH] 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 --- CONTRIBUTING.md | 427 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 330 insertions(+), 97 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a0f4185..ec9fefab 100644 --- a/CONTRIBUTING.md +++ b/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.