Agent Protocols is a structured framework of instructions, personas, skills, and SDLC workflows designed to optimize agentic AI coding assistants. It serves as a centralized, shared foundation to help LLM-based agents maintain code quality, architectural consistency, and professional standards across all your projects.
This framework is distributed via the dist branch and is meant to be added as
a Git submodule in your project's .agents/ directory.
Add the submodule to your project:
git submodule add -b dist https://github.com/dsj1984/agent-protocols.git .agentsRegularly update the protocols to pick up the latest personas and skills.
git submodule update --remote --merge .agents && git add .agents && git commit -m "chore: update agent-protocols"git submodule update --remote --merge .agents; git add .agents; git commit -m "chore: update agent-protocols"Add the following script to your package.json for one-command updates:
"scripts": {
"update:agents": "git submodule update --remote --merge .agents && git add .agents && git commit -m \"chore: update agent-protocols\""
}Now you can run: npm run update:agents.
- Read the Full Guide: For detailed configuring, using personas/skills, and
more, refer to the detailed protocol guide: 👉
.agents/README.md
The core of this repository lives entirely within the .agents/ directory,
which is what gets distributed to consumers.
agent-protocols/
├── .agents/ # ← Distributed to consumers via the `dist` branch
│ ├── instructions.md # Core system prompt & rules
│ ├── personas/ # Role-specific behavior constraints
│ ├── skills/ # Tech-stack-specific guardrails
│ ├── templates/ # Markdown templates
│ ├── workflows/ # SDLC automation slash commands
│ └── README.md # Detailed consumer user guide
├── .github/ # CI/CD automation for this repository
├── package.json # Tooling: markdownlint, prettier, husky
└── README.md # ← You are here
Key distinction: Only the
.agents/directory is distributed to consumers via thedistbranch. The rest of the repository contains internal tooling and CI/CD pipelines for developing the protocols.
If you are contributing to or modifying this repository:
- Node.js 20+
- npm
npm installThis also installs Husky Git hooks via the prepare script, which
configures lint-staged to auto-format and lint markdown files on every
commit.
All markdown is validated with markdownlint and formatted with prettier:
| Command | Description |
|---|---|
npm run lint |
Check all markdown for lint errors |
npm run format |
Auto-format all markdown files |
- Create a feature branch from
main. - Make your changes to files inside
.agents/. - Commit — Husky + lint-staged will automatically lint and format staged
.mdfiles before the commit is accepted. - Open a Pull Request against
main. Theci.ymlworkflow will validate your changes.
| Workflow | Trigger | Purpose |
|---|---|---|
ci.yml |
Push/PR to main |
Validates markdown, runs security scans, and syncs dist branch |
When changes to .agents/** are merged into main, the ci workflow
automatically copies the .agents/ directory contents to the dist branch if
the build passes. Consumers pinned to dist will pick up the changes on their
next submodule update.
The development of these protocols leverages an agent-first stack optimized for speed, precision, and high-context reasoning:
- LLM Engine: Google AI Ultra
- Planning Assistant: Gemini Deep Think
- Agentic IDE: Google Antigravity IDE (using Gemini & Claude models)
- Asynchronous Agent: Google Jules (experimental)
- Context Engine: Context7 (indirectly via MCP)
- Voice Interface: Wispr Flow
