1# Contributing to Agent Skills for Context Engineering
2 
3Thank you for your interest in contributing to this collection of Agent Skills for Context Engineering. This document provides guidelines and instructions for contributing.
4 
5## How to Contribute
6 
7### Reporting Issues
8 
9If you find errors, unclear explanations, or missing topics, please open an issue with:
10- A clear description of the problem
11- The skill and section where the issue was found
12- Suggested improvements if you have them
13 
14### Submitting Changes
15 
16For substantive changes, please:
17 
181. Fork the repository
192. Create a feature branch for your changes
203. Make changes following the skill template structure
214. Ensure SKILL.md files remain under 500 lines
225. Add references or scripts as appropriate
236. Submit a pull request with a clear description of changes
24 
25### Adding New Skills
26 
27When adding new skills:
28 
291. Use the template in `template/SKILL.md`
302. Follow naming conventions (lowercase with hyphens)
313. Include both SKILL.md and appropriate references/scripts
324. Update the root README.md to include the new skill
335. Update root `SKILL.md`, `.claude-plugin/marketplace.json`, and `.plugin/plugin.json` when publishing the skill
346. Update `researcher/corpus/index.json` with the new skill's name, activation scenarios, mechanism IDs, and claim IDs
357. Add at least one entry to `researcher/fixtures/activation-cases.jsonl`; include rejected or adjacent skills when the boundary is easy to confuse
368. Ensure content is platform-agnostic (works across Cursor, Claude Code, etc.)
379. Run `python3 researcher/scripts/validate_repo.py --strict`, `python3 researcher/scripts/skill_health.py --strict --no-history`, `python3 researcher/scripts/check_activation_cases.py`, and `python3 researcher/scripts/run_benchmarks.py` before opening a PR
38 
39## Researcher Operating System Contributions
40 
41The repository ships with a file-based research-to-skill operating system in `researcher/`. Contributions that introduce skill changes derived from external research should flow through it.
42 
43### Run lifecycle
44 
45```
46initialized -> retrieved -> evaluated -> proposed -> novelty_checked -> validated -> pr_ready -> closed
47```
48 
49Use `researcher/scripts/research_loop.py` subcommands rather than editing `run-state.json` by hand. Each transition appends to the run's thread log and updates the state machine atomically.
50 
51### Mechanism promotion
52 
53New behavior changes proposed for the corpus go through `researcher/mechanisms/registry.jsonl`. The promotion path is gated:
54 
551. Author the proposal in the run's `proposals/mechanism-proposal.jsonl`.
562. Pass `validate_run.py --run-dir <run>`.
573. Run `research_loop.py promote-mechanisms --run-dir <run> --reviewed-by <handle>`. This appends to the registry and to `researcher/mechanisms/ledgers/accepted.jsonl`.
58 
59Rejected mechanisms append to `ledgers/rejected.jsonl` so future agents do not rediscover them.
60 
61### Claim provenance
62 
63Any numeric, benchmark, or volatile claim added to a published skill should also receive an entry in `researcher/claims/index.jsonl` with `claim_id`, `owning_skill`, `section`, `source_url`, `retrieved_at`, `evidence_strength`, `volatility`, and `last_reviewed`. The validator checks ownership and source paths.
64 
65### Parked runs
66 
67Runs that hit human-review gates land in `researcher/queue/parked.jsonl` and the dashboard at `researcher/reports/parked-review.md`. Reviewers should:
68 
691. Read `researcher/runs/<run-id>/THREAD.md` and `sources/evidence/`.
702. Complete the next required step (retrieve, evaluate, propose, novelty, validate-run, or pr-ready).
713. Close the run with `research_loop.py close --status accepted|rejected|reference-only|abandoned --reason <text> --reviewed-by <handle>`.
72 
73The continuous loop will reap closed runs into `researcher/queue/done.jsonl` on the next iteration.
74 
75### Runtime state is not committed
76 
77`researcher/runs/*/` (except the seed run), `researcher/queue/*.jsonl`, and `researcher/reports/{logs,snapshots,loop-events.jsonl,loop-failures.jsonl,status.md,parked-review.md}` are gitignored. PRs should not introduce new committed runs; bug fixtures belong in `researcher/fixtures/` instead.
78 
79## Skill Structure Requirements
80 
81Each skill must include:
82 
83- YAML frontmatter with `name` and `description` fields
84- `## When to Activate` with positive triggers and an explicit `Do not activate` boundary for adjacent skills
85- `## Core Concepts` focused on behavior-changing mechanisms, not generic background
86- `## Practical Guidance` with an executable workflow, checklist, decision table, or operating rule
87- `## Examples` with at least one worked artifact, before/after, or boundary example
88- `## Guidelines`, `## Gotchas`, `## Integration`, and `## References`
89- Integration notes that explain routing and composition boundaries, not only topical relationships
90 
91Any numeric, benchmark, volatile, or vendor-performance claim in a published skill must either reference a `claim-*` ID from `researcher/claims/index.jsonl` or be softened and moved to dated reference material. Any reusable behavior pattern should be represented in `researcher/mechanisms/registry.jsonl` and linked from `researcher/corpus/index.json`.
92 
93Optional additions:
94 
95- `references/` directory with additional documentation
96- `scripts/` directory with executable examples
97- Multiple markdown files for complex skills
98 
99## Content Guidelines
100 
101### Writing Style
102 
103- Be direct and precise
104- Use technical terminology appropriately
105- Include specific guidance, not vague recommendations
106- Provide concrete examples
107- Point out complexity and trade-offs
108 
109### Avoiding Platform Specificity
110 
111Skills should work across agent platforms. Avoid:
112- Platform-specific tool names without abstraction
113- Vendor-locked examples
114- Features specific to one agent product
115 
116### Keeping Skills Focused
117 
118Each skill should have a single focus. If a topic grows too large, consider splitting into multiple skills with clear dependencies.
119 
120## Code of Conduct
121 
122This project follows a professional, technical collaboration model. Be respectful of different perspectives and focus on improving the collective knowledge base.
123 
124## Questions
125 
126For questions about contributing, please open an issue for discussion.
127 
128