Skip to content

armgit / ECC

Public Imported from GitHub
0

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.md
index 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
+### 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
+## 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.