Team Harness

Overview

A team harness is a shared operating layer for AI-assisted work.

Instead of every person teaching Copilot the same terminology, tools, workflows, quality standards, and safety rules in every conversation, the team captures that knowledge once in a versioned repository. The repository is installed as an Agency plugin and exposes reusable skills, specialized agents, tool connections, and instructions to every team member.

The harness does not replace people, source code, documentation, or normal engineering processes. It gives Copilot a consistent way to use them.

At a high level:

Person
  |
  v
Copilot
  |
  v
Team harness
  |-- shared instructions
  |-- reusable skills
  |-- specialized agents
  |-- approved tools
  |-- optional knowledge
  `-- validation and governance

The result is less repeated prompting, more consistent execution, and a durable way for the team's practices to improve over time.

The central idea

Most teams already have an informal harness. It is scattered across:

onboarding documents;
tribal knowledge;
copied prompts;
shell scripts;
runbooks;
chat history;
individual Copilot instruction files;
knowledge held by a few experienced people.

A team harness turns those fragments into an explicit, reviewable product.

The philosophical shift is:

Do not ask every person to become excellent at prompting every workflow. Encode the workflow so that the whole team can invoke it consistently.

This creates a practical interface between human intent and organizational systems. A person can say what they want at a high level, while the harness supplies the team's established procedure, tool routing, review gates, and output contract.

What belongs in a harness

Instructions

Instructions define behavior that should apply broadly:

terminology and naming conventions;
repository and platform conventions;
safety rules;
expected validation;
preferred tools;
when Copilot must ask before acting;
how private or sensitive information is handled.

Instructions should be short and stable. If a rule applies only to one workflow, put it in that workflow's skill instead.

Skills

A skill is a reusable workflow that a person can invoke by name.

Examples include:

preparing a handoff;
triaging an issue;
creating a release plan;
reviewing a design;
collecting evidence for a decision;
publishing approved knowledge;
generating a standard report.

A good skill defines:

when it should be used;
what inputs it accepts;
which tools it may use;
the ordered procedure;
approval or confirmation gates;
failure behavior;
the expected output;
how completion is verified.

Skills are most valuable when a workflow is repeated, consequential, easy to perform inconsistently, or dependent on knowledge that users should not need to memorize.

Specialized agents

An agent is a focused reasoning role with a narrow contract.

For example, a skill may own user interaction and writes, while a read-only agent does deep analysis and returns a recommendation. This separation is useful:

Skill: orchestration, approvals, side effects, final delivery
Agent: focused analysis, synthesis, critique, or classification

Keeping analytical agents read-only reduces risk. The skill remains responsible for deciding when a recommendation is allowed to become an external change.

Tools

Tools connect Copilot to real systems through Model Context Protocol (MCP) servers, command-line programs, or repository scripts.

Typical categories include:

source control;
work tracking;
documentation;
messaging and collaboration;
telemetry and analytics;
cloud resources;
local build and test tools.

The harness should expose only the tools a workflow needs. Tool access is a capability boundary, not merely a convenience.

Knowledge

Knowledge is optional. A harness can start with skills alone.

When knowledge is included, separate:

raw evidence: source material, transcripts, exports, or snapshots;
compiled knowledge: concise pages that answer recurring questions;
personal knowledge: user-specific notes or preferences;
private content: local-only material that must not be published.

The harness should distinguish evidence from interpretation and current facts from historical context. It should not turn every conversation into permanent documentation.

Scripts and validators

Markdown instructions are excellent for judgment, but deterministic operations belong in code.

Use scripts for:

schema validation;
normalization;
repeated API calls;
indexing;
repository setup;
lifecycle logging;
file generation;
checks that must produce the same answer every time.

Use Copilot for interpretation and scripts for invariants.

Design principles

1. Treat the harness as a product

The harness has users, interfaces, releases, regressions, and documentation. It should be maintained with the same care as other shared engineering tools.

2. Prefer intent-level interfaces

Users should invoke outcomes, not implementation details.

Good:

/team:prepare-handoff
/team:review-design

Less useful:

Run these twelve commands, query these three systems, and format the result
according to a template you must remember.

3. Put human gates before side effects

Reading and analysis can often proceed autonomously. Writes should be explicit.

Require confirmation before actions such as:

changing work items;
sending messages;
publishing documentation;
pushing branches;
opening pull requests;
modifying shared infrastructure.

Show the proposed semantic change before asking for approval.

4. Separate evidence, reasoning, and action

A robust workflow has three layers:

Evidence — what the sources actually say.
Reasoning — conclusions, classifications, and recommendations.
Action — the approved external change.

Do not let a summary masquerade as evidence or a recommendation silently become an action.

5. Be portable

A shared skill should not depend on one person's directory layout.

Prefer:

repository-relative paths;
environment-independent helper commands;
platform-aware scripts;
configuration files;
discovery rather than hard-coded machine paths.

6. Degrade honestly

If a tool or source is unavailable, report that limitation. Do not manufacture a successful-looking result.

A workflow should define whether missing evidence:

blocks the task;
lowers confidence;
requires user input;
permits a partial result.

7. Keep scopes narrow

One skill should represent one coherent user outcome. Split unrelated workflows. Use a specialized agent or helper script when a section becomes independently complex.

8. Version everything

Store the harness in Git. Review changes through pull requests. Record meaningful skill versions. Make it possible to determine which instructions produced an outcome.

9. Minimize telemetry

If usage is measured, collect operational facts such as skill name, duration, outcome, and version. Avoid storing prompts, generated content, credentials, or source data unless there is a clear and approved need.

10. Optimize for trust

The most important property of a harness is not maximum autonomy. It is predictable behavior that users are comfortable invoking.

Suggested repository structure

team-harness/
|-- .github/
|   `-- plugin/
|       `-- plugin.json
|-- skills/
|   |-- prepare-handoff/
|   |   `-- SKILL.md
|   `-- review-design/
|       |-- SKILL.md
|       `-- references/
|-- agents/
|   `-- design-reviewer.md
|-- scripts/
|   |-- setup.ts
|   `-- validate-skills.ts
|-- docs/
|-- knowledge/                 # optional
|-- agency.toml                # Agency MCP configuration
|-- mcp.json                   # standalone Copilot MCP configuration
|-- AGENTS.md                  # repository-wide instructions
|-- README.md
`-- package.json               # optional, for scripts and validation

Start smaller than this if necessary. One excellent skill and a clear README are more useful than a large empty framework.

Minimal plugin manifest

Create .github/plugin/plugin.json:

{
  "name": "team-harness",
  "version": "0.1.0",
  "description": "Shared skills, agents, and tool configuration for the team.",
  "author": {
    "name": "Your Team"
  },
  "homepage": "https://github.com/YOUR-ORG/team-harness",
  "keywords": [
    "agency",
    "copilot",
    "skills"
  ],
  "skills": "./skills",
  "agents": "./agents",
  "mcp": "./mcp.json"
}

The manifest tells plugin consumers where the shared capabilities live.

Minimal skill

Create skills/prepare-handoff/SKILL.md:

---
name: prepare-handoff
version: 1.0.0
description: >-
  Create a concise handoff for another person or Copilot session. Use when the
  user asks to preserve current progress, transfer work, or resume later.
owner: team
---

# Prepare Handoff

## Inputs

- The current goal.
- Confirmed progress.
- Important constraints.
- Failed approaches.
- The first actionable next step.

## Procedure

1. Inspect the current repository and branch without changing them.
2. Summarize only facts supported by the conversation or repository state.
3. Include:
   - Goal
   - Current progress
   - What worked
   - What did not work
   - Next steps
4. Show the proposed handoff and ask for approval before saving it.

## Output

One Markdown handoff that a fresh Copilot session can use without access to the
original conversation.

## Safety

- Do not invent commit IDs, test results, owners, or decisions.
- Do not overwrite an existing handoff without confirmation.

The frontmatter helps Copilot discover when to use the skill. The body is the workflow contract.

Minimal specialized agent

Create agents/design-reviewer.md:

---
name: design-reviewer
description: >-
  Read-only reviewer that evaluates a proposed design for correctness,
  operability, maintainability, and unresolved risk.
tools: []
---

# Design Reviewer

Review the supplied design. Do not edit files or perform external writes.

Return:

1. The strongest parts of the design.
2. High-confidence correctness or operability risks.
3. Missing decisions or evidence.
4. Recommended changes, ordered by impact.
5. A final verdict: ready, ready with follow-ups, or needs revision.

The parent skill can gather context, invoke this agent, present the findings, and own any later edits.

Tool configuration

Agency can bootstrap approved MCP servers for plugin sessions through agency.toml.

Generic example:

[mcps.builtins]
work-context = true

[mcps.builtins.work-tracker]
type = "work-tracker"
organization = "YOUR-ORGANIZATION"

For standalone Copilot sessions, provide equivalent MCP configuration in mcp.json:

{
  "mcpServers": {
    "work-tracker": {
      "type": "local",
      "command": "agency",
      "args": [
        "mcp",
        "work-tracker",
        "--org",
        "YOUR-ORGANIZATION",
        "--transport",
        "stdio"
      ],
      "tools": ["*"]
    }
  }
}

Replace these placeholders with integrations approved for your environment. Never commit credentials or personal access tokens.

Instructions versus skills

Use AGENTS.md or Copilot instruction files for broad rules:

# Team instructions

- Read the repository's local instructions before making changes.
- Preserve unrelated user changes.
- Use the smallest validation that covers the change.
- Ask before performing an external write.
- Never commit credentials or private data.

Use skills for named workflows. Do not place a multi-page procedure in global instructions if it is relevant only when one task is requested.

Copilot can load instructions from repository files such as:

AGENTS.md;
.github/copilot-instructions.md;
.github/instructions/**/*.instructions.md.

User-level instructions can also apply across repositories, but team rules are usually easier to review and version when they live in the harness repository.

Onboarding model

A good onboarding flow should:

clone or update the canonical harness repository;
install required local dependencies;
register the Agency plugin;
register the skills with standalone Copilot when desired;
configure approved MCP integrations;
verify installation;
tell the user to start a new session so the refreshed plugin is loaded.

Automate this in one setup script once the manual process is stable.

Governance

Use normal software review practices:

require pull requests for shared workflow changes;
assign an owner to each skill;
test deterministic scripts;
lint skill frontmatter and required sections;
require version bumps for behavior changes;
include privacy and side-effect review;
remove obsolete skills instead of allowing duplicates;
document how users refresh their installed plugin.

Review a skill by asking:

Is its trigger clear?
Is its outcome clear?
Can it accidentally write before approval?
Does it distinguish evidence from interpretation?
Does it behave honestly when a source is unavailable?
Is it portable across team members' machines?
Is the result verifiable?

A practical adoption path

Phase 1: one painful workflow

Choose one repeated workflow that already has a recognizable procedure. Encode it as a skill and test it with several team members.

Phase 2: shared foundations

Add common instructions, setup automation, validation, and the small set of tools needed by the first skills.

Phase 3: specialized reasoning

Introduce read-only agents for deep analysis, review, or synthesis. Keep external writes in skills with human gates.

Phase 4: optional knowledge

Add curated shared knowledge only when users repeatedly need the same context. Define evidence, privacy, freshness, and ownership rules before scaling it.

Phase 5: feedback and maintenance

Track failures and confusing interactions. Improve the shared workflow rather than teaching every user a new workaround.

What not to do

Do not begin by copying every team document into the harness.
Do not encode secrets or credentials.
Do not give every skill every tool.
Do not allow an analytical agent to make unreviewed external changes.
Do not hard-code one person's paths or machine configuration.
Do not treat AI-generated summaries as authoritative evidence.
Do not hide partial failures behind optimistic language.
Do not create skills for one-time tasks with no likely reuse.
Do not let multiple obsolete plugins expose conflicting versions of a workflow.

How to set up your own Team Harness

Prerequisites

Install:

Git;
Node.js if your setup or validation scripts use it;
GitHub CLI and authenticate with gh auth login;
GitHub Copilot CLI;
Agency, with access to the MCP integrations your team intends to use.

Confirm the basic commands are available:

git --version
node --version
gh auth status
copilot --version
agency --version

1. Create the repository

mkdir team-harness
cd team-harness
git init
mkdir -p .github/plugin skills agents scripts docs

Add:

.github/plugin/plugin.json;
README.md;
AGENTS.md;
one skills/<skill-name>/SKILL.md;
agency.toml and mcp.json only if the first skill needs external tools.

Commit and push the repository to your team's GitHub organization.

2. Install the Agency plugin

From the repository root:

agency plugin install github:YOUR-ORG/team-harness:. \
  --engine copilot \
  --cache-policy force-refresh \
  --fetch-mode foreground

Verify it:

agency plugin list --engine copilot

3. Register with standalone Copilot

If your team also uses Copilot outside Agency sessions, register the plugin:

copilot plugin install YOUR-ORG/team-harness

If direct plugin installation is unavailable or deprecated in your environment, register the skill directory from the local clone:

copilot skill add /absolute/path/to/team-harness/skills

Verify inside Copilot with:

/plugin
/skills
/env

4. Start a new session

Plugin capabilities are loaded when a session starts. Restart Copilot or open a new Agency Copilot session after installation or a forced refresh.

5. Test the first skill

Ask for the workflow in natural language and by its explicit command, for example:

Prepare a handoff for this work.

/team:prepare-handoff

Confirm that:

Copilot selects the skill for the intended trigger;
the procedure follows the documented order;
approval occurs before writes;
unavailable information is reported honestly;
the final output matches the contract.

6. Add validation

Create a small validator that checks at least:

every skill has valid frontmatter;
names are unique;
required fields exist;
referenced files exist;
writable skills contain an approval rule;
versions are bumped when behavior changes.

Run validation in pull requests.

7. Create a repeatable setup script

Once manual installation works, create scripts/setup.ts or an equivalent cross-platform script that:

installs dependencies;
registers or refreshes the Agency plugin;
registers standalone Copilot skills if desired;
configures only approved integrations;
verifies both registrations;
prints a reminder to restart the session.

8. Give this prompt to Copilot

Replace the placeholders, then give the following to a Copilot session:

Create a repository named team-harness for my team.

The repository must be an Agency plugin that provides shared GitHub Copilot
skills and optional specialized agents. Keep the first version intentionally
small.

Build:
1. .github/plugin/plugin.json with the plugin name "team-harness".
2. A concise README explaining the purpose, architecture, installation, refresh,
   and contribution process.
3. AGENTS.md with repository-wide safety, portability, validation, and review
   rules.
4. skills/prepare-handoff/SKILL.md as the first reusable skill.
5. agents/design-reviewer.md as a read-only example agent.
6. Optional agency.toml and mcp.json templates containing placeholders only; do
   not invent integrations and do not include credentials.
7. A cross-platform setup script that installs or refreshes the plugin for
   Agency Copilot and registers the local skills with standalone Copilot.
8. A validator for skill frontmatter, unique names, referenced files, and
   semantic versions.
9. A pull-request workflow that runs the validator.

Use repository-relative paths and placeholder organization names. Do not include
private team data, internal system names, credentials, personal paths, or
machine-specific assumptions.

Before writing, ask me which repeated workflow should be the first real team
skill. After implementation, run the validator and show me the exact installation
commands for:
- agency plugin install github:YOUR-ORG/team-harness:. --engine copilot
- copilot skill add <absolute-clone-path>/skills

jdylanmc/Team Harness.md