GitHub Copilot Tooling Guide

April 26, 2026 · View on GitHub

This project includes comprehensive GitHub Copilot customization to accelerate development, maintain quality, and enforce project conventions. This guide documents the custom agents, skills, instructions, and workflows that enhance your Copilot experience.

Overview
Directory Structure
Copilot Agent Plugin
Copilot Instructions
Custom Agents
Skills
Chat Modes
Prompts
How to Use Custom Agents
Creating Your Own Agents
Best Practices

Overview

The .github directory contains a rich ecosystem of Copilot customizations designed specifically for this monorepo:

Custom Instructions - Global and scoped rules for code generation
Agents - Specialized AI assistants for specific tasks
Skills - Reusable workflows and procedures
Chat Modes - Enhanced conversation modes
Prompts - Validation and quality check templates

These tools work together to ensure code quality, consistency, and adherence to project conventions while maximizing developer productivity.

Directory Structure

.github/
├── copilot-instructions.md          # Main Copilot instructions file
├── instructions/                     # Scoped instruction files
│   ├── 00-repo-basics.instructions.md
│   ├── react-spa-router.instructions.md
│   ├── testing-and-quality.instructions.md
│   └── ui-and-accessibility.instructions.md
├── agents/                           # Custom Copilot agents
│   ├── brightsign-deploy.agent.md
│   ├── custom-agent-foundry.agent.md
│   ├── instructions-detox.agent.md
│   ├── requirements-planner.agent.md
│   ├── shadcnui-component-reviewer.agent.md
│   ├── signage-architect.agent.md
│   ├── signage-design-brief-writer.agent.md
│   └── ui-designer.agent.md
├── chatmodes/                        # Custom chat modes
│   └── enhanced-gpt4.1.chatmode.md
├── prompts/                          # Reusable prompts
│   ├── code-health.prompt.md
│   ├── commit.prompt.md
│   ├── create-signage-placeholders.prompt.md
│   ├── help.prompt.md
│   ├── implement-next.prompt.md
│   ├── mcp-check.prompt.md
│   ├── pr-desc.prompt.md
│   └── validate-client.prompt.md
└── workflows/                        # GitHub Actions workflows
    ├── ci.yml
    └── deploy.yml

skills/                               # Canonical portable SKILL.md source
├── brightsign-debug/
├── brightsign-deploy-local/
├── brightsign-fleet-deploy/
├── brightsign-package/
├── brightsign-runtime/
├── brightsign-signage-build/
├── chrome-devtools-webapp-debug/
├── instructions-detox/
├── player-discovery-export/
├── player-discovery-probe/
├── player-discovery-scan/
├── remotion-demo-video/
├── shadcnui-component-review/
├── signage-animation-system/
├── signage-content-fallbacks/
├── signage-data-refresh-patterns/
├── signage-distance-legibility/
├── signage-layout-system/
├── signage-menu-board/
├── signage-performance-budget/
├── signage-placeholder-images/
├── signage-safe-layout/
└── signage-state-machine/

skills/ is the source of truth. Run pnpm sync:skills to regenerate .github/skills/ for GitHub Copilot-native discovery, and pnpm check:skills to verify the mirror before pushing.

Copilot Agent Plugin

Preview feature — Copilot agent plugins currently require VS Code Insiders. This may change as the feature matures.

In addition to the workspace-level agents and skills above, WallRun packages a Copilot agent plugin at copilot-plugins/wallrun-signage/. This bundles a curated subset of skills and agents into a standalone package that can be installed into any VS Code workspace.

What's in the plugin

14 curated skills — signage layout, animation, menu boards, distance legibility, BrightSign runtime/packaging/deploy/debug, and more
2 agents — signage-architect (builds premium signage screens) and wallrun-deploy (deployment triage and preflight)
Hooks — advisory preflight check (experimental)
MCP config — plugin-scoped MCP configuration for BrightSign docs

When to use the plugin vs. workspace agents

Mechanism	Scope	Best for
Workspace agents (`.github/agents/`)	This repo	Working inside the WallRun monorepo
Copilot plugin (`copilot-plugins/wallrun-signage/`)	Any workspace	Building signage in your own project
Portable skills (`npx skills add`)	Any workspace	Only the skill workflows, no agents

Installation

See the Plugin Installation Guide for step-by-step instructions, or the Plugin README for the full reference.

Building and maintaining the plugin

The plugin is generated from source skills and agents:

pnpm plugin:copilot:build   # Generate copilot-plugins/wallrun-signage/
pnpm plugin:copilot:check   # Validate structure and scan for secrets
pnpm plugin:copilot:clean   # Remove generated output

After changing source skills or agents, regenerate and commit:

pnpm plugin:copilot:build
pnpm plugin:copilot:check
git add copilot-plugins/
git commit -m "chore: regenerate copilot plugin"

Copilot Instructions

Main Instructions File

Location: .github/copilot-instructions.md

This file contains global conventions that apply to all Copilot interactions:

Project Purpose - Working notebook, component library, tooling reference, living documentation
TypeScript Conventions - Strict types, prefer type over interface, named exports only
React Conventions - Functional components, direct hook imports, JSDoc comments
Testing Expectations - Vitest + Testing Library, 80% coverage minimum
Accessibility Baseline - WCAG AA compliance, keyboard navigation, semantic HTML
Nx and Monorepo Guidance - Affected commands, workspace imports, library structure

Scoped Instructions

Located in .github/instructions/, these files apply to specific file patterns:

00-repo-basics.instructions.md

Applies to: apps/**/*.{ts,tsx,js,jsx}, libs/**/*.{ts,tsx,js,jsx}
Purpose: Fundamental monorepo conventions and contribution guidelines

react-spa-router.instructions.md

Applies to: apps/client/**/*.{ts,tsx}
Purpose: Conventions for the React SPA client app

testing-and-quality.instructions.md

Applies to: **/*.test.{ts,tsx}, **/*.spec.{ts,tsx}, **/playwright/**/*.{ts,tsx}
Purpose: Test frameworks, patterns, and validation workflows

ui-and-accessibility.instructions.md

Applies to: **/*.tsx
Purpose: Tailwind v4, component conventions, and WCAG AA accessibility requirements

Custom Agents

Agents are specialized AI assistants that handle specific development tasks. Invoke them via the Copilot chat using @agent-name.

BrightSign Deploy

File: .github/agents/brightsign-deploy.agent.md

Purpose: Deploy React apps to BrightSign OS 9.x digital signage players with optimized packaging and debugging

When to use:

Packaging React apps for BrightSign hardware
Deploying to local BrightSign players via HTTP API
Debugging player issues using device APIs and remote inspection
Setting up fleet deployments with versioned releases

Usage:

@BrightSign Deploy
Package and deploy player-minimal to my BrightSign player at 192.168.1.100

Capabilities:

Package optimization (<100KB gzipped bundles)
autorun.brs bootstrap generation for OS 9.x HTML widgets
Local deployment via DWS HTTP API (port 8008)
Remote Chrome DevTools inspection
Fleet management with GitHub Releases

Handoffs:

Start Building Player App
Deploy to Player
Debug Player Issues

shadcnui Component Reviewer

File: .github/agents/shadcnui-component-reviewer.agent.md

Purpose: End-to-end review of shadcn/ui components for standards, accessibility, exports, tests, and Storybook coverage

When to use:

After adding a new shadcn/ui component to libs/shadcnui/src/lib
After modifying an existing component
When you need component taxonomy validation

Usage:

@shadcnui-component-reviewer data-display/badge

Capabilities:

Standards compliance review
Accessibility audit (ARIA, keyboard nav, focus management)
Export validation
Test coverage check
Storybook story validation
Component categorization

Handoffs:

🔧 Implement recommended fixes

UI Design Reviewer

File: .github/agents/ui-designer.agent.md

Purpose: Expert UI/UX design review providing actionable, evidence-based recommendations for modern, professional enterprise interfaces

When to use:

Reviewing page layouts or component designs
Identifying visual hierarchy issues
Improving perceived quality and clarity
Validating against modern B2B SaaS patterns

Usage:

@ui-designer http://localhost:4200/

Capabilities:

Evidence-based design audits using Chrome DevTools screenshots
Prioritized recommendations (Critical, Moderate, Minor)
Tailwind-first code examples
Spacing, typography, and color contrast analysis
Task efficiency improvements

Requirements:

Chrome DevTools MCP for screenshots OR user-provided screenshots

Handoffs:

🎨 Implement Design Changes

Requirements Planner

File: .github/agents/requirements-planner.agent.md

Purpose: Transforms user requirements into actionable implementation plans respecting project structure and conventions

When to use:

Starting a new feature
Planning complex refactors
Breaking down large requirements into tasks
Creating GitHub issues for team execution

Usage:

@requirements-planner [provide requirements document or description]

Capabilities:

Requirement clarification and gap analysis
Project structure research
Discrete task breakdown (1-5 files per task)
Dependency identification
Validation checkpoints
Complexity/sizing indicators

Output:

Actionable implementation plan
Clear acceptance criteria
Validation commands
Concrete file paths and component names

Custom Agent Foundry

File: .github/agents/custom-agent-foundry.agent.md

Purpose: Helps create new custom Copilot agents following project conventions

When to use:

Creating a new custom agent
Learning agent file format and best practices
Extending Copilot capabilities for project-specific needs

Signage Architect

File: .github/agents/signage-architect.agent.md

Purpose: Digital signage-focused React architecture guidance (deterministic layouts, multi-zone screens, 24/7 reliability)

When to use:

Designing a new signage screen layout or zone system
Auditing legibility/safe areas
Choosing animation/performance patterns for always-on screens

Usage:

@signage-architect
Build a 3-zone layout for 1080p with a ticker and a hero.

Handoffs:

Deploy To BrightSign Player
Debug BrightSign Runtime Issues

Signage Design Brief Writer

File: .github/agents/signage-design-brief-writer.agent.md

Purpose: Creates implementation-ready markdown design briefs for digital signage, particularly restaurant and menu-board concepts

When to use:

Starting a new signage project that needs creative direction
Defining visual concepts before implementation
Creating briefs for restaurant menus, wayfinding, dashboards

Usage:

@Signage Design Brief Writer
Create a menu board brief for "The Rustic Table" - a farm-to-table restaurant with rustic aesthetic, portrait orientation, 3 pages: main menu, drinks, specials

Output:

Creates a new folder under docs/signage design briefs/<Brief Name>/
Produces design brief.md with visual direction, typography, layout zones, and implementation notes

Handoffs:

Implement This Brief (hands off to @signage-architect)

Instructions Detox

File: .github/agents/instructions-detox.agent.md

Purpose: Extracts and organizes scoped instructions to keep prompts focused and reduce context bloat

When to use:

You’re about to do a complex change and want the smallest relevant ruleset
You suspect instruction overlap/conflicts

Skills

Skills are reusable workflows and procedures that can be referenced by agents or used directly in Copilot chat.

How to discover what's available:

Browse skills/ for the canonical source or .github/skills/ for the Copilot mirror
In Copilot Chat, describe the outcome you want (Copilot can select a matching skill based on the argument-hint)
Prefer explicit inputs for anything network-related (CIDR ranges, IPs, output paths)

Portable install:

npx skills add CambridgeMonorail/WallRun

The open skills CLI supports GitHub shorthand, full repo URLs, direct repo paths, and local paths. It is not an Nx feature and it is not limited to Claude-specific install locations.

shadcnui Component Review Skill

Location: skills/shadcnui-component-review/ (mirrored to .github/skills/shadcnui-component-review/)

Purpose: End-to-end component review workflow for shadcn/ui components

When to use:

New component added to libs/shadcnui/src/lib
Existing component modified
Standards review needed
Categorization validation

Workflows:

ARIA attributes validation
Keyboard navigation testing
Focus management review
Screen reader compatibility

performance-and-bundle.md

Bundle size analysis
Render performance checks
Memoization opportunities
Lazy loading considerations

review-and-fix.md

General standards review
Code quality checks
Convention adherence
Quick fixes

taxonomy-and-exports.md

Component categorization validation
Export structure review
Index file verification
Category placement

tests-and-storybook.md

Unit test coverage
Component test completeness
Storybook story validation
Visual regression testing setup

Inputs required:

Component path relative to libs/shadcnui/src/lib (e.g., data-display/badge)
Optional: Special concerns (accessibility, API design, variants, performance)

Output contract:

Actions taken
Issues found and fixes applied (with file paths)
Summary and next steps
Definition of done status

Chrome DevTools WebApp Debug Skill

Location: skills/chrome-devtools-webapp-debug/ (mirrored to .github/skills/chrome-devtools-webapp-debug/)

Purpose: Structured debugging workflow using Chrome DevTools MCP

When to use:

Web application runtime debugging
Browser-specific issues
Performance investigations
Network troubleshooting

Planning Skill

Location: skills/planning/ (mirrored to .github/skills/planning/)

Purpose: Standardized workflow for planning non-trivial changes

When to use:

Implementing new features
Complex refactoring
Changes affecting multiple files

See docs/plans/ for plan templates and storage.

Systematic Debugging Skill

Location: skills/systematic-debugging/ (mirrored to .github/skills/systematic-debugging/)

Purpose: Rigorous 6-step process for root cause analysis

When to use:

Fixing bugs
Investigating regressions
Solving complex integration issues

Code Review Ready Skill

Location: skills/code-review-ready/ (mirrored to .github/skills/code-review-ready/)

Purpose: Ensures changes are packaged effectively for review

When to use:

Preparing a PR
Self-reviewing code
Ensuring documentation is complete

Verification Skill

Location: skills/verification/ (mirrored to .github/skills/verification/)

Purpose: Standardized verification steps ("Definition of Done")

When to use:

Before committing
Before creating a PR
Validating a fix

BrightSign Skills

These skills provide reusable workflows for packaging/deploying to BrightSign players and debugging common issues.

Runtime guidance: skills/brightsign-runtime/
Local deploy: skills/brightsign-deploy-local/
Packaging: skills/brightsign-package/
Debugging: skills/brightsign-debug/
Fleet deploy: skills/brightsign-fleet-deploy/

Signage Design Skills

These skills capture the wall-screen rules that typical web development tools do not encode well by default.

Layout system: skills/signage-layout-system/
Placeholder images: skills/signage-placeholder-images/
Animation system: skills/signage-animation-system/

See Signage Placeholder Images for example prompts and expected outputs.

Practical entry points (non-skill commands that the skills may ask you to run):

pnpm package:player
pnpm deploy:player

Player Discovery Skills

These skills are designed for on-site development and diagnostics.

Scan: skills/player-discovery-scan/ — scan subnets for BrightSign players
Probe: skills/player-discovery-probe/ — check a single IP
Export: skills/player-discovery-export/ — output raw JSON for piping or sharing

Related pnpm commands:

# Scan local subnets, update .brightsign/players.json
pnpm discover

# Scan explicit subnet
pnpm discover --cidr 192.168.0.0/24

# Probe a single host
pnpm discover --host 192.168.0.42

# Print raw JSON to stdout
pnpm discover --json

Security boundary:

Discovery outputs contain internal IPs and device identifiers. .brightsign/players.json is gitignored.

Chat Modes

Enhanced GPT-4.1

File: .github/chatmodes/enhanced-gpt4.1.chatmode.md

Purpose: Enhanced conversation mode with specific configurations

When to use: General Copilot interactions requiring enhanced capabilities

Prompts

Create Signage Placeholders

File: .github/prompts/create-signage-placeholders.prompt.md

Purpose: Generates a small, structured placeholder asset plan for signage image zones before final artwork exists

When to use:

Scaffolding a new signage screen with image zones
Adding temporary image paths into a React component
Standardizing placeholder naming, dimensions, and alt text across a demo

Help

File: .github/prompts/help.prompt.md

Purpose: Quick reference guide to available prompts, agents, and skills

When to use: When you’re new to the repo tooling or need a refresher

Implement Next

File: .github/prompts/implement-next.prompt.md

Purpose: Implements the next unchecked task from the active plan

When to use: Executing a plan incrementally, one task at a time

Commit Helper

File: .github/prompts/commit.prompt.md

Purpose: Generates conventional commit messages

When to use: Staging and committing changes

PR Description

File: .github/prompts/pr-desc.prompt.md

Purpose: Generates standardized PR descriptions

When to use: Creating pull requests

MCP Check

File: .github/prompts/mcp-check.prompt.md

Purpose: Validates MCP server configuration

When to use: Troubleshooting AI tools

Validate Client

File: .github/prompts/validate-client.prompt.md

Purpose: Validation prompt for client application quality checks

When to use:

Pre-commit validation
Quality gate checks
CI/CD integration

How to Use Custom Agents

Invoking Agents

In GitHub Copilot Chat, use the @ symbol followed by the agent name:

@shadcnui-component-reviewer data-display/badge

Providing Context

Agents work best with clear, specific context:

Good:

@ui-designer http://localhost:4200/dashboard
Review the spacing and hierarchy on the dashboard page

Better:

@requirements-planner
Goal: Add a ticker component to a 3-zone signage layout
Constraints: 1080p only, must handle offline mode
Acceptance criteria: deterministic layout, no overflow, tested

Using Handoffs

Many agents provide handoffs to other agents or workflows:

Run the initial agent (e.g., @shadcnui-component-reviewer)
Review the findings
Click the handoff button (e.g., "🔧 Implement recommended fixes")
The handoff agent receives the context and executes the next phase

Creating Your Own Agents

Agent File Format

Custom agents use YAML frontmatter + Markdown:

---
name: My Custom Agent
description: Brief description of what this agent does
argument-hint: Example usage hint shown to users
model: Claude Sonnet 4.5
tools: ['read', 'edit', 'execute', 'search']
handoffs:
  - label: 🔧 Next Step
    agent: agent
    prompt: Instructions for the next agent
    send: false
---

# My Custom Agent

Agent instructions and behavior specification...

## Rules

- Rule 1
- Rule 2

## Workflow

1. Step 1
2. Step 2

Agent Development Guidelines

Single Responsibility: Each agent should have one clear purpose
Clear Inputs: Specify exactly what information the agent needs
Deterministic: Agent should produce consistent results with same inputs
Safe: Never run destructive operations without confirmation
Evidence-Based: Use tools to gather facts before making changes
Handoffs: Provide clear transitions to related workflows

Using the Custom Agent Foundry

For help creating agents:

@custom-agent-foundry
I need an agent that validates TypeScript types across the monorepo

Best Practices

When to Use Agents vs Regular Copilot Chat

Use Agents When:

You need specialized domain knowledge (UI design, component review)
The task requires multi-step workflows
You want consistent, repeatable processes
Evidence gathering is required (debugging, audits)

Use Regular Copilot Chat When:

Simple code generation
Quick questions about syntax or APIs
Exploratory conversations
One-off tasks

Effective Agent Usage

Provide Complete Context: Give agents all required information upfront
Use Argument Hints: Follow the suggested format in argument-hint
Review Before Acting: Agents propose changes; you approve them
Use Handoffs: Chain agents together for complex workflows
Verify Results: Always validate agent output with tests and linting

Combining Agents with Skills

Agents can reference skills for detailed procedures:

@shadcnui-component-reviewer data-display/avatar
Focus on accessibility using the a11y-and-focus workflow

Integration with Development Workflow

Pre-Development: @requirements-planner for feature planning
Development: Regular Copilot with planning skill for iterative work
Component Review: @shadcnui-component-reviewer for quality checks
UI Review: @ui-designer for design validation
Debugging: Use systematic-debugging skill for runtime issues
Pre-Commit: Use commit.prompt.md for conventional commits
PR Creation: Use pr-desc.prompt.md for PR descriptions

Additional Resources

MCP Servers (VS Code)

This repo includes a workspace MCP configuration for VS Code/Cursor in .vscode/mcp.json.

Currently configured servers:

brightdeveloper → https://brightdeveloper-mcp.bsn.cloud/mcp

Notes:

You must have workspace trust enabled for the repo.
After opening the repo, confirm brightdeveloper/* tools appear in Copilot Chat's tool list (agent/tool picker varies by VS Code version).
If you update MCP settings and tools don’t appear, reload the VS Code window.

Need Help?

Review agent-specific documentation in .github/agents/
Check skill workflows in skills/ or the mirrored .github/skills/
Ask in GitHub Discussions
Open an issue with the copilot-tooling label

This document is maintained as part of WallRun project. For updates or corrections, please submit a pull request.