Skip to content

Contributing Guide

Jump to bottom
Pedro Rocha edited this page Aug 16, 2026 · 1 revision

Contributing Guide

Thank you for your interest in contributing to awesome-skills!

Workflow (every change)

  1. Branch from main: feat/..., fix/..., docs/..., chore/...
  2. Follow templates/ for new skills/agents/plugins
  3. Never hand-edit the README above the Index/Contributing sections — run python3 tools/gen_index.py
  4. Verify locally before commit
  5. Open a PR with the seven standard assignment fields
  6. Review per docs/CODE_REVIEW.md
  7. Merge --squash; delete the branch

Standard Assignment Fields

Every issue and PR must include:

Field Description
Assignee Who is responsible
Reviewer Who reviews the PR
Labels bug, enhancement, documentation, etc.
Project Awesome Skills — Roadmap
Milestone Backlog / release tag
Development Branch linked to issue
Relationship Closes/Relates #N

Adding a New Skill

  1. Copy templates/skill-template/ to skills/<category>/<new-skill>/
  2. Edit SKILL.md frontmatter (name, description, version, tags)
  3. Write the body (Trigger, Steps, Pitfalls, Verification)
  4. Run python3 tools/gen_index.py to update README
  5. Open PR with all seven assignments

Adding a New Agent

  1. Copy templates/agent-template/ to agents/<category>/<new-agent>/
  2. Edit AGENT.md and manifest.json
  3. Run python3 tools/gen_index.py to update README
  4. Open PR with all seven assignments

Adding a New Plugin

  1. Copy templates/plugin-template/ to plugins/<category>/<new-plugin>/
  2. Edit PLUGIN.md and manifest.json
  3. Run python3 tools/gen_index.py to update README
  4. Open PR with all seven assignments

Commit Convention

We use Conventional Commits:

Type Description
feat New skill or feature
fix Bug fix
refactor Code restructuring
docs Documentation
chore Maintenance
test Tests
ci CI/CD

Example:

feat(readme): add Star History chart

- Add RepoActivity section
- Fix URL to api.star-history.com

Verification (before every commit)

python3 tools/gen_index.py
python3 -c "import yaml; yaml.safe_load(open('skills/<cat>/<name>/SKILL.md').read().split('---')[1]); print('SKILL_OK')"

Code Review Standard

See docs/CODE_REVIEW.md for the review model (severity table + rubrics).

Links

Clone this wiki locally