Add dotclaude configuration files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 17:16:27 -07:00
parent c10636b330
commit 491a45dd43
37 changed files with 2737 additions and 0 deletions
@@ -0,0 +1,99 @@
+# Contributing to dotclaude
+
+Thanks for wanting to make this better. This project aims to be the standard `.claude/` folder structure — contributions that help more developers ship faster are welcome.
+
+## Before You Contribute
+
+- Check existing issues and open PRs to avoid duplicate work
+- For large changes (new skills, new agents, restructuring), open an issue first to discuss the approach
+
+## What We're Looking For
+
+**Yes, please:**
+- Bug fixes in hook scripts
+- Improvements to existing rules, skills, or agents that make them more effective
+- New skills for common daily workflows (not project-creation workflows)
+- New agents for common review/analysis tasks
+- Better token efficiency — same quality, fewer tokens
+- Documentation improvements
+
+**Probably not:**
+- Language-specific rules — Claude already knows standard conventions
+- Plugin integrations — this repo is deliberately plugin-free
+- Project scaffolding skills — this is for daily work, not project creation
+- Vendor-specific configurations (specific CI providers, cloud platforms, etc.)
+
+## PR Rules
+
+### One thing per PR
+
+Each PR should do exactly one thing. Don't bundle a new skill with a rule fix with a README update. Split them.
+
+### File requirements
+
+| File type | Must have | Must NOT have |
+|---|---|---|
+| **Rules** (`.md` in `rules/`) | `alwaysApply: true` or `paths:` frontmatter | Language-specific conventions Claude already knows |
+| **Skills** (`SKILL.md`) | `name`, `description` in frontmatter | Hardcoded package names, model assignments |
+| **Agents** (`.md` in `agents/`) | `name`, `description`, `tools` in frontmatter | `model` field (users choose their own model) |
+| **Hooks** (`.sh` in `hooks/`) | `jq` availability check, proper exit codes (0=allow, 2=block) | Hardcoded paths, missing `#!/bin/bash` |
+
+### Naming
+
+- Skill directories: `kebab-case` — `debug-fix/`, `test-writer/`
+- Agent files: `kebab-case.md` — `code-reviewer.md`, `security-reviewer.md`
+- Rule files: `kebab-case.md` — `code-quality.md`, `frontend.md`
+- Hook scripts: `kebab-case.sh` — `protect-files.sh`, `block-dangerous-commands.sh`
+
+### No duplication
+
+Before adding content, check that it's not already covered elsewhere:
+
+- If a hook enforces it, don't also add a rule saying the same thing
+- If a skill covers it, don't duplicate the guidance in a rule
+- If `CLAUDE.md` says it, don't repeat it in a rule
+- Agents run isolated and CAN repeat rule content (they don't see rules)
+
+### No hardcoded opinions
+
+This is a template — keep it framework-agnostic:
+
+- Don't hardcode `npm`, `pnpm`, `yarn`, or any specific package manager
+- Don't hardcode specific component libraries, CSS frameworks, or test runners
+- Don't assign `model` to agents or skills — let users choose
+- Present options as tables or lists, not mandates
+- The `/setupdotclaude` skill handles project-specific customization at runtime
+
+### Token consciousness
+
+Every line in a rule costs tokens every session. Every line in a skill costs tokens when invoked. Before adding content, ask: "Would removing this cause Claude to make mistakes?" If no, don't add it.
+
+### Hook scripts must be safe
+
+- Always check for `jq` availability before using it
+- Exit 0 (allow) if dependencies are missing — don't block the user
+- PreToolUse hooks observe and block — they should never modify files. PostToolUse hooks may transform output (e.g., formatting).
+- Test with sample JSON input before submitting
+
+### Update READMEs
+
+If you add a new file to `rules/`, `skills/`, `agents/`, or `hooks/`, add a description to the README in that folder. Keep it to 2-3 lines.
+
+### Update the root README
+
+If your change adds or removes a file, update the structure tree in `README.md` to match.
+
+## How to Submit
+
+1. Fork the repo
+2. Create a branch: `feat/your-skill-name` or `fix/hook-bug-description`
+3. Make your changes
+4. Test: verify YAML frontmatter is valid, hook scripts work with sample input, no duplication with existing files
+5. Open a PR with:
+   - **Title**: what you added/changed (under 72 chars)
+   - **Body**: why it's useful, what daily workflow it improves
+   - **Testing**: how you verified it works
+
+## Code of Conduct
+
+Be helpful, be kind, be constructive. We're all here to make Claude Code better for daily development work.