Contributing to Shared Agents

Thank you for helping improve the Core open-source project. This document covers what belongs here, how to develop locally, and how to submit changes.

Website: shared-agents docs — Contributing (when served from the project website).

Core vs team data

Learnings, team rules, and optional team-only skills live in a separate private Git repository, mounted at $SHARED_AGENTS_HOME/team/. Configure it during sa bootstrap or in config.local.yaml (team.remote).

Team rules use flat team/rules/*.mdc (like team/skills/) — no pending/review workflow.

Development setup

Clone and install into your home directory (or use an existing bootstrap):

git clone git@github.com:netgrade-digital/shared-agents.git
cd shared-agents
./sa install --home "$HOME/.shared-agents"
source ~/.bashrc

Work on the clone, then test changes:

sa install --dry-run
sa install
sa check

Run scripts directly when debugging: python3 scripts/install-adapters.py check ~/.shared-agents

Pull requests

1. Branch from main with a focused change (one feature or fix per PR).
2. Test with sa install and sa check on at least one supported tool you have installed.
3. Describe what changed and why; include sa check output if you touched adapters.
4. No secrets — no tokens, private URLs, or team learnings in Core.
5. CLI changes — update scripts/sa and keep sa help accurate; extend skills/sa-cli/SKILL.md when behavior is non-obvious.

We use fast-forward merges on main. Keep PRs small and reviewable.

Adding support for a new AI tool

1. Add an entry to adapters/manifest.json:

   • detect — config directory (e.g. ~/.cursor)
   • detect_bins — optional CLI names on $PATH
   • agents_md and/or sync — see existing tools

2. Add adapters/<tool-id>/README.md with setup notes.

3. Verify:

   sa install --dry-run
   sa install
   sa check
   

4. Open a PR with sample sa check output.

Manifest fields

Installed ≠ configured. sa install only configures tools that are detected as installed. sa check reports the full matrix.

For tools without a manifest entry, users can copy adapters/generic/instructions.md into their global agent config.

See also docs/adapters.md.

Adding or changing Core skills

• Place skills under skills/<name>/SKILL.md.
• Keep content safe for a public repo (no credentials, no client-specific paths).
• After adding a skill or rule, teammates run sa sync (auto-links). Use sa install for first-time adapter setup.
• If the skill changes agent workflow (paths, sync, learnings, rules), update rules/shared-agents-knowledge.mdc and skills/shared-agents-knowledge/SKILL.md when relevant.

Team skills and rules (team repo, not Core)

Private team content lives under team/skills/ and team/rules/ (flat .mdc for rules). Use the wizards:

sa skill new    # team/skills/<name>/SKILL.md
sa skill rm     # remove (picker)
sa rule new     # team/rules/<slug>.mdc
sa rule rm      # remove (picker)

Commit/push defaults to yes after create/remove (--no-git to skip). Teammates run sa sync. No pending/review workflow (unlike learnings).

See docs/skills-and-rules.md.

Learnings (team repo, not Core)

Agents draft learnings in team/learnings/pending/ after explicit user approval. Humans promote them with sa review into team/learnings/approved/.

Contributors documenting this flow should edit docs/learnings.md and docs/canonical-paths.md, not put learning files in Core PRs.

Documentation (website + repo)

Guides live under docs/ and render on the project website at /docs/<slug>. When adding topics:

• Write in English
• Use clear H1 titles (become page titles)
• Cross-link with docs/other-topic.md or /docs/other-topic

CONTRIBUTING.md (this file) is also published as /docs/contributing.

Shared MCPs (planned)

MCP wiring is specced in docs/shared-mcps.md. When implemented:

• Mirror install-adapters.py patterns (stdlib only, idempotent, --check, --dry-run)
• Integrate via sa install / install.sh
• Never commit mcps.local.yaml or secrets
• Use managed prefix sa- for team servers

Reference: mcps/manifest.example.json

Code guidelines

Questions

Open a GitHub issue for bugs or design questions. For day-to-day CLI usage, run sa help or read the CLI reference and sa-cli skill.