Shared Snippet Conventions for Dev Teams: A Practical Ruleset
Last updated: November 3, 2026 · Reading time: ~8 min
Most teams discover they need snippet conventions the day two people paste two slightly different versions of the same incident-response template into the same channel. Everyone has a snippet. Nobody knows whose is current.
This article is a ruleset, not a tool review. Each rule comes with its rationale, so you can bend it when your team differs from the assumptions. It ends with a template you can copy into a repo today.
Should a team share snippets through a clipboard manager?
No. A clipboard manager records what you copied; a snippet library stores what you decided to reuse. They solve different problems, and mixing them is how teams end up with stale, unreviewed text.
Maccy App is a good example of the boundary. It is a local-first clipboard history for macOS: it stores your recent copies on your machine, lets you search them, and lets you pin items you want to keep. It does not sync to other machines and has no team-sharing layer . That is a feature for privacy, and it is exactly why it should not be your team’s source of truth.
The workable split looks like this:
| Need | Right tool | Why |
|---|---|---|
| Reviewed, versioned team templates (PR descriptions, incident updates, SQL boilerplate) | A git repo consumed by a text expander | Diffs, blame, code review, rollback |
| Personal shortcuts | Text expander or macOS Text Replacements | Fast, no review needed |
| “What was that command I copied ten minutes ago?” | Clipboard manager (e.g., Maccy) | Recall of ephemeral content |
| Pinned one-offs you reuse this week | Maccy pins | Quick access without committing to a convention |
The ten conventions
1. One source of truth, in version control
Rule: The canonical snippet library is a git repository with a README and a CODEOWNERS file.
Why: Snippets are code-adjacent text with the same failure modes as code: drift, silent edits, and “works on my machine.” Git gives you review, history, and a way to answer “who changed this and why?” Shared documents and chat pins give you none of that.
Practical note: Espanso, an open-source cross-platform text expander, stores matches in YAML files and supports installing packages from git repositories, which makes it a natural consumer of a team repo . Whatever tool you choose, prefer one whose config is plain text.
2. Prefix every trigger with a category
Rule: Triggers follow <sigil><category>-<name>, for example ;pr-bugfix, ;inc-update, ;sql-explain.
Why: Flat trigger namespaces collide as libraries grow. A category prefix gives you autocomplete-by-memory and makes collisions visible in review. Pick a sigil that will not appear in normal prose or code. A leading semicolon or double-colon is common; avoid sigils that are valid at the start of a shell command or a Markdown line.
3. Make triggers lowercase, hyphenated, and short
Rule: Lowercase ASCII, hyphens as separators, no more than about 12 characters after the category.
Why: Case-sensitive triggers cause misfires across keyboard layouts and are painful to say aloud in pairing sessions. Short triggers are typed; long ones get abandoned.
4. Pick one placeholder syntax and document it
Rule: Use one cursor marker and one variable style across the whole library, and document both in the README.
Why: Different expanders use different syntax for cursor position, dates, and form fields. If your team uses more than one tool, the lowest-common-denominator approach is to use obvious human-readable placeholders such as {{ticket_id}} or TODO: markers that work even when pasted raw. A snippet that expands to broken template syntax is worse than no snippet.
5. Never put secrets in a snippet
Rule: No API keys, tokens, passwords, internal hostnames you would not put in a public README, or customer data. Enforce it with a secret scanner in CI.
Why: Snippet repos get cloned widely and rarely get the scrutiny of production code. Treat the repo as semi-public inside the company.
This is also where clipboard hygiene matters on the personal side. If you copy credentials, configure your clipboard manager to skip them. In Maccy Mac, the Ignore settings (Maccy Clipboard → Settings → Ignore) let you exclude specific apps, such as your password manager, and specific pasteboard types . Many password managers also mark their copies as concealed using a community pasteboard convention (see nspasteboard.org), which well-behaved clipboard managers respect .
6. Every snippet gets a description and an owner
Rule: Each entry has a one-line description of when to use it and an owning team or person (via CODEOWNERS path, or a metadata field if your tool allows it).
Why: Ownerless snippets rot. When an incident template references a retired Slack channel, someone needs to be paged to fix it.
7. Organize files by domain, not by author
Rule: One file per domain (git.yml, incident.yml, sql.yml), never alex-snippets.yml.
Why: Author-based files make ownership personal, make deduplication impossible, and become orphaned when people change teams.
8. Review snippets like code, but lightly
Rule: Changes go through pull requests with one approver from the owning domain. Use a short checklist: trigger follows the prefix rule, no secrets, description present, no collision.
Why: Heavy process kills contribution. A one-approver rule keeps the library healthy without making a typo fix feel like a release.
9. Deprecate, don’t delete
Rule: When retiring a snippet, keep the trigger for a release or two, make it expand to a short notice pointing to its replacement, then remove it.
Why: Muscle memory outlives documentation. A trigger that silently stops working looks like a bug in the tool.
10. Test the destructive ones
Rule: Any snippet that expands to a shell command, SQL statement, or kubectl invocation must be reviewed for safety and avoid destructive defaults (no bare DELETE or rm -rf with an unset variable).
Why: Expansion is instant and you often do not read what you just inserted. Snippets with placeholders should fail loudly when the placeholder is left empty, for example by using a WHERE clause that matches nothing until it is filled in.
What’s the difference between shared snippets and personal snippets?
Shared snippets are reviewed, versioned, and owned. Personal snippets are neither, and that is fine. The convention that keeps both healthy is a namespace split: reserve one sigil or prefix for team snippets and another for personal ones, so your own experiments never collide with the shared library.
| Shared (team) | Personal | |
|---|---|---|
| Location | Git repo | Local config or app |
| Trigger style | ;cat-name |
;;name [your convention] |
| Review | PR + one approver | None |
| Secrets | Forbidden | Still discouraged |
| Lifespan | Deprecation process | Whenever |
Which tools handle shared snippets well?
No tool is universally best. These are the trade-offs that matter for teams.
| Tool | Team-sharing story | Trade-off |
|---|---|---|
| Espanso | Plain-text YAML, installable from git; works with any repo workflow | Configuration is text-first, so non-developers may find it less approachable |
| macOS Text Replacements | Syncs via iCloud for one person across devices | No team sharing; poor fit for review and ownership |
| Commercial expanders (e.g., TextExpander, Raycast snippets) | Offer team or shared-library features | Typically paid tiers; libraries live in a vendor’s system rather than your repo |
| Maccy | None by design | Excellent for recall of copied content; not a snippet manager |
If your team is mixed (developers plus support or ops), choose the tool the least technical regular user can live with, then keep the repo as the canonical source and generate or export from it where the tool allows.
Where does a clipboard manager fit in?
It fills the gap between “I’ll never need this again” and “this deserves to be a snippet.” That gap is bigger than people assume. The log line, the one-off curl command, the stack trace you are about to paste into a ticket: these are things you need for ten minutes and then not at all.
A reasonable workflow: recall with the clipboard manager, pin if you will reuse it this week, and promote to the shared repo via a pull request if it keeps coming back. In Maccy, you pin an item from the history menu (Option+P on the highlighted entry) , and the default shortcut to open the history is Shift+Command+C . Treat pins as a staging area, not a library.
One benefit of staying local: nothing you copy in this workflow leaves your Mac, which is the property that makes it safe to use with work content in the first place.
A starter template you can copy
Adapt this layout to your tool. The structure matters more than the syntax.
snippets/
├── README.md # conventions, sigils, placeholder syntax
├── CODEOWNERS # path → owning team
├── git.yml # ;git-*
├── pr.yml # ;pr-*
├── incident.yml # ;inc-*
├── sql.yml # ;sql-*
└── .github/
└── pull_request_template.md # the review checklist
A sample Espanso-style entry following the conventions above (verify syntax against the Espanso docs for your version):
matches:
- trigger: ";pr-bugfix"
replace: |
## What broke
{{what_broke}}
## Root cause
TODO
## How I tested it
TODO
# owner: platform-team (via CODEOWNERS)
# description: PR body for bug fixes
And the README review checklist:
- Trigger uses the category prefix and the agreed sigil
- No secrets, tokens, or private hostnames
- Description and owner present
- No trigger collision (run the repo’s lint script)
- Destructive commands fail safe when placeholders are empty
Common mistakes
- Treating the repo as a dumping ground. Without the ownership and deprecation rules, libraries grow until nobody trusts them.
- Over-engineering on day one. Start with five snippets and the prefix rule. Add linting when collisions actually appear.
- Expecting everyone to use the same tool. Convention lives in the repo; tooling is a per-person choice as long as the format is readable.
- Forgetting onboarding. Put “install the snippet repo” in your new-hire checklist, or the library helps only the people who already know about it.
Conclusion
The ten rules reduce to three ideas: put shared text where it can be reviewed, name things so they do not collide, and keep secrets and destructive defaults out. Everything else is detail you can tune.
If you want a lightweight place for the in-between stuff, the things you copied today that might become snippets tomorrow, Maccy is free, open source, and keeps that history on your Mac.
Question for your team: which snippet do you retype most often, and does anyone own it?
FAQ
What is a snippet convention?
A snippet convention is a written agreement on how a team names, formats, stores, reviews, and retires reusable text snippets, so a shared library stays consistent and trustworthy as it grows.
Where should a dev team store shared snippets?
In a git repository with code review and an owner file. This gives version history, accountability, and rollback, which chat pins, wikis, and personal clipboard histories do not provide.
Can you share a clipboard manager’s history across a team?
Generally no, and for privacy reasons you should not. Maccy keeps history local to your Mac . For shared, reviewed content, use a snippet library in version control instead.
How do you avoid trigger collisions in shared snippets?
Prefix every trigger with a category (for example ;pr- or ;sql-), keep a lint script in CI that rejects duplicate triggers, and reserve a different prefix for personal snippets.
Is it safe to store credentials in snippets?
No. Snippet repos spread widely and receive less scrutiny than production code. Use a password manager or secrets manager, and run a secret scanner on the repo.
