shared-agents

Team skills, rules, and learnings for AI assistants — one install, Git-synced, IDE-agnostic.

If this project helps your team, consider giving it a ⭐ on GitHub.

Why this exists

Teams use many AI tools (Cursor, Claude Code, Zed, Codex, …). Each session starts cold: no shared workflows, no institutional memory, and knowledge trapped in chats or private notes.

Shared Agents gives you one place to:

• Skills — how we work (repeatable workflows for agents)
• Rules — shared instructions per tool (Cursor .mdc, others via AGENTS.md / CLAUDE.md)
• Learnings — what we already figured out (bugs, stack quirks, decisions)

Everyone syncs the same content. Agents load it automatically at session start. Sensitive team data stays in a private repo, not public.

What it is

  GitHub (Core)              Your private remote (Team)
        │                              │
        └────────── sa sync ───────────┘
                        │
                        ▼
              ~/.shared-agents  ──►  Cursor · Claude Code · Zed · …

• Tool-neutral — Markdown + Git, no vendor lock-in
• Manifest-driven adapters — hooks and global instructions per IDE/CLI
• Human-in-the-loop learnings — agents propose drafts; a person approves via sa review
• Team rules like skills — flat team/rules/*.mdc; manage with sa skill / sa rule; teammates sa sync

Quick start

curl -fsSL https://raw.githubusercontent.com/netgrade-digital/shared-agents/refs/heads/main/scripts/bootstrap.sh | bash

The bootstrap wizard installs Core, optionally wires your team repo, and configures detected tools. Then open a new shell and run sa.

Non-interactive (CI/scripts): SA_BOOTSTRAP_NON_INTERACTIVE=1 curl -fsSL … | bash

Everyday use

What sa sync does

After pulling Core + team (ff-only):

1. Skill symlinks — skills/ + team/skills/ → ~/.agents/skills, ~/.claude/skills, …
2. Rule symlinks — Cursor: rules/ + team/rules/ → ~/.cursor/rules/
3. Team-rules blocks — Zed, Codex, Claude Code, Gemini, Windsurf, …: <!-- shared-agents:team-rules:begin/end --> in each tool's AGENTS.md / CLAUDE.md

Also runs quietly via IDE session hooks where configured. sa install is still required once per tool (hooks, base <!-- shared-agents:begin --> block).

Team content (skills & rules)

Lives in your private team repo under team/skills/ and team/rules/ — not in Core PRs. No pending/review workflow (unlike learnings).

sa skill new          # wizard → team/skills/<name>/SKILL.md
sa rule new           # wizard → team/rules/<slug>.mdc
sa skill rm [name]    # remove (picker if name omitted)
sa rule rm [slug]

Create/remove wizards commit + push by default (Enter = yes; --no-git to skip). Then teammates run sa sync.

Dev checkout: ./sa sync from this repo uses scripts from the clone (even before ~/.shared-agents is updated). Shell alias sa uses $SHARED_AGENTS_HOME/scripts/ — refresh with ./sa install after pulling Core changes.

Repository layout

shared-agents/
├── skills/              # Core skills (synced to ~/.agents/skills, etc.)
├── rules/               # Core rules (.mdc) — Cursor symlinks + AGENTS.md merge
├── adapters/            # Per-tool wiring (manifest.json + docs)
├── scripts/             # sa CLI, sync, bootstrap, learning tools
├── docs/                # Detailed guides
└── team/                # Private team data (gitignored here — separate remote)
    ├── learnings/       # pending/ + approved/ (review via sa review)
    ├── rules/           # flat *.mdc (like team/skills/)
    └── skills/

Install path defaults to ~/.shared-agents. Team data lives under team/ inside that directory.

Documentation

Contributing

Contributions to Core (adapters, CLI, docs, shared skills, shared rules) are welcome. Team learnings and team rules belong in your private team repo, not in pull requests here.

See CONTRIBUTING.md.

License

MIT — maintained by netgrade-digital.

Star History