Poshan Pandey
100 lines
4.2 KiB
Markdown
100 lines
4.2 KiB
Markdown
# 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.
|