Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bradygaster/squad/llms.txt

Use this file to discover all available pages before exploring further.

Skills are compressed, reusable knowledge snippets stored in .squad/skills/ or .copilot/skills/. They teach agents specific techniques, conventions, and workflows — and because they live as files in your repository, they travel with the team. Instead of re-explaining how your PR process works or what your test conventions are every session, you write a skill once and every agent has access to it. Skills reduce context window consumption. Rather than duplicating the same boilerplate across every agent charter, you extract shared patterns into a skill file and reference it. The Squad project itself consolidates over 5KB of redundant charter content into a handful of focused skills.

​
Anatomy of a Skill

Every skill is a markdown file named SKILL.md inside a named directory. The frontmatter describes the skill and how it should be matched; the body contains the actual knowledge. Here is the template: 
---
name: "{skill-name}"
description: "{what this skill teaches agents}"
domain: "{e.g., testing, api-design, error-handling}"
confidence: "low|medium|high"
source: "{how this was learned: manual, observed, earned}"
tools:
  # Optional — declare MCP tools relevant to this skill's patterns
  # - name: "{tool-name}"
  #   description: "{what this tool does}"
  #   when: "{when to use this tool}"
---

## Context
{When and why this skill applies}

## Patterns
{Specific patterns, conventions, or approaches}

## Examples
{Code examples or references}

## Anti-Patterns
{What to avoid}
Here is a real example — the agent-collaboration skill that ships with every Squad init: 
---
name: "agent-collaboration"
description: "Standard collaboration patterns for all squad agents — worktree
  awareness, decisions, cross-agent communication"
domain: "team-workflow"
confidence: "high"
source: "extracted from charter boilerplate — identical content in 18+ agent charters"
---

## Context

Every agent on the team follows identical collaboration patterns for worktree
awareness, decision recording, and cross-agent communication.

## Patterns

### Worktree Awareness
Use the `TEAM ROOT` path provided in your spawn prompt. All `.squad/` paths are
relative to this root. If TEAM ROOT is not provided, run
`git rev-parse --show-toplevel` as fallback.

### Decision Recording
After making a decision that affects other team members, write it to:
`.squad/decisions/inbox/{your-name}-{brief-slug}.md`

### Cross-Agent Communication
If you need another team member's input, say so in your response. The
coordinator will bring them in. Don't try to do work outside your domain.

## Anti-Patterns
- Don't read all agent charters — you only need your own context + decisions.md
- Don't write directly to `.squad/decisions.md` — always use the inbox drop-box
- Don't modify other agents' history.md files — that's Scribe's job
The key fields in the frontmatter:
FieldDescription
nameUnique identifier for the skill — used for loading and referencing
descriptionOne-line summary for the skill registry
domainCategory for matching (e.g., testing, security, git)
confidenceHow reliable this knowledge is: low, medium, or high
sourceHow the knowledge was acquired: manual, observed, or earned
toolsOptional MCP tools relevant to this skill’s workflows

​
Built-in Skills

Every squad init scaffolds a set of skills into .copilot/skills/. These cover the core collaboration patterns all agents need:

agent-collaboration

Worktree awareness, decision recording, and cross-agent communication patterns.

agent-conduct

Behavioral standards — response format, escalation, and reviewer protocols.

architectural-proposals

How to write and submit architectural proposals before committing to code.

architectural-review

Standards for reviewing proposals, what to approve vs. reject, and how to document decisions.

ci-validation-gates

CI/CD validation requirements — what must pass before a PR can merge.

cli-wiring

How to wire new commands into the CLI, flag conventions, and help text standards.

client-compatibility

Cross-client compatibility requirements for APIs and SDK surfaces.

distributed-mesh

Patterns for connecting multiple Squad instances in a distributed mesh topology.

git-workflow

Branching strategy, commit conventions, and merge policies.

history-hygiene

How to write useful history.md entries — what to record and what to omit.

init-mode

Scaffolding patterns and idempotency requirements for initialization flows.

model-selection

How to choose the right model for a task based on complexity and cost.

pr-lifecycle

Pull request lifecycle from branch creation through merge, including review gates.

protected-files

Which files agents must never modify without explicit human approval.

release-process

Versioning, changelog, and release gating standards.

reskill

How to update or replace a skill when the underlying pattern changes.

reviewer-protocol

Reviewer authority, rejection lockout, and revision handoff procedures.

secret-handling

How to handle secrets, tokens, and credentials — never commit, always rotate.

security-review

Security review checklist and what triggers a mandatory security audit.

squad-conventions

Project-wide conventions — naming, file layout, and inter-agent communication.

github-multi-account

Patterns for managing multiple GitHub accounts and SSH identities in multi-user or CI environments.

windows-compatibility

Windows-specific path handling, shell conventions, and cross-platform compatibility requirements.

​
Creating a Custom Skill

1

Create the skill directory

Create a named directory under .copilot/skills/ (available to all agents) or .squad/skills/ (available to squad-scoped agents):
mkdir -p .copilot/skills/my-test-conventions
2

Write the SKILL.md

Create the skill file with frontmatter and content sections:
---
name: "my-test-conventions"
description: "Testing conventions for this project — framework, patterns, file layout"
domain: "testing"
confidence: "high"
source: "manual"
---

## Context

This project uses Vitest with a collocated test file pattern. Tests live
alongside source files, not in a separate `tests/` directory.

## Patterns

- Test files are named `{module}.test.ts` in the same directory as the module
- Use `describe` blocks to group related tests
- Mock external I/O with `vi.mock()` — never hit real APIs in unit tests
- Minimum 80% branch coverage for new modules

## Examples

```typescript
// src/parser.ts
export function parseRoute(input: string): Route { ... }

// src/parser.test.ts (collocated)
import { parseRoute } from './parser.js';
describe('parseRoute', () => { ... });

​
Anti-Patterns

  • Don’t write tests to tests/ — collocated only
  • Don’t import from dist/ in tests — always import from src/
</Step>
<Step title="Commit the skill">
Add the skill file to version control so it travels with the team:

```bash
git add .copilot/skills/my-test-conventions/SKILL.md
git commit -m "Add test conventions skill"

​
Loading Skills

The SDK’s SkillRegistry handles skill loading, matching, and injection. Skills are loaded from their directories at session startup and matched to tasks by keyword triggers and agent role affinity. 
import { loadSkillsFromDirectory, SkillRegistry } from '@bradygaster/squad-sdk';

const registry = new SkillRegistry();

// Load all skills from a directory
const skills = await loadSkillsFromDirectory('.copilot/skills');
for (const skill of skills) {
  registry.registerSkill(skill);
}

// Match skills relevant to a task
const matches = registry.matchSkills(
  'write tests for the auth module',
  'tester'
);

// Get skill content for injection
const content = registry.loadSkill('my-test-conventions');
Scoring works as follows: each trigger keyword found in the task text adds +0.5 to the score (capped at 0.7), and a matching agent role adds +0.3. Skills with a score above 0 are returned, sorted by score descending. Skills in .copilot/skills/ are available to all agents. Skills in .squad/skills/ are squad-scoped. Both directories are scanned at session startup.

​
The squad nap Command

squad nap performs context hygiene — it compresses accumulated session context, prunes stale entries, and archives skills that have been superseded. 
# Standard compression — prune obvious redundancy
squad nap

# Aggressive compression — collapse similar patterns, reduce verbosity
squad nap --deep

# Preview what would change without modifying any files
squad nap --dry-run
Use squad nap after long sessions or before starting a major new feature. It keeps history files focused and prevents skill directories from accumulating outdated entries that could confuse agents.
Commit your skills directory. Skills are how your team’s institutional knowledge accumulates across contributors and sessions. When a new developer joins the project and runs squad init, they immediately have access to every convention, pattern, and workflow the team has codified — without anyone needing to explain it.

Build docs developers (and LLMs) love

Get started for freeTalk to us