Workspace Baseline

A curated library of reusable GitHub Copilot markdown files — instructions, agents, prompts, and skills — for bootstrapping and accelerating new coding projects.

This is a knowledge base, not an application. Copy what you need into your project's .github/ folder, customize to fit, and move on. Files marked 🏠 are home-grown; files marked 🔗 are sourced/inspired from awesome-copilot.

---

Quick Start

1.  Open this workspace alongside your target project
2.  Ask Copilot to scaffold a copilot-instructions.md (the copilot-instructions-blueprint-generator skill activates automatically)
3.  Cherry-pick instructions, agents, prompts, and skills you need
4.  Customize freely — downstream divergence is expected

---

How GitHub Copilot Uses These Files

VS Code and the Copilot coding agent load customization files from your repository. Each type has a distinct role and loading model — references current as of mid-2026 (VS Code custom instructions docs, GitHub Copilot custom instructions docs, Copilot coding agent AGENTS.md support).

Type	Path	Loaded	Purpose
copilot-instructions.md	.github/copilot-instructions.md	Every chat request	Project-wide context: tech stack, hard rules, MCP tool routing
AGENTS.md	AGENTS.md (root, optionally nested in subfolders)	Every request; nested files merge for matching paths	Cross-tool standard (Copilot coding agent, Claude, Codex, etc.) — describe the project so any agent can be productive
Instructions	.github/instructions/*.instructions.md	Auto, by applyTo glob	Coding standards applied silently when editing matching files. Multiple matching files are merged with no guaranteed order — avoid conflicting rules
Agents	.github/agents/*.agent.md	On demand @agent	Interactive persona with scoped expertise, tools, and (optionally) model for a task category
Prompts	.github/prompts/*.prompt.md	On demand /prompt	One-shot workflow starter — a scripted playbook for a task
Skills	.github/skills/*/SKILL.md	Auto-discovered, loaded on relevance	Bundled domain knowledge, scripts, and assets — progressively loaded only when the prompt matches
Hooks (Preview)	.github/hooks/*.json or agent frontmatter	At lifecycle events	Deterministic shell commands at SessionStart, PreToolUse, PostToolUse, Stop, etc. — gate, audit, automate. See VS Code hooks (Preview)

Manage all of these in VS Code via Chat: Open Customizations (Command Palette).

When to use which

flowchart TD
    A[I need Copilot to...] --> B{Apply rules automatically\nwhen editing files?}
    B -- Yes --> C[✅ Instruction]
    B -- No --> D{Have an ongoing conversation\nwith specialized expertise?}
    D -- Yes --> E[✅ Agent]
    D -- No --> F{Run a repeatable\nworkflow or scaffold?}
    F -- Yes --> G[✅ Prompt]
    F -- No --> H{Bundle reference docs\nor assets for reuse?}
    H -- Yes --> I[✅ Skill]
    H -- No --> J{Run a deterministic check\nat a session lifecycle event?}
    J -- Yes --> K[✅ Hook]
    J -- No --> L[Add to copilot-instructions.md or AGENTS.md]

Loading

Context budget tips

• copilot-instructions.md, AGENTS.md, and applyTo: '**' instructions load on every request — keep them lean
• Agents and prompts only load when invoked — put specialized knowledge there
• Skills are progressively loaded by relevance — ideal for large reference material
• Hooks are still Preview — config schema may shift before stable release
• If Copilot starts ignoring your rules, you're probably loading too much context

---

Repository Structure

instructions/       Coding standards and conventions per technology
agents/             Specialized AI personas for development tasks
prompts/            Reusable workflow triggers and generators
skills/             Bundled domain knowledge with scripts and assets
hooks/              VS Code agent hooks for session lifecycle events
docs/               Architecture decisions, prompt-craft notes, spike research
.github/workflows/  CI/CD: weekly upstream refresh + PR template validation
.github/scripts/    Shell scripts powering the workflows
.github/upstream-exclude  Files intentionally different from upstream (skip list)

Root folders are the authoritative library. Copy files into your project's .github/ folder to activate them.

---

Automation

Weekly Upstream Refresh

The upstream-refresh workflow runs every Monday at 06:00 UTC (and on manual dispatch) to sync sourced (🔗) files from awesome-copilot. It creates a PR with any changes found. Files listed in .github/upstream-exclude are intentionally skipped.

What gets auto-applied:

• Updates to existing 🔗-sourced files (verbatim copy from upstream HEAD)
• New hooks/* and skills/* directories that don't exist locally yet
• README catalog table additions for newly imported items

What gets surfaced but NOT auto-applied:

• ⚠️ Removed/renamed upstream files — the sourced path no longer exists upstream; the PR body flags it for manual curation (rename, exclude, or remove).
• 📋 Curation digest — a count of agents/, instructions/, skills/, and hooks/ items available upstream but not yet in our catalog. New .agent.md and .instructions.md files are not auto-imported (the upstream catalog has 200+ agents and 180+ instructions; bulk import would balloon the catalog). Maintainers cherry-pick from the digest.

Manual trigger: Actions tab → "Upstream Refresh" → "Run workflow". Enable dry_run to preview changes in the job summary without creating a PR.

PR Template Validation

The pr-checks workflow runs on every PR that touches template directories. It validates:

• Naming conventions: {purpose}.agent.md, {technology}.instructions.md, {workflow}.prompt.md
• Frontmatter: Required fields (description/applyTo for instructions, description/name for agents)
• Content quality: No empty files, no frontmatter-only templates

Upstream refresh PRs auto-merge after validation passes.

---

Featured Prompts 🏠

These are the home-grown workflow prompts that drive day-to-day development:

Prompt	Invoke	What it does
analyze-wsfc-diagnostics	/analyze-wsfc-diagnostics	Launches an indexed WSFC diagnostic analysis session for extracted Get-ClusterDiagnosticInfo bundles.
workon.myidea	/workon.myidea	Structured workflow for bug fixes, small features, and refactors. Routes large work to workon.myspec.
workon.myspec	/workon.myspec	Coordinator for spec-driven feature development. Depends on SpecKit agents and templates.
validate.myprompt	/validate.myprompt	Dispatches three parallel specialist reviews (critical-thinking, code-review, prompt-builder) of a workspace template file (.prompt.md, .agent.md, .instructions.md, SKILL.md), then synthesizes a prioritized action plan.

---

Catalog

Agents (17)

Specialized AI personas invoked via @agent-name in Copilot Chat.

Agent	Description	Source
adr-generator	Creates Architecture Decision Records with structured formatting	🔗
code-review	Code quality validator and compliance checker with fresh context analysis	🏠
context7	Expert in latest library versions using up-to-date documentation via Context7 MCP	🔗
critical-thinking	Challenges assumptions to ensure the best possible solution	🔗
debug-mode	Debug your application to find and fix a bug	🏠
mcp-m365-agent-expert	Builds MCP-based declarative agents for Microsoft 365 Copilot	🔗
playwright-tester	Testing mode for Playwright tests	🔗
prompt-builder	Expert prompt engineering and validation system (microsoft/edge-ai)	🔗
research-technical-spike	Systematically research and validate technical spike documents	🔗
se-technical-writer	Technical writing specialist for developer documentation and tutorials	🔗
tdd-red	Write failing tests first from GitHub issue context	🔗
tdd-green	Implement minimal code to make failing tests pass	🔗
tdd-refactor	Improve quality and security while keeping tests green	🔗
Thinking-Beast-Mode	Transcendent coding agent with quantum cognitive architecture and adversarial intelligence	🔗
Ultimate-Transparent-Thinking-Beast-Mode	Ultimate fusion mode with mandatory crystal-clear transparency of reasoning	🔗
workflow-coordinator	Orchestrate 6-phase lightweight development workflow with MCP state tracking	🏠
wsfc-diagnostics	Analyze WSFC diagnostic bundles with progressive triage and RCA workflows	🏠

Prompts (4)

Workflow starters invoked via /prompt-name in Copilot Chat.

Prompt	Description	Source
analyze-wsfc-diagnostics	Guided WSFC diagnostics workflow for extracted Get-ClusterDiagnosticInfo bundles	🏠
workon.myidea	Structured workflow for bug fixes, small features, and refactors	🏠
workon.myspec	Coordinator for spec-driven feature development. Depends on SpecKit.	🏠
validate.myprompt	Parallel specialist review of a workspace template file with synthesized action plan	🏠

Instructions (31)

Coding standards Copilot auto-loads based on applyTo glob patterns.

Instruction	Applies to	Description	Source
agent-skills	**/SKILL.md	Guidelines for creating Agent Skills	🔗
agents	**/*.agent.md	Guidelines for creating custom agent files	🔗
ai-prompt-engineering-safety-best-practices	**	Prompt engineering, safety, bias mitigation	🔗
alpinejs-chartjs-dashboard	**/*.{js,html}	Alpine.js 3.x + Chart.js 4.x dashboard patterns	🏠
code-review-generic	**	Generic code review checklist	🔗
containerization-docker-best-practices	Dockerfile globs	Multi-stage builds, security scanning, runtime	🔗
context-engineering	**	Structuring code to maximize Copilot effectiveness	🔗
copilot-sdk-python	**.py	Building Python apps with GitHub Copilot SDK	🔗
copilot-thought-logging	**	Trace Copilot's reasoning process	🔗
declarative-agents-microsoft365	**.json, **.ts	M365 Copilot declarative agents (schema v1.5)	🔗
html-css-style-color-guide	**/*.html, **/*.css	Accessible color and styling rules	🔗
instructions	**/*.instructions.md	Meta: how to author instruction files	🔗
invokebuild-tasks	**/*.build.ps1	InvokeBuild task patterns for PowerShell	🏠
javascript-es6-browser	**/*.{js,html}	JavaScript ES6+ browser patterns with esbuild	🏠
markdown-documentation	docs/**/*.md	Markdown standards, cross-references, Mermaid	🏠
mcp-m365-copilot	MCP/agent globs	MCP-based agents and API plugins for M365	🔗
microsoft-graph-sdk	**/*.ps1	Microsoft Graph PowerShell SDK 2.0+ patterns	🏠
nodejs-javascript-vitest	**/*.js	Node.js + JavaScript with Vitest testing	🔗
performance-optimization	*	Cross-stack performance optimization	🔗
playwright-typescript	**	Playwright TypeScript test patterns	🔗
powershell-7	**/*.ps1	PowerShell 7.5+ coding standards	🏠
powershell-pester-5	**/*.Tests.ps1	Pester 5 testing best practices	🔗
prompt	**/*.prompt.md	Meta: how to author prompt files	🔗
security-and-owasp	**	Secure coding based on OWASP Top 10	🔗
self-explanatory-code-commenting	**	Write self-documenting code, comment only "why"	🔗
spec-driven-workflow-v1	**	Structured spec → plan → implement workflow	🔗
sqlite-schema-queries	**/*.sql	SQLite schema design and query patterns	🏠
typescript-mcp-server	**/*.ts, **/*.js	Building MCP servers with TypeScript SDK	🔗
update-docs-on-code-change	code + docs globs	Auto-update docs when code changes	🔗
versioning-management	**/package.json etc.	SemVer and release automation rules	🏠
vscode-hooks	.github/hooks/** etc.	VS Code agent hooks lifecycle, schemas, and gotchas	🏠

Skills (24)

Domain knowledge packages with embedded scripts, references, or assets.

Skill	Description	Source
agentic-eval	Evaluator-optimizer pipelines, self-critique loops, LLM-as-judge	🔗
architecture-blueprint-generator	Analyzes codebases to create detailed architectural documentation	🔗
chrome-devtools	Browser automation, debugging, and performance via Chrome DevTools MCP	🔗
copilot-instructions-blueprint-generator	Scaffolds a copilot-instructions.md tailored to your tech stack	🔗
copilot-sdk	Build agentic apps with GitHub Copilot SDK, MCP servers, custom agents	🔗
create-agentsmd	Generates an AGENTS.md file for a repository	🔗
create-technical-spike	Creates time-boxed spike documents for critical technical decisions	🔗
documentation-writer	Diátaxis expert for creating structured technical documentation	🔗
github-copilot-starter	Sets up complete GitHub Copilot configuration for a new project	🔗
make-skill-template	Scaffold new SKILL.md files with proper structure	🔗
mcp-cli	Interface with MCP servers from the command line	🔗
microsoft-code-reference	Look up Microsoft API references and verify SDK code	🔗
microsoft-skill-creator	Create agent skills for any Microsoft technology via Learn MCP	🔗
multi-stage-dockerfile	Creates optimized multi-stage Dockerfiles for any language	🔗
playwright-generate-test	Generates Playwright tests from scenarios using Playwright MCP	🔗
powershell-7	PowerShell 7 best practices, performance, cross-platform, Pester	🏠
prd	Generate Product Requirements Documents with user stories and risk analysis	🔗
pytest-coverage	Runs pytest with coverage analysis and drives toward 100%	🔗
python-mcp-server-generator	Scaffolds a complete MCP server project in Python	🔗
refactor	Surgical code refactoring — extract, rename, decompose, improve types	🔗
technology-stack-blueprint-generator	Detects and documents technology stacks with version info and diagrams	🔗
typescript-mcp-server-generator	Scaffolds a complete MCP server project in TypeScript	🔗
webapp-testing	Test local web apps with Playwright — screenshots, logs, UI verification	🔗
wsfc-diagnostics	Domain knowledge for analyzing Windows Server Failover Clustering diagnostics	🏠

Hooks (6)

VS Code agent hooks for session lifecycle events (preToolUse, sessionStart, sessionEnd, onPrompt).

Hook	Description	Source
dependency-license-checker	Scans new dependencies for copyleft/restrictive license compliance at session end	🔗
governance-audit	Real-time threat detection and audit logging — scans prompts for dangerous patterns	🔗
secrets-scanner	Scans modified files for leaked secrets, credentials, and API keys at session end	🔗
session-auto-commit	Auto-commits and pushes changes when a coding agent session ends	🔗
session-logger	Comprehensive session logging — tracks starts, ends, and prompts for audit trails	🔗
tool-guardian	Blocks dangerous tool operations — force pushes, database drops, destructive commands	🔗

---

SpecKit Integration

The workon.myspec prompt depends on SpecKit, which provides spec-driven development workflows with agents and templates for taking features from idea → spec → plan → tasks → implementation. SpecKit files (.specify/, speckit.* agents/prompts) are included in this repo as a dependency.

---

Tech Stack Coverage

Templates are built around these technologies, though many are language-agnostic:

Stack	Technologies
PowerShell	PowerShell 7.5+, InvokeBuild, Pester 5.7+, Microsoft Graph SDK
JavaScript	ES6+, Alpine.js 3.x, Chart.js 4.x, esbuild
TypeScript	Vitest, Playwright, MCP Server SDK
Infrastructure	Docker (multi-stage builds, Python/Node isolation)
Data	SQLite (Microsoft.Data.Sqlite, sql.js WASM)
Microsoft 365	Graph SDK, Declarative Agents, MCP, Copilot SDK
Windows HA	Windows Server Failover Clustering diagnostics, Get-ClusterDiagnosticInfo, Get-ClusterLog

---

MCP Tools

Copilot agents extend their reach via MCP (Model Context Protocol) servers. The copilot-instructions.md includes a routing table so agents know which tool to call. The MCP specification is at v2 (2026); the production-recommended TypeScript SDK is v1.x (typescript-sdk).

Need	MCP Tool
Microsoft / .NET / Azure / Graph patterns	mcp_microsoftdocs_microsoft_docs_search (Microsoft Learn MCP)
Library/framework docs (any ecosystem)	mcp_context7_resolve-library-id → mcp_context7_get-library-docs
Current versions / live web search	mcp_brave-search_brave_web_search (or any web-search MCP your team standardizes on — VS Code's built-in #fetch and #websearch tools work too)
Discover community MD files	mcp_awesome-copil_search_instructions / mcp_awesome-copil_search_agents
Complex reasoning	mcp_sequential-th_sequentialthinking (min 3 thoughts)

Tool names follow the mcp_<server>_<tool> convention used by VS Code and the Copilot coding agent. Substitute the server names registered in your environment.

---

Docs

Area	Path	Contents
ADRs	docs/adr/	Architecture Decision Records
Architecture	docs/architecture/	System design decisions and patterns
Development	docs/development/	Contributing, workflows, and iteration logs
Prompt Craft	docs/prompt-craft/	Refined prompt techniques and lessons learned
Spikes	docs/spikes/	Technical spike research documents

---

Conventions

Rule	Detail
Instruction frontmatter	Requires description and applyTo
Agent frontmatter	Requires description and name
Naming	{technology}.instructions.md, {purpose}.agent.md, {workflow}.prompt.md
Root is authoritative	All templates originate in root folders; .github/ draws from root
Downstream divergence	Expected and encouraged — no sync enforcement

Full authoring standards: .github/copilot-instructions.md

---

Attribution

Templates marked 🔗 are sourced from or inspired by github/awesome-copilot, a community-curated collection. All sourced templates are reviewed and adapted to be project- and tech-agnostic.

License

Personal template library. See individual files for attribution where sourced from community resources.