The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: enhance CONTRIBUTING.md with detailed templates
Affaan Mustafac0fdd89c4957
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 2a0f41854..ec9fefab0 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+### Hooks+Useful automations:+- Linting/formatting hooks+- Security checks+- Validation hooks+- Notification hooks+### CommandsSlash 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+## Quick Start++```bash+# 1. Fork and clone+gh repo fork affaan-m/everything-claude-code --clone+cd everything-claude-code-### Rules+# 2. Create a branch+git checkout -b feat/my-contribution-Always-follow guidelines:-- Security rules-- Code style rules-- Testing requirements-- Naming conventions+# 3. Add your contribution (see sections below)-### MCP Configurations+# 4. Test locally+cp -r skills/my-skill ~/.claude/skills/ # for skills+# Then test with Claude Code-New or improved MCP server configs:-- Database integrations-- Cloud provider MCPs-- Monitoring tools-- Communication tools+# 5. Submit PR+git add . && git commit -m "feat: add my-skill" && git push+```----## How to Contribute+## Contributing Skills-### 1. Fork the repo+Skills are knowledge modules that Claude Code loads based on context.++### Directory Structure-```bash-git clone https://github.com/YOUR_USERNAME/everything-claude-code.git-cd everything-claude-code+```+skills/+└── your-skill-name/+ └── SKILL.md```-### 2. Create a branch+### SKILL.md Template-```bash-git checkout -b add-python-reviewer+```markdown+---+name: your-skill-name+description: Brief description shown in skill list+---++# Your Skill Title++Brief overview of what this skill covers.++## 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++Describe scenarios where this skill applies.```-### 3. Add your contribution+### Skill Checklist++- [ ] Focused on one domain/technology+- [ ] Includes practical code examples+- [ ] Under 500 lines+- [ ] Uses clear section headers+- [ ] Tested with Claude Code-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+### Example Skills-### 4. Follow the format+| 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 |++----**Agents** should have frontmatter:+## Contributing Agents++Agents are specialized assistants invoked via the Task tool.++### File Location++```+agents/your-agent-name.md+```++### Agent Template```markdown----name: agent-name-description: What it does-tools: Read, Grep, Glob, Bash+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----Instructions here...-```+You are a [role] specialist.-**Skills** should be clear and actionable:+## Your Role-```markdown-# Skill Name+- Primary responsibility+- Secondary responsibility+- What you DO NOT do (boundaries)-## When to Use+## Workflow++### Step 1: Understand+How you approach the task.-...+### Step 2: Execute+How you perform the work.-## How It Works+### 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]```-**Commands** should explain what they do:+### 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 |-```markdown-----description: Brief description of command----# Command Name+## Contributing Hooks++Hooks are automatic behaviors triggered by Claude Code events.++### File Location-Detailed instructions...```+hooks/hooks.json+```++### Hook Types-**Hooks** should include descriptions:+| 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{- "matcher": "...",- "hooks": [...],- "description": "What this hook does"+ "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"+ }+ ]+ }}```-### 5. Test your contribution+### Matcher Syntax-Make sure your config works with Claude Code before submitting.+```javascript+// Match specific tools+tool == "Bash"+tool == "Edit"+tool == "Write"-### 6. Submit a PR+// Match input patterns+tool_input.command matches "npm install"+tool_input.file_path matches "\\.tsx?$"-```bash-git add .-git commit -m "Add Python code reviewer agent"-git push origin add-python-reviewer+// 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++## Purpose++What this command does.++## Usage++\`\`\`+/your-command [args]+\`\`\`++## Workflow++1. First step+2. Second step+3. Final step++## Output++What the user receives.```-Then open a PR with:-- What you added-- Why it's useful-- How you tested it+### Example Commands++| 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+```++### 2. PR Description++```markdown+## Summary+What you're adding and why.++## Type+- [ ] Skill+- [ ] Agent+- [ ] Hook+- [ ] Command++## Testing+How you tested this.++## Checklist+- [ ] Follows format guidelines+- [ ] Tested with Claude Code+- [ ] No sensitive info (API keys, paths)+- [ ] Clear descriptions+```++### 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.