Production-grade engineering skills and agent personas for GitHub Copilot.
Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. This repo packages them so GitHub Copilot follows them consistently across every phase of development.
.github/
prompts/ → Slash commands as Copilot prompt files (/spec, /plan, /build, ...)
skills/ → Skills auto-discovered by Copilot
agents/ → Agent personas (*.agent.md) auto-discovered by Copilot
workflows/ → CI to validate skill content
references/ → Supplementary checklists (testing, security, performance, a11y)
docs/ → Copilot setup guide and skill anatomy
scripts/ → Skill validator
GitHub Copilot discovers skills from .github/skills/ and personas from .github/agents/ (files must be named *.agent.md).
This repo is pre-configured. Skills live in .github/skills/ and personas in .github/agents/, so Copilot picks them up automatically when you open the repo.
To use these skills in another repo, see docs/copilot-setup.md.
Every persona owns one SDLC phase and one output artifact. Each phase locks its decisions before the next phase begins — preventing late re-litigation and producing a clean handoff contract.
flowchart LR
subgraph Define
D[/discover<br/>discovery-lead/] --> S[/spec<br/>product-planner/]
end
subgraph Design
S --> AI[/ai-architect<br/>ai-application-architect/]
AI --> A[/architect<br/>azure-architect/]
S -.non-AI.-> A
end
subgraph Plan
A --> P[/plan<br/>sprint-planner/]
end
subgraph Build
P --> B[/build<br/>backend-engineer<br/>frontend-engineer/]
end
subgraph Verify
B --> T[/test<br/>test-engineer/]
B --> DB[/debug<br/>debugger/]
B --> PF[/perf<br/>performance-engineer/]
end
subgraph Review
T --> R[/review<br/>code-reviewer/]
DB --> R
PF --> R
R --> CS[/code-simplify/]
R --> DC[/docs<br/>docs-author/]
end
subgraph Evolve
CS --> M[/migrate<br/>migrator/]
end
subgraph Release
DC --> SH[/ship<br/>fan-out + launch/]
M --> SH
end
classDef define fill:#dbeafe,stroke:#1e40af
classDef design fill:#dcfce7,stroke:#15803d
classDef plan fill:#fef3c7,stroke:#a16207
classDef build fill:#fee2e2,stroke:#b91c1c
classDef verify fill:#fae8ff,stroke:#86198f
classDef review fill:#e0e7ff,stroke:#3730a3
classDef evolve fill:#fed7aa,stroke:#c2410c
classDef release fill:#d1fae5,stroke:#047857
class D,S define
class AI,A design
class P plan
class B build
class T,DB,PF verify
class R,CS,DC review
class M evolve
class SH release
Forward pipeline is steps 1–8. Cross-cutting personas (marked ✱) are reactive — invoked any time after Step 5.
| Step | SDLC Phase | Persona | Slash | Locked artifact | Branch prefix |
|---|---|---|---|---|---|
| 1 | Discover | discovery-lead |
/discover |
specs/DISCOVERY.md |
discover/ |
| 2 | Define | product-planner |
/spec |
specs/PRODUCT.md |
spec/ |
| 3a | Design (AI shape) | ai-application-architect |
— | specs/AI-ARCHITECTURE.md (AI-driven products only) |
arch/ai-* |
| 3b | Design (Azure) | azure-architect |
/architect |
specs/ARCHITECTURE.md + ≤8 recommended skills |
arch/ |
| 4 | Plan | sprint-planner |
/plan |
specs/SPRINTS.md (1–2 JIT skills per sprint) |
plan/ |
| 5 | Build | backend-engineer |
/build |
One-sprint PR (API contracts locked inside sprint) | backend/sprint-N-* |
| 5′ | Build (UI variant) | frontend-engineer |
/build |
One-sprint UI PR | ui/sprint-N-* |
| 6 | Verify | test-engineer |
/test |
Strengthened test suite | test/ |
| 7 | Review | code-reviewer |
/review |
Five-axis review on PR | — |
| 8 | Release | fan-out: code-reviewer ∥ security-auditor ∥ test-engineer |
/ship |
Release | — |
| ✱ | Verify (bugs) | debugger |
/debug |
Fix + regression test | fix/ |
| ✱ | Verify (perf) | performance-engineer |
/perf |
Baseline + optimization + delta | perf/ |
| ✱ | Review (simplify) | — | /code-simplify |
Refactor PR | simplify/ |
| ✱ | Review (docs) | docs-author |
/docs |
User docs / ADRs | docs/ |
| ✱ | Evolve | migrator |
/migrate |
MIGRATION.md + phased PRs |
migrate/*-phase-N |
Each persona's
.agent.mdopens with a Pipeline position block showing its step number, prev, and next — so the agent itself knows where it sits in the pipeline.
Every persona reads and writes specs/PIPELINE.md in your project repo. It tracks Current step, per-step status (⬜ pending · 🟡 in progress · ✅ done), PR numbers, sprint progress, and handoff notes.
- First persona to run bootstraps it from
.github/templates/PIPELINE.md(in this repo). - On handoff, the persona updates its row, advances Current step, and appends a handoff note for the next persona.
- Cross-cutting personas log to a separate Cross-cutting activity table and don't move the forward pipeline.
Result: "Where are we?" is a one-line read, not a forensic dig through PRs. See .github/copilot-instructions.md → Pipeline tracker protocol for the full rules.
The architect recommends up to 8 upstream skills. The sprint-planner schedules 1–2 per sprint. The backend-engineer installs them at the start of that sprint via pwsh scripts/add-upstream-skill.ps1 <skill-id>. The full microsoft/skills catalog (126 skills) is never loaded at once.
This repo is pre-configured. Skills live in .github/skills/ and personas in .github/agents/, so Copilot picks them up automatically when you open the repo.
14 prompt files in .github/prompts/ map to the development lifecycle. Invoke them in Copilot Chat with /<name>.
| Command | Phase | What it does | Activates |
|---|---|---|---|
/discover |
Discovery | Interview the user, find the riskiest assumption (DISCOVERY.md) | discovery-lead persona |
/spec |
Define | Define what to build (PRODUCT.md) | product-planner persona |
/architect |
Design | Produce Azure architecture from a spec (ARCHITECTURE.md) | azure-architect persona |
/plan |
Plan | Slice product + architecture into sprints (SPRINTS.md) | sprint-planner persona |
/build |
Implement | Implement the next sprint (API contracts locked inside the sprint) | backend-engineer persona |
/test |
Verify | Strengthen test strategy or coverage | test-engineer persona |
/debug |
Verify | Reproduce → isolate → fix → regression test | debugger persona |
/perf |
Verify | Measure → profile → optimize → re-measure | performance-engineer persona |
/review |
Review | Five-axis code review | code-reviewer persona |
/code-simplify |
Review | Surgical complexity reduction | code-simplification skill |
/docs |
Review | User docs, references, ADRs | docs-author persona |
/migrate |
Evolve | Phased migration or deprecation | migrator persona |
/ship |
Release | Pre-launch fan-out + deploy | code-reviewer ∥ security-auditor ∥ test-engineer, then shipping-and-launch |
Personas are switched via the agent dropdown in VS Code Chat, or /agent <name> in the Copilot CLI. They are not invoked with @name — that syntax is reserved for built-in chat participants.
Most slash commands above automatically switch to the right persona for you.
22 in-house lifecycle skills, 8 Microsoft / Azure domain skills, and the using-agent-skills meta-skill. Several of the Microsoft / Azure skills are imported or adapted from microsoft/skills. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables.
Pulling more upstream skills: run
pwsh scripts/add-upstream-skill.ps1 <skill-id>. The script shallow-clones microsoft/skills, copies the named skill, and tells you whether to add it to the validator's exemption list. Recommended pattern: load skills just-in-time per sprint, not all upfront, to avoid context rot.
| Skill | What It Does |
|---|---|
| using-agent-skills | Maps incoming work to the right skill workflow |
| Skill | What It Does |
|---|---|
| interview-me | One-question-at-a-time interview until ~95% confidence |
| idea-refine | Structured divergent/convergent thinking |
| spec-driven-development | Write a PRD before any code |
| Skill | What It Does |
|---|---|
| planning-and-task-breakdown | Decompose specs into small, verifiable tasks |
| Skill | What It Does |
|---|---|
| incremental-implementation | Thin vertical slices — implement, test, verify, commit |
| test-driven-development | Red-Green-Refactor, test pyramid, DAMP over DRY |
| context-engineering | Feed agents the right information at the right time |
| source-driven-development | Ground every decision in official documentation |
| doubt-driven-development | Adversarial fresh-context review of in-flight decisions |
| frontend-ui-engineering | Component architecture, design systems, WCAG 2.1 AA |
| api-and-interface-design | Contract-first design, Hyrum's Law, error semantics |
| Skill | What It Does |
|---|---|
| browser-testing-with-devtools | Chrome DevTools MCP for live runtime data |
| debugging-and-error-recovery | Five-step triage: reproduce, localize, reduce, fix, guard |
| Skill | What It Does |
|---|---|
| code-review-and-quality | Five-axis review, change sizing, severity labels |
| code-simplification | Chesterton's Fence, Rule of 500, preserve behavior |
| security-and-hardening | OWASP Top 10 prevention, auth patterns, secrets management |
| performance-optimization | Measure-first — Core Web Vitals, profiling, bundle analysis |
| Skill | What It Does |
|---|---|
| git-workflow-and-versioning | Trunk-based development, atomic commits |
| ci-cd-and-automation | Shift Left, feature flags, quality gate pipelines |
| deprecation-and-migration | Code-as-liability mindset, migration patterns |
| documentation-and-adrs | Architecture Decision Records, API docs |
| shipping-and-launch | Pre-launch checklists, staged rollouts, rollback |
| Skill | What It Does |
|---|---|
| cloud-solution-architect | 10 Azure design principles, 6 architecture styles, 44 cloud design patterns, WAF review workflow |
| azure-architecture-diagrams | Paired .drawio + PNG using Microsoft's official V23 + Fabric icon bundles (no stale 2019 stencils) |
| azure-content-understanding | azure-ai-contentunderstanding SDK — prebuilt + custom analyzers across documents, images, audio, video |
| microsoft-docs | Primary lookup channel for Foundry, Azure SDKs, and Microsoft Learn content |
| entra-agent-id | OAuth2-capable AI agent identities via Microsoft Graph beta (preview) |
| mcp-builder | Build high-quality MCP servers (Python, TS, .NET) for LLM tool integration |
| pptx | Production-grade PowerPoint decks with bold layouts, content-informed palettes, QA loop |
| skill-creator | Author or update agent-skills following this repo's conventions |
Pre-configured specialist personas for targeted reviews:
| Agent | Role | Perspective |
|---|---|---|
| code-reviewer | Reviewer | Five-axis code review |
| test-engineer | Verifier | Test strategy, coverage, Prove-It pattern |
| security-auditor | Reviewer | Vulnerability detection, threat modeling, OWASP |
| discovery-lead | Discovery | Interviews, idea refinement → specs/DISCOVERY.md |
| product-planner | Definer | Briefs → ambitious-but-bounded specs/PRODUCT.md |
| ai-application-architect | AI Architect | Spec → specs/AI-ARCHITECTURE.md (corpus, retrieval, agent + tool surface, grounding, model selection, evals, RAI) |
| azure-architect | Architect | Spec → specs/ARCHITECTURE.md + recommended skills |
| sprint-planner | Planner | Spec + arch → specs/SPRINTS.md with JIT skill loading |
| backend-engineer | Builder | Executes one sprint with JIT skills + TDD; locks API/interface contracts inside the sprint |
| frontend-engineer | Builder | UI-heavy build variant (a11y + real-browser tests) |
| debugger | Fixer | Reproduce → isolate → minimal fix + regression test |
| performance-engineer | Optimizer | Measure → profile → optimize → re-measure |
| docs-author | Writer | User docs, references, ADRs |
| migrator | Evolver | Phased migrations + deprecations with rollback per phase |
| Reference | Covers |
|---|---|
| testing-patterns.md | Test structure, naming, mocking, anti-patterns |
| security-checklist.md | Pre-commit checks, auth, input validation, OWASP Top 10 |
| performance-checklist.md | Core Web Vitals targets, frontend/backend checklists |
| accessibility-checklist.md | Keyboard nav, screen readers, ARIA, testing tools |
Every skill follows a consistent anatomy:
SKILL.md
├─ Frontmatter (name, description with "Use when…" triggers)
├─ Overview → What this skill does
├─ When to Use → Triggering conditions
├─ Process → Step-by-step workflow
├─ Rationalizations → Excuses + rebuttals
├─ Red Flags → Signs something's wrong
└─ Verification → Evidence requirements
Key design choices:
- Process, not prose. Skills are workflows agents follow, not reference docs.
- Anti-rationalization. Every skill includes a table of common excuses with counter-arguments.
- Verification is non-negotiable. Every skill ends with evidence requirements.
- Progressive disclosure. Supporting references load only when needed.
See CONTRIBUTING.md and docs/skill-anatomy.md.
MIT. Originally derived from addyosmani/agent-skills.