mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-17 22:46:29 +03:00
Magnus Hedemark
c5c4d2434a
Comprehensive open source contribution guidance with progressive disclosure. Restructured from a single ~23K-token monolithic SKILL.md into a concise ~1.2K-token orchestrator with 10 focused reference files. Changes: - SKILL.md: 1,720 lines → 100 lines (AgentSkills.io compliant frontmatter) - 10 new reference files covering phases 0a-4, pitfalls, default posture - Portable PR template compliance checker script (stdlib-only) - All personal context scrubbed for public export - AGENTS.md + README.md updated with trigger table entry Signed-off-by: Magnus Hedemark <magnus919@pm.me>
39 lines
3.3 KiB
Markdown
39 lines
3.3 KiB
Markdown
# Case Study: Hermes Agent CONTRIBUTING.md
|
|
|
|
This is a real-world example of a well-written CONTRIBUTING.md from a project we've contributed to. It demonstrates everything a good contributing guide can cover.
|
|
|
|
**Source:** https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md
|
|
|
|
## What It Covers
|
|
|
|
| Section | What We Learn |
|
|
|---|---|
|
|
| **Contribution Priorities** | Not all contributions are equal. This project explicitly prioritizes: bug fixes > cross-platform compatibility > security > performance > new skills > new tools > docs. Knowing this tells you where your contribution effort is most welcome. |
|
|
| **Skill vs Tool Decision Guide** | A detailed framework for deciding whether a capability should be a skill or a tool. The answer is almost always "skill." Also covers bundled vs optional vs Skills Hub placement. |
|
|
| **Development Setup** | Exact commands needed to set up a local dev environment. If we'd read this, we'd have known about `--recurse-submodules`, the specific `uv venv --python 3.11`, and `uv pip install -e ".[all,dev]"`. |
|
|
| **Project Structure** | Maps the entire codebase so you know where your change goes. |
|
|
| **Architecture Overview** | Core loop, key design patterns, provider abstraction. Essential context before modifying agent behavior. |
|
|
| **Code Style** | PEP 8 with practical exceptions. Comments only for non-obvious intent. Cross-platform rules. |
|
|
| **Adding a New Tool** | Self-registering pattern with `registry.register()`, auto-discovery, toolset wiring in `toolsets.py`. |
|
|
| **Adding a Skill** | SKILL.md format with frontmatter, platform-specific skills, conditional activation, required env vars, skill guidelines (no external deps, progressive disclosure). |
|
|
| **Cross-Platform Compatibility** | Extensive rules for Windows compatibility (16 specific rules). This is a huge section — cross-platform care matters to this project. |
|
|
| **Security Considerations** | Existing protection layers, what to do when contributing security-sensitive code. |
|
|
| **PR Process** | Branch naming (`fix/`, `feat/`, etc.), what to test before submitting, PR description format, Conventional Commits. |
|
|
| **License** | By contributing, you agree to MIT licensing. |
|
|
|
|
## Common Contributor Mistakes This Prevents
|
|
|
|
Reading the contributing guide *before* starting work prevents common mismatches between contributor intent and maintainer expectations:
|
|
|
|
1. **Branch naming** — Using project-standard prefixes (`fix/`, `feat/`) instead of arbitrary names
|
|
2. **Commit messages** — Following the project's commit format requirements instead of defaulting to freeform
|
|
3. **Tests** — Running the project's test suite before submission
|
|
4. **Development setup** — Using the project's exact dev environment commands instead of guessing
|
|
5. **PR description format** — Filling out the project's PR template rather than writing a freeform summary
|
|
6. **Skill/tool classification** — Understanding where different types of changes belong in the project structure
|
|
7. **Cross-platform considerations** — Checking for platform-specific requirements the project enforces
|
|
|
|
## Key Takeaway
|
|
|
|
Even a single READ of CONTRIBUTING.md before starting work would have caught most of these. The document exists to prevent exactly this kind of mismatch between contributor intent and maintainer expectations.
|