diff --git a/.gitignore b/.gitignore deleted file mode 100644 index e43b0f98..00000000 --- a/.gitignore +++ /dev/null @@ -1 +0,0 @@ -.DS_Store diff --git a/website/blog/2026-05-31-copilot-config-files-guide.md b/website/blog/2026-05-31-copilot-config-files-guide.md deleted file mode 100644 index 40f255e7..00000000 --- a/website/blog/2026-05-31-copilot-config-files-guide.md +++ /dev/null @@ -1,366 +0,0 @@ ---- -slug: /2026-05-31-copilot-config-files-guide -authors: [dfberry] -date: 2026-05-31 -image: ./media/2026-05-31-copilot-config-files-guide/watercolor-1-layers-of-governance.png -canonical_url: https://dfberry.github.io/blog/2026-05-31-copilot-config-files-guide -custom_edit_url: null -sidebar_label: "2026.05.31 Copilot Config Files" -title: "Copilot Configuration Files: What They Are, Where They Live, and When to Use Them" -description: "A practical guide to `.github/copilot-instructions.md`, agents, skills, prompts, and workflows — what each one does, where to find accurate examples, and how they fit together." -tags: - - copilot - - configuration - - repository-patterns - - reference -updated: 2026-05-31 16:10 PST -keywords: - - copilot-instructions - - copilot-agents - - copilot-skills - - copilot-prompts - - github-configuration - - ai-workflow ---- - -When I work with repos that use Copilot, I keep running into the same confusion: people have these files scattered across `.github/`, but they don't know what each one does, why they exist separately, or how they're supposed to work together. - -I'll see `.github/copilot-instructions.md` and `.github/agents/` in the same repo, then a `prompts/` folder, then maybe a workflow file that looks half like YAML and half like agent instructions. The files exist, but the mental model doesn't. - -This guide is my attempt to make that mental model boring and usable. I want to show what each file is for, where real repos keep them, and which claims I can actually defend with links. - -![Layers of governance showing instructions, agents, and skills as concentric circles](./media/2026-05-31-copilot-config-files-guide/watercolor-1-layers-of-governance.png) - -*The governance metaphor works like nested rings: instructions shape the space, agents interpret it, and skills do the work at the center.* - -## Quick Reference: The Five File Families - -| File | Lives at | Purpose | When to use | -|------|----------|---------|------------| -| **Copilot instructions** | `.github/copilot-instructions.md` | Repository-wide governance (always-on context) | "All Copilot work in this repo should follow these rules" | -| **Agent definitions** | `.github/agents/` | Specialist persona with its own scope, tools, and constraints | "This task needs a reviewer or specialist with tighter boundaries" | -| **Skills** | `.github/skills/{name}/SKILL.md` | Reusable workflow package with instructions, resources, and optional scripts | "This is a repeatable procedure Copilot should know how to do" | -| **Prompt files / prompt docs** | Official prompt files: `.github/prompts/*.prompt.md`; repo-local docs often live in `.github/prompts/*.md` | Reusable prompt template or task-specific reference context | "I need either a reusable prompt in the IDE or a deeper reference doc for a specific task" | -| **Workflows** | `.github/workflows/` | GitHub Actions automation and remote triggers | "I need this to run on a label, schedule, dispatch, or PR event" | - -![Configuration files structure across the five .github families](./media/2026-05-31-copilot-config-files-guide/diagram-2-configuration-files-structure.svg) - -*This structure diagram turns the five file families into one navigable map so you can see which pieces are baseline, specialized, reusable, or event-driven.* - -![Stylized .github home showing where instructions, agents, skills, prompts, and workflows live](./media/2026-05-31-copilot-config-files-guide/image-2-where-they-live.png) - -*The folder-house metaphor emphasizes that these files live together, but each room has a different job.* - - - -Those are the most commonly confused files. There are also path-specific instructions, `AGENTS.md`, hooks, and MCP configs. I keep coming back to these five because they're the ones people mix together most often. - -## The Copilot Instructions File: Governance Layer - -`/.github/copilot-instructions.md` is the ambient context that sits behind Copilot work in a repo. It's not something I invoke manually. It's the baseline. - -**What it contains:** -- Coding standards and conventions -- Architecture guidelines -- Documentation expectations -- Review requirements -- What "done" looks like -- Security constraints -- Naming conventions - -**Real examples:** - -[Microsoft MCP Copilot Instructions](https://github.com/microsoft/mcp/blob/main/.github/copilot-instructions.md#L1-L16) — a compact baseline file. The heading is `Coding Instructions for GitHub Copilot`, not "Comprehensive Overview," and it goes straight into always-apply rules, build expectations, and PR guidance. - -[Azure SDK for JavaScript Copilot Instructions](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/copilot-instructions.md#L86-L111) — a denser governance file. The Azure SDK guidance gets specific about API design, implementation choices, and when to explain a deviation from the house style. In my experience, this kind of baseline makes Copilot more likely to produce code aligned with review expectations. - -**When you use it in Copilot:** -- Open Copilot chat in the repo -- Ask it to "write a PR description" -- Copilot includes the repo instructions automatically - -**How long should it be?** -Short enough that a human can still scan it. MCP's file is compact. Azure's is more opinionated. If the instructions file starts reading like a runbook instead of repo policy, I move the task-specific detail somewhere else. - -**Key rule:** Instructions describe outcomes and standards. They are the repo's rules of engagement, not the step-by-step workflow. - ---- - -## Agent Definitions: Specialist Persona - -`.github/agents/` is where I expect to find specialist agents — focused reviewers or operators with their own scope, tool boundaries, and output format. - -**What an agent file contains:** -- What the agent specializes in -- Which tools it can access -- Task-specific constraints -- Expected output format -- When to use it over the default assistant - -**Real examples:** - -[Azure SDK: archie.agent.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md#L1-L45) — architecture review specialist. The file defines the reviewer's purpose, allowed tools, scope, and output format. It also explicitly loads `../prompts/architecture-review-guidelines.md` in [lines 6-8](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md#L6-L8). - -[Azure SDK: scribe.agent.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/scribe.agent.md#L1-L45) — documentation review specialist. Same pattern, different charter: README, CHANGELOG, snippets, samples, and TSDoc. - -**How to invoke it:** -The exact path depends on the surface. GitHub's [customization cheat sheet](https://docs.github.com/en/copilot/reference/customization-cheat-sheet) is the clearest map I found: select the custom agent in the UI, use `/agent` in Copilot CLI, or reference the agent naturally in chat. - -**How it differs from instructions:** -- **Instructions:** Always-on, repo-wide governance -- **Agent:** Specialized, on-demand, with its own boundaries - -I don't need agents for every repo. A lot of projects are fine with instructions alone. But once I have a recurring task like architecture review or docs review, an agent gives that work a clear owner. - ---- - -## Skills: Reusable Procedures - -A skill is a folder with a `SKILL.md` file plus whatever supporting templates, scripts, or resources the workflow needs. GitHub's docs describe skills as packages that Copilot can load when they're relevant to a task. That detail matters. A skill is not just a long prompt. It's a reusable procedure. - -**What a skill contains:** -- When to use the skill -- What it does -- Input requirements -- Output expectations -- Links to deeper references -- Templates or helper assets -- Scripts or automation, if the workflow needs them - -**Real examples:** - -[OpenAI Agents Python: code-change-verification](https://github.com/openai/openai-agents-python/blob/main/.agents/skills/code-change-verification/SKILL.md) — a concrete verification skill. It tells Copilot when to run the verification stack and points to scripts that execute the checks. - -[Vercel Next.js: authoring-skills](https://github.com/vercel/next.js/blob/canary/.agents/skills/authoring-skills/SKILL.md) — a nice example of a skill that explains what belongs in a skill versus in `AGENTS.md`. - -**How it gets used:** -- Copilot can auto-load it when the task matches -- You can ask for that workflow explicitly in a surface that supports skills -- A custom agent can rely on it as part of a larger procedure - -**Where they live:** -- `.github/skills/` in GitHub's current docs -- Other ecosystems also use `.agents/skills/` - -**Skill vs. Agent vs. Instructions — the mental model:** - -GitHub's documentation describes what each feature does, but doesn't frame the relationship as explicitly as I'd like. Here's my mental model: **Instructions set the rules. Agents decide. Skills execute.** This is my interpretation, not GitHub's official framing, but it helps me remember which tool to reach for. - -![Mental model hierarchy showing instructions governing agents and skills](./media/2026-05-31-copilot-config-files-guide/diagram-1-mental-model-v3.svg) - -*This cascade makes the control flow explicit: rules constrain decisions, and decisions choose the reusable execution path.* - ---- - -## Skills vs. Prompts: The Critical Difference - -This is the distinction that tripped me up most, because people use the word "prompt" to mean two different things. - -| Aspect | Skill | Prompt file / prompt doc | -|--------|-------|--------------------------| -| **What it is** | Agent-skill package with instructions, resources, and sometimes scripts | Either an official `.prompt.md` template or a repo-local markdown doc used as reference context | -| **How it gets used** | Copilot auto-loads it when relevant, or you ask for it in a supported surface | Official prompt files are typically user-selected or referenced in supported IDEs; repo-local docs can also be linked from agents or workflows | -| **What's inside** | Steps, commands, templates, helper assets | Examples, patterns, checklists, input variables, edge cases | -| **CLI support** | Yes | Official `.prompt.md` prompt files are IDE-focused, not Copilot CLI | - -**The caveat that matters:** Official GitHub prompt files use `.prompt.md` and are an IDE feature. Azure's `.github/prompts/*.md` files are different. They're repo-local reference docs that agents or workflows load, not the product feature GitHub documents as prompt files. - -That means my old rule of thumb was too neat. Prompts are not always passive reference, and skills are not always the only place with step-by-step guidance. The better distinction is this: skills are packaged workflows Copilot can use as skills; prompt files and prompt docs are reusable context. - -![Decision tree for choosing between skills, official prompts, prompt docs, or no file](./media/2026-05-31-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree.svg) - -*The decision tree compresses the distinction into one question sequence: reusable workflow first, reusable prompt second, reference doc third.* - ---- - -## Prompts: Task-Specific Expertise - -`.github/prompts/` is where many repos store task-specific context. Sometimes those files are official GitHub prompt files ending in `.prompt.md`. Sometimes, and this is what Azure JS does, they are plain markdown docs that reviewers load as guidance. - -**What a prompt file or prompt doc contains:** -- Patterns and examples -- Detailed guidance for a specific task -- Decision rules -- Known edge cases -- Sometimes input placeholders if it's an official prompt file - -**Real examples:** - -[Azure SDK: architecture-review-guidelines.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/prompts/architecture-review-guidelines.md#L3-L18) — a repo-local reference doc. It defines the review scope and checklist for architecture review, and [Archie points to it directly](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md#L6-L8). - -[GitHub gh-aw: create-agentic-workflow.md](https://github.com/github/gh-aw/blob/v0.71.1/.github/aw/create-agentic-workflow.md#L13-L25) — another repo-local guide. It explains the markdown workflow structure used by `gh-aw`. Useful context, yes. An official GitHub prompt-file feature, no. - -**How agents use them:** -Agents or workflows can read these docs at runtime. In Azure JS, the architecture review guidance also points back to `.github/copilot-instructions.md`, which is a nice example of the layers staying connected instead of duplicating each other. - -**Where they live:** -- Official prompt files: `.github/prompts/*.prompt.md` -- Repo-local reference docs: often `.github/prompts/*.md` -- Organized by task: architecture review, dependency review, release prep, and so on - -**Why separate files?** -Because the detail belongs close to the task, not smeared across every Copilot interaction. When instructions become hard to scan, moving task-specific context into separate files keeps the baseline clean. - ---- - -## Workflows: Automation Triggers - -`.github/workflows/` is standard GitHub Actions. I include it here because people often blame Copilot for behavior that is really coming from a workflow trigger. - -**What a workflow does:** -- Listens for triggers such as push, label, schedule, or manual dispatch -- Runs remote automation on GitHub -- Starts a reviewer or other automation path -- Posts status, comments, or checks back to the PR - -**Real example:** - -[Azure SDK for JavaScript reviewer workflows](https://github.com/Azure/azure-sdk-for-js/tree/main/.github/workflows) — not one big controller that fans everything out. Each reviewer has its own workflow file. [Archie](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md#L2-L18) and [Dexter](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md#L2-L18) both trigger on `pull_request_target` with `types: [labeled]`, and [Dash](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md#L78-L84) says plainly that its job is to review a PR for performance regressions. - -**How it connects to agents and skills:** -The workflow is the remote trigger. In Azure JS, each reviewer workflow posts its own findings back to the PR. In other repos, a workflow might also call a custom agent or load a skill, but that's not the part I can prove from this example. - ---- - -## How They Wire Together: A Real Workflow - -Here's the version of the Azure SDK flow I can actually defend with links. - -**1. A label triggers the run** -In Azure JS, the review workflows listen for `pull_request_target` with `types: [labeled]`, not for PR creation. You can see that in [archie.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md#L2-L18) and [dexter.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md#L2-L18). - -**2. Each reviewer has its own workflow** -[Archie](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md#L2-L18), [Dash](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md#L2-L18), [Dexter](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md#L2-L18), and [Scribe](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/scribe.md#L2-L18) are separate files under `.github/workflows/`. They can run independently when their trigger label appears. This is not one workflow spawning four reviewers in parallel. - -**3. The workflow itself states the review job** -[Dash](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md#L78-L84) literally says it reviews the PR for performance regressions and anti-patterns. Archie and Dexter follow the same pattern for architecture and dependency review. - -**4. Agent files and prompt docs are the reusable layer** -Separately from the workflow trigger, [archie.agent.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md#L1-L45) defines the architecture reviewer as a reusable custom agent, and [lines 6-8](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md#L6-L8) load `../prompts/architecture-review-guidelines.md`. That prompt doc then points back to the repo instructions in [architecture-review-guidelines.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/prompts/architecture-review-guidelines.md#L3-L18). - -**5. Findings land on the PR from each workflow** -[Archie](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md#L56-L73) and [Scribe](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/scribe.md#L56-L73) both declare `create-pull-request-review-comment` and `submit-pull-request-review` in `safe-outputs`, with run messages for the PR review lifecycle. So the accurate mental model is: each reviewer workflow posts its own findings. There isn't a separate "collector" workflow in this example. - -**6. Skills are adjacent, not proven by this example** -Skills still matter to the overall ecosystem, but Azure's review workflows are not the example I would use to claim that agents are invoking skills behind the scenes. If I want to show skills, I use an actual `SKILL.md` repo. - -That's the loop I trust: a label starts a workflow, the workflow runs the reviewer, the reviewer uses repo guidance, and comments come back to the PR. - -![Sequence diagram for the Azure SDK architecture review workflow](./media/2026-05-31-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger.svg) - -*This sequence shows the asynchronous handoff from label to workflow to reviewer guidance and back to a PR comment.* - ---- - -## Using Copilot with These Files: Chat and CLI - -### In Copilot Chat (Browser or VS Code) - -**Scenario:** You're in a repo and you open Copilot chat. - -``` -You: write a PR description -``` - -Copilot reads `.github/copilot-instructions.md` and picks up things like: -- PR title format -- Required sections -- Review expectations - -Result: the draft is much more likely to match the repo's stored rules. - -**Scenario 2:** You want the specialist reviewer. - -``` -You: use the archie agent to review my API changes -``` - -Depending on the surface, you might select `archie` in the agent picker, use `/agent` in Copilot CLI, or reference it naturally in chat. The important part is the same: the agent file gives that review task its own scope and constraints. - -### In Copilot CLI - -**Scenario:** You're working locally and you want a code review from the terminal. - -```shell -copilot -/review focus on bugs and security issues in my current changes -``` - -GitHub documents `/review` as the CLI code review path in its [Copilot CLI docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) and [agentic code review guide](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review). This is the replacement for the old `gh copilot pr-review` mental model I had in my head. - -**Scenario 2:** You want to trigger the remote GitHub Actions reviewer from your terminal. - -```shell -gh workflow run archie.md -f item_number=42 -``` - -That command is a **remote workflow dispatch through GitHub CLI**, not local Copilot behavior. Azure's reviewer workflows expose `workflow_dispatch` with an `item_number` input in [archie.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md#L6-L11), so `gh` can start the run on GitHub. - ---- - -## Decision Table: Which File for What? - -![Decision tree for placing work in instructions, agents, skills, prompts, or workflows](./media/2026-05-31-copilot-config-files-guide/diagram-5-file-placement-decision-tree.svg) - -*This placement tree turns the file choice into a routing problem: match the task shape, then drop it in the right folder.* - -| I need to... | Put it in... | Why | -|--------------|--------------|-----| -| Set coding standards | Copilot instructions | Always-on, repo-wide governance | -| Require testing notes on all PRs | Copilot instructions | It's a rule, not a workflow | -| Automate PR review on labels | Workflows + reviewer definitions | Labels are a GitHub Actions trigger, and the reviewer needs its own scope | -| Store detailed architecture patterns | Prompt docs | Too bulky for baseline instructions; reviewers can load them when needed | -| Make code generation or verification repeatable | Skills | Copilot can load the packaged workflow when the task matches | -| Handle a one-time task | Chat | Some work doesn't need a file at all | - ---- - -## Minimal Repo Setup - -If I'm starting fresh and I don't want to overengineer this, I keep it boring. - -**Minimal viable setup:** -- `.github/copilot-instructions.md` (recommended baseline) -- No agents yet unless I have a recurring specialist task -- No skills yet unless I keep repeating the same workflow -- No prompt docs yet unless the task-specific context is making the instructions file noisy - -**As the repo grows:** -- Add agents when a task needs its own tool restrictions or review charter -- Add skills when a workflow deserves packaging -- Add prompt docs when a reviewer or task needs deeper context than the baseline file should carry - -Start minimal, then add layers only when each layer removes confusion. - ---- - -## How to Find Examples in Real Repos - -Here are the examples I would study first. - -**Azure SDK for JavaScript** — the clearest end-to-end example I found -- Instructions baseline: [`.github/copilot-instructions.md` lines 86-111](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/copilot-instructions.md#L86-L111) -- Architecture reviewer: [`.github/agents/archie.agent.md` lines 1-45](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md#L1-L45) -- Prompt doc Archie loads: [`.github/prompts/architecture-review-guidelines.md` lines 3-18](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/prompts/architecture-review-guidelines.md#L3-L18) -- Performance reviewer workflow: [`.github/workflows/dash.md` lines 78-84](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md#L78-L84) -- Dependency reviewer workflow: [`.github/workflows/dexter.md` lines 2-18](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md#L2-L18) -- Documentation reviewer: [`.github/agents/scribe.agent.md` lines 1-45](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/scribe.agent.md#L1-L45) - -**Microsoft MCP** — a small, readable baseline instructions file -- Instructions: [`.github/copilot-instructions.md` lines 1-16](https://github.com/microsoft/mcp/blob/main/.github/copilot-instructions.md#L1-L16) - -**GitHub gh-aw** — a good example of repo-local workflow guidance that looks prompt-like -- Workflow authoring guide: [`.github/aw/create-agentic-workflow.md` lines 13-25](https://github.com/github/gh-aw/blob/v0.71.1/.github/aw/create-agentic-workflow.md#L13-L25) - -**Vercel Next.js** — useful for skill design patterns -- Skill example: [`.agents/skills/authoring-skills/SKILL.md`](https://github.com/vercel/next.js/blob/canary/.agents/skills/authoring-skills/SKILL.md) - -I stole this idea from reading public repos side by side. Once I stopped looking for one canonical layout, the patterns got easier to see. - ---- - -## The One-Sentence Rule - -If I'm stuck deciding where something belongs, this is still the fastest check I know: **If it reads like a rule, put it in instructions. If it reads like a reusable workflow, put it in a skill. If it reads like task-specific context, put it in a prompt doc or prompt file. If it has to run on GitHub events, put it in a workflow.** - -That's the mental model I keep coming back to, and it's the first one that has held up once I started checking the links. diff --git a/website/blog/2026-05-31-instructions-versus-skills.md b/website/blog/2026-05-31-instructions-versus-skills.md deleted file mode 100644 index 15d76f04..00000000 --- a/website/blog/2026-05-31-instructions-versus-skills.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -title: "The Instructions vs Skills Distinction: Governance vs Execution" -authors: [dfberry] -date: 2026-05-31 -slug: /2026-05-31-instructions-versus-skills -tags: [copilot, governance, skills, repo-instructions, architecture] -description: "When to put guidance in repo instructions vs skills — a practical decision framework for Copilot-powered teams." -keywords: - - instructions - - skills - - governance - - execution - - repository-patterns - - copilot -image: /blog/media/2026-05-31-instructions-vs-skills/hero.png ---- - -When I look at repos that manage agents and skills, I keep noticing the same pattern: governance rules do not stay in the instruction layer. They get pushed down into skills. A repo starts with a clean distinction in theory, then practical pressure takes over. It feels easier to tuck a rule into the skill that already handles PRs, releases, reviews, or docs updates than to keep the governance layer separate and durable. - -That leak creates a mess fast. Policy gets buried inside execution, contributors have to hunt through step-by-step workflow files to figure out what is actually required, CI can only enforce the rules that escaped into the right place, and every workflow tweak risks rewriting what should have been a stable repo expectation. The instructions-versus-skills distinction only matters if you keep the layers separate. Once rules get pushed into skills, you lose both layers. - -So I kept pulling on one simple question: when does guidance belong in repo instructions, and when does it belong in a skill? - - - -## Build the mental model - -The cleanest model I found is this: **instructions constrain behavior; skills produce behavior**. - -Repo instructions are the guardrails that shape every interaction. They are ambient. They sit in the background like shop rules posted above the bench: use this style, follow this architecture, require these approvals, don't skip these checks. They tell Copilot what "good" looks like before any specific task begins. - -Skills are different. They are invoked capabilities. A skill is more like picking up a jig, checklist, or specialty tool when the work calls for it. It exists to *do* something repeatable: create a PR, summarize CI failures, triage issues, draft release notes, or run a multi-step review. - -My perspective: if instructions are the Cascades in the distance — fixed, always shaping the weather — skills are the trails you choose for today's hike. Both matter. They just solve different problems. - -| Layer | Question it answers | Behavior model | Best for | -| --- | --- | --- | --- | -| Repo instructions | "How do we operate in this repo?" | Passive, always-on | Rules, conventions, expected outcomes | -| Skills | "What reusable thing should happen now?" | Active, invoked when relevant | Workflows, procedures, tool-backed execution | - -## Use a decision framework instead of guessing - -The practical test is boring, and boring is good. Before I place any Copilot guidance, I ask four questions: - -1. **Should this apply all the time?** If yes, it leans toward instructions. -2. **Does it read like a rule or expectation?** If yes, it belongs in instructions. -3. **Does it require ordered steps, tools, or output generation?** If yes, it belongs in a skill. -4. **Would I ever want to call this only on demand?** If yes, it probably belongs in a skill. - -The questions sound cleaner than real repos feel, so I keep a few messy cases around to pressure-test them. - -### Test the messy cases - -- A PR template with required sections plus a note like "if this is a hotfix, add the emergency label" is mixed. The required sections are instruction material. The branching label logic belongs in a skill or automation. -- A linter config that sets repo rules but also shells out to custom validation is mixed too. The rules stay in config. The shell step is execution, so I want that script or skill to stand on its own. -- A docs checklist that says "update screenshots when UI changes" looks simple until the exceptions show up. The durable expectation belongs in instructions. The conditional screenshot workflow is skill territory. - -None of that is perfectly tidy. Sometimes the first draft is a mixed artifact and the framework only tells me where to cut it apart. That's still useful. I don't need a universal law. I need a way to stop hiding rules inside procedures just because they showed up in the same file first. - -### Put durable rules in repo instructions - -Repo instructions should hold the durable governance layer: coding standards, architectural boundaries, PR naming conventions, review expectations, security constraints, documentation requirements, and the definition of done. - -A PR guidance block usually looks more like this: - -```md -# .github/copilot-instructions.md - -## Pull Request Guidelines -- Use format: [area]: short description -- Include: summary, testing notes, and docs impact -- Request review from CODEOWNERS -- Do not suggest merging until CI passes -- Use the pr-lifecycle skill when creating or updating pull requests -``` - -This works because the file describes expectations, not choreography. It doesn't try to walk Copilot through twenty steps. It tells the agent what standards must be true whenever PR work comes up. - -Good instruction content usually has these traits: - -- It is always applicable or path-scoped in a predictable way. -- It describes outcomes, not button clicks. -- It stays stable even if tooling changes. -- It is short enough to remain readable and enforceable. - -If I change GitHub templates, CI jobs, or branch automation later, the governance may stay the same. That's the signal that the content belongs in instructions. - -### Put executable workflows in skills - -Skills should own the operational layer. If something needs steps, tools, branching logic, templates, or generated artifacts, I move it into a skill. - -At repo level, it usually looks more like this: - -```text -.copilot/skills/pr-lifecycle/ -├── SKILL.md -├── templates/pr-description.md -└── scripts/check-pr-readiness.sh -``` - -Inside the skill, I keep the file focused on execution: - -```md -# PR Lifecycle Manager - -## When to use -- Creating a new pull request -- Updating a pull request after review -- Checking whether a pull request is ready to merge - -## Capabilities -- Draft PR title and description from git diff -- Validate required sections and linked work items -- Summarize failing CI checks -- Prepare merge notes or release notes -``` - -That belongs in a skill because it executes actions on behalf of the user. It may call tooling. It may collect context. It may follow a sequence. None of that is reliably enforced by passive instructions alone. - -A good skill is procedural without being bloated. It should tell the agent when to use it, what inputs it needs, what outputs it should create, and where deeper references live. That's the same pattern I keep coming back to in Copilot repos: **instructions define the lane; skills drive the truck**. - -### Use the split pattern when both are true - -A lot of teams get stuck because the real answer is not "instructions or skills." It's both, split on responsibility. - -If a topic has both governance and execution, split it this way: - -| If the content says... | Put it in... | Why | -| --- | --- | --- | -| "PRs must include testing notes" | Repo instructions | It's an always-on rule | -| "Generate testing notes from changed files" | Skill | It's an action | -| "Two approvals are required" | Repo instructions | It's policy | -| "Check approval state before merge" | Skill | It's a workflow step | -| "Use squash merge" | Repo instructions | It's the expected outcome | -| "Prepare the squash merge summary" | Skill | It's execution | - -That split keeps the rule visible and the workflow callable without turning one artifact into a junk drawer. - -The tradeoff is that you now maintain two layers instead of one. I still think that's the right time investment. The layers change at different speeds, and treating them as one thing hides that reality instead of simplifying it. - -## See the precedent in public repos - -I don't think these repos prove a universal law, and they are not solving exactly the same problem. Pre-commit is about hook lifecycle. ESLint is about rule discovery and enforcement. What I care about here is repo governance for human-plus-agent work. Even so, I kept finding teams that learned a similar separation independently: durable guidance in one place, task-specific execution in another. - -### OpenAI Agents Python says policies first, skills second - -[openai/openai-agents-python](https://github.com/openai/openai-agents-python) makes the split very explicit. Its root `AGENTS.md` opens with **"Policies & Mandatory Rules"** and then a **"Mandatory Skill Usage"** section that tells the agent when `$code-change-verification` or `$pr-draft-summary` must run. - -The execution layer lives in [`.agents/skills/`](https://github.com/openai/openai-agents-python/tree/main/.agents/skills). A concrete example is [`code-change-verification`](https://github.com/openai/openai-agents-python/tree/main/.agents/skills/code-change-verification), whose `SKILL.md` turns the policy into steps: run `make format`, then `make lint`, `make typecheck`, and `make tests`, or use the bundled script that does the sequence for you. - -That rhymes with my framing: `AGENTS.md` defines the lane, and the skill handles the trip. - -### Continue splits rules from review agents - -[continuedev/continue](https://github.com/continuedev/continue) uses different words, but the architecture is the same. The governance layer lives in [`.continue/rules/`](https://github.com/continuedev/continue/tree/main/.continue/rules), where files like [`programming-principles.md`](https://github.com/continuedev/continue/blob/main/.continue/rules/programming-principles.md) contain statements such as **"Use functional programming paradigms whenever possible."** - -The operational layer lives in [`.continue/agents/`](https://github.com/continuedev/continue/tree/main/.continue/agents). In [`test-coverage.md`](https://github.com/continuedev/continue/blob/main/.continue/agents/test-coverage.md), the repo doesn't restate style policy. It tells the agent what to do during review, including the wonderfully specific line **"Do NOT write tests yourself. The author knows the intended behavior best."** - -Similar split, different vocabulary: rules stay ambient, agents carry the task logic. - -### OpenHands keeps repo guidance at the root and release work in skills - -[OpenHands/OpenHands](https://github.com/OpenHands/OpenHands) follows the same pattern with root guidance plus task-specific skills. The repo-level guidance lives in [`AGENTS.md`](https://github.com/OpenHands/OpenHands/blob/main/AGENTS.md), while the executable playbooks live under [`.agents/skills/`](https://github.com/OpenHands/OpenHands/tree/main/.agents/skills). - -A good example is [`update-sdk`](https://github.com/OpenHands/OpenHands/tree/main/.agents/skills/update-sdk). Its `SKILL.md` says it should be used when someone asks to **"update SDK," "bump SDK version,"** or **"prepare a release"**, then gets brutally concrete with a table showing whether the task changes 5, 6, or 3 files and the exact lockfile commands to run. - -That is the same kind of separation I want in Copilot repos: repo guidance stays durable, and release choreography lives where an agent can actually invoke it. - -### Next.js documents the boundary inside the skill itself - -[vercel/next.js](https://github.com/vercel/next.js) is probably the most self-aware example I found. Its [`authoring-skills`](https://github.com/vercel/next.js/tree/canary/.agents/skills/authoring-skills) skill says it covers the relationship between **"always-loaded `AGENTS.md` and on-demand skills."** - -It gets even more direct a few lines later: create a skill when content is **"Too detailed for AGENTS.md"** or **"Only relevant for specific tasks,"** and keep it in `AGENTS.md` when it's **"a one-liner rule or guardrail every session needs."** I stole that wording mentally because it says the whole thing without making it dramatic. - -So even when the repo is teaching people how to author skills, it lands on the same boundary: guardrails in the ambient layer, procedures in the invoked one. - -### Microsoft and Azure repos show the pattern in Copilot instruction files too - -I also wanted examples from repos using Copilot instruction files directly, not just adjacent agent architectures. Microsoft has several public repos where the instruction layer is clearly being used as a governance surface for AI assistants working in complex systems and production codebases. - -Here's the pairing I wanted to see in public: instruction files setting the expectations, then concrete agent or skill artifacts carrying the work. - -- [Microsoft MCP Copilot Instructions](https://github.com/microsoft/mcp/blob/main/.github/copilot-instructions.md) — Governance rules for AI assistants working with the Model Context Protocol. - - Skills: [`agentic-workflows`](https://github.com/microsoft/mcp/blob/main/.github/agents/agentic-workflows.agent.md) routes workflow creation, debugging, and upgrades, and the repo also keeps executable skills under `.github/agents/` plus `tools/**/skills/`. -- [Microsoft Waza Copilot Instructions](https://github.com/microsoft/waza/blob/main/.github/copilot-instructions.md) — Agent-specific rules and behavioral guidelines. - - Skills: [`waza`](https://github.com/microsoft/waza/blob/main/skills/waza/SKILL.md) runs evals and benchmarks, [`waza-interactive`](https://github.com/microsoft/waza/blob/main/skills/waza-interactive/SKILL.md) handles conversational eval orchestration, and [`azd-publish`](https://github.com/microsoft/waza/blob/main/.github/skills/azd-publish/SKILL.md) owns the azd extension publish flow. -- [Azure SDK for JavaScript Copilot Instructions](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/copilot-instructions.md) — Governance for AI assistants working on production JavaScript libraries. - - Skills: [`archie`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md) for API and architecture review, [`dash`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/dash.agent.md) for performance review, [`dexter`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/dexter.agent.md) for dependency review, and [`scribe`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/scribe.agent.md) for documentation review. - -Those examples strengthen the same precedent from another angle: teams are publishing durable expectations in instruction files, then letting tools, workflows, and agent-specific routines handle execution elsewhere. - -## How the flow actually wires: instruction → agent → skill → prompt - -Looking deeper at those three Microsoft repos shows how the wiring actually works in practice. GitHub's [Copilot customization cheat sheet](https://docs.github.com/en/copilot/reference/customization-cheat-sheet) defines each layer clearly: - -- **Custom instructions**: "Always-on context that automatically applies to every interaction within its defined scope" -- **Custom agents**: "Specialist persona with its own instructions, tool restrictions, and context" -- **Agent skills**: "Folder of instructions, scripts, and resources that Copilot loads when relevant to a task" - -The flow is not instructions calling skills directly. Instructions provide ambient governance while agents route to skills or prompts. But the exact wiring differs by repo — and this is important to acknowledge. - -**Microsoft MCP**: The instruction file sets repo-wide rules. The `agentic-workflows` agent exists as a dispatcher, but the instruction file doesn't explicitly reference it. Instead, the agent independently routes based on task type (create/update/debug) and loads specialized prompts from external URLs (`gh-aw/create-agentic-workflow.md`, etc.). The pattern: **coexisting layers, not a single chain**. Instructions are ambient; agent dispatch is implicit or convention-driven. - -**Microsoft Waza**: The instruction file sets repo-wide rules. The `squad.agent.md` file is a real coordinator that spawns agents, but again, the instruction file doesn't reference it. Instead, `squad.agent.md` wires to `.squad/skills/` (not `.github/skills/`), and the coordinator loads skills based on routing decisions. The pattern: **instructions and agent coexist, but don't directly invoke each other**. The coordinator is the orchestrator, but it's activated outside the visible instruction layer. - -**Azure SDK for JavaScript**: The instruction file sets repo-wide rules. Reviewer agents (`archie`, `dash`, `dexter`, `scribe`) exist and explicitly load task-specific prompts. But the instruction file doesn't reference `sdk-workflow` or the agents directly. Instead, two parallel mechanisms work: (1) the shared `sdk-workflow` skill for package workflows, and (2) reviewer agents invoked either directly or via PR labels. Each reviewer agent loads `../prompts/architecture-review-guidelines.md`, etc. The pattern: **parallel systems**, not a single chain. - -The key insight from these repos: **they prove that instructions, agents, skills, and prompts can coexist and work together — but the orchestration is often implicit rather than explicit**. The file formats show clear separation of concerns, but the linkage between layers is not always visible in static analysis. - -The pattern in all three still follows the separation model that Copilot's documentation describes: - -``` -Custom instructions (always-on, repo-wide context) - ↓ -Custom agent (routing, dispatch logic, persona) - ↓ -Prompt or skill (task-specific expertise: guidelines, patterns, procedures) - ↓ -LLM receives: repo context + agent logic + domain expertise + tool definitions -``` - -But "orchestration" might be: -- **Explicit** (agent file explicitly references prompt URLs, like MCP) -- **Implicit** (convention-driven, like Waza's `.squad/` routing) -- **Parallel** (multiple independent systems, like Azure's workflows + agents) - -## Map the pattern to a real PR lifecycle - -PR lifecycle management is where this distinction stops being philosophical and starts paying rent. - -This is also where the failure modes get obvious fast. If I bury PR policy inside a long skill, a new contributor has to reverse-engineer which lines are rules and which lines are just one suggested sequence. If I bury the rule inside instructions instead, CI can still check for testing notes or required sections, but it cannot replay the workflow details that explain how to produce them. And once exceptions show up — docs-only changes, hotfix labels, screenshot updates — the all-in-one file turns into a negotiation instead of a guide. - -When I model PR work, I treat repo instructions as the governance contract. They answer questions like: - -- What should the PR title look like? -- Which sections are required in the description? -- Which approvals are mandatory? -- What merge strategy is allowed? -- What counts as done? - -Those are repo-level truths. They should be visible whether a human is writing the PR manually, Copilot is drafting it, or a future automation layer picks it up. - -Then I let the skill own the moving parts: - -- Create the PR body from the diff -- Check for missing testing notes -- Summarize CI failures -- Update the PR after review comments -- Prepare merge or release notes - -I keep the layering because long procedural text inside instructions rarely survives contact with reality. Instructions don't execute. They also don't enforce conditional rules well. "If the PR touches docs, then update screenshots unless the change is internal" is already skill territory. -The reverse mistake is just as common: teams put all PR rules in a skill because that's where the workflow feels tangible. The problem is that skills are not ambient. If nobody invokes the skill, nobody sees the rule. That's how you end up with one perfectly governed workflow and five side doors. - -The split pattern fixes both failure modes. Governance stays central and durable. Operations stay modular and reusable. In workshop terms, the wall chart tells everyone how the shop runs; the specialized jig helps you cut the joint cleanly. One without the other is either bureaucracy or improvisation. - -There's another reason I like this pattern: it scales with teams. Senior contributors can work from the governance layer because they already know the motions. Newer contributors or occasional collaborators can lean on the skill for the motions without missing the policy. That avoids over-regulation on one side and under-enforcement on the other. It also gives me a cleaner review question: am I changing the rule, or am I changing the way we carry it out? - -## Avoid the anti-patterns early - -The first anti-pattern is **procedural logic in instructions**. This usually starts with good intentions: people want consistency, so they paste an entire workflow into `.github/copilot-instructions.md`. The result is noisy guidance that is too long to be sharp and too passive to be dependable. Copilot may imitate pieces of it, but the artifact itself cannot execute, branch, recover, or verify. - -The second anti-pattern is **rules hidden inside skills**. This feels tidy until someone works around the skill, uses a different skill, or simply forgets the name. Then the policy disappears. Rules only work when they are ambient. - -The third anti-pattern is **ignoring context scope**. Repo instructions are for repository-wide or path-specific truth. Skills are for reusable capability. If the guidance depends heavily on a specific moment, tool state, or user request, I keep it out of instructions. - -One useful gut check: if removing the content would make the repo less governed, it was probably instruction material. If removing it would only make a task slower or more manual, it was probably skill material. - -## Wire the split into tooling - -This is where the distinction stops being tidy architecture and starts helping automation. - -Instructions are the easiest layer to lint and enforce because they read like policy. If the repo says PRs need testing notes, CI can check for testing notes no matter whether the PR body came from a human, a template, or a skill. The same goes for naming conventions, review requirements, documentation gates, and security constraints. The rules stay stable enough that automation can look for outcomes instead of trying to replay somebody's workflow. - -Skills are the layer that makes invocation and orchestration possible. They can expose a clear trigger, gather inputs, call scripts, branch on state, and produce artifacts. OpenAI's `code-change-verification` skill is a clean example: the rule lives in `AGENTS.md`, but the skill can actually run the verification stack. OpenHands does the same thing for release work by turning an SDK bump into a named procedure with exact files and commands. - -That's also why my repo structure keeps settling into `.github/skills/` and `.squad/`. I want the governance layer where I can review it, diff it, and eventually enforce it with policy checks. I want the execution layer where a person, a slash command, or an agent team can invoke it without dragging all of that procedural text into every session. - -## Keep the one-line rule nearby - -When I need a fast decision, I use the short version taped to the metaphorical tool cabinet: **If it reads like a rule, put it in instructions. If it reads like a workflow, put it in a skill.** - -That sentence is simple enough to use in code review, repo design, or onboarding. It also keeps debates short, which is an underrated form of governance. - -## Audit the repo you already have - -If your repo already feels tangled, I wouldn't start by rewriting everything. I'd start with an audit. - -### Ask these questions - -- Which guidance is always supposed to apply? -- Which files contain numbered steps, branching logic, or tool commands? -- Which skills quietly contain policy that should be visible everywhere? -- Which instructions are so long they stopped being useful? -- Which repeated tasks still depend on team memory instead of a reusable skill? - -### Start small and split one workflow - -Pick one messy area — PRs are perfect for this — and separate it into two artifacts: - -1. A slim instruction section with the rules. -2. A skill with the operational steps. - -Then test whether the separation makes the repo easier to understand. In my experience, it usually does immediately. The instructions get shorter. The skill gets more actionable. New contributors stop guessing where to put things. - -That's also where the time savings show up. You spend a little time on the split once, then stop re-explaining the same boundary every time someone adds a new automation. - -If you're not sure where to start, look for the longest instruction file in the repo. Long instruction files are often carrying work they were never designed to carry. Split out the first workflow you find and leave the rule behind. - -## The orchestration gap: theory vs practice - -While the three Microsoft repos show strong separation between instructions, agents, skills, and prompts, **the exact linkage varies**. Instructions don't always explicitly invoke agents. Agents don't always reference the instruction file. But the separation of concerns is real: governance lives in one place, execution in another. - -This is actually a feature. It means teams can evolve each layer independently. Instructions can change without breaking agents. Agents can be added without rewriting instructions. Skills can be refined without touching either. - -I've been validating these patterns with a local test suite that exercises the orchestration boundaries. The tests include file existence checks, linkage validation, and content classification. You can run them against your own repos to check whether the instructions-vs-skills split is actually happening. - -## Close the loop - -I like this distinction because it scales without becoming dramatic. Instructions hold the governance layer. Skills hold the execution layer. Together they give Copilot a clearer operating model and teams a cleaner way to grow capability without losing control. - -If you want to keep digging, [Exploring Copilot CLI Session Management to Improve Squad](https://dfberry.github.io/2026-04-16-session-storage-decision-guide) connects well with this one. I'm still interested in the same larger question underneath both posts: how do I make AI teams easier to govern without sanding off the parts that make them useful? Fun stuff! diff --git a/website/blog/2026-06-03-copilot-config-files-guide.md b/website/blog/2026-06-03-copilot-config-files-guide.md deleted file mode 100644 index acd75e23..00000000 --- a/website/blog/2026-06-03-copilot-config-files-guide.md +++ /dev/null @@ -1,412 +0,0 @@ ---- -slug: /2026-06-03-copilot-config-files-guide -authors: [dfberry] -date: 2026-06-03 -image: ./media/2026-06-03-copilot-config-files-guide/watercolor-1-layers-of-governance.png -canonical_url: https://dfberry.github.io/blog/2026-06-03-copilot-config-files-guide -custom_edit_url: null -sidebar_label: "2026.06.03 Copilot Config Files" -title: "Copilot Configuration Files: What They Are, Where They Live, and When to Use Them" -description: "A practical guide to `.github/copilot-instructions.md`, agents, skills, prompts, and workflows — what each one does, where to find accurate examples, and how they fit together." -draft: true -tags: - - copilot - - configuration - - repository-patterns - - reference -updated: 2026-06-02 09:30 PST -keywords: - - copilot-instructions - - copilot-agents - - copilot-skills - - copilot-prompts - - github-configuration - - ai-workflow ---- - -When I work with repos that use Copilot, I keep running into the same issue: people have these files scattered across `.github/`, but I'm not sure what each one does, why they exist separately, or how they're supposed to work together. - -I'll see `.github/copilot-instructions.md` and `.github/agents/` in the same repo, then a `prompts/` folder, then maybe a workflow file that looks half like YAML and half like agent instructions. The files exist, but my mental model doesn't. - -This guide is my attempt to create that mental model. I want to know what each file is for, where real repos keep them, and how they are used. - -![Three matryoshka nesting dolls opened and displayed from largest to smallest — representing the governance layers of instructions, agents, and skills](./media/2026-06-03-copilot-config-files-guide/watercolor-1-layers-of-governance.png) - -*At first glance, these configuration files look related — but how they nest relate to each other isn't obvious until you see the full picture.* - -## Quick Reference: The Six File Families - -| # | File | Lives at | Purpose | When to use | -|---|------|----------|---------|------------| -| 1 | **Copilot instructions** | `.github/copilot-instructions.md` | Repository-wide governance (always-on context) | "All Copilot work in this repo should follow these rules" | -| 2 | **Path-specific instructions** | `.github/instructions/*.instructions.md` | Scoped rules for specific directories or file patterns | "My monorepo has areas with different conventions" | -| 3 | **Agent definitions** | `.github/agents/` | Specialist persona with its own scope, tools, and constraints | "This task needs a reviewer or specialist with tighter boundaries" | -| 4 | **Skills** | `.github/skills/{name}/SKILL.md` | Reusable workflow package with instructions, resources, and optional scripts | "This is a repeatable procedure Copilot should know how to do" | -| 5 | **Prompt files / prompt docs** | Official prompt files: `.github/prompts/*.prompt.md`; repo-local docs often live in `.github/prompts/*.md` | Reusable prompt template or task-specific reference context | "I need either a reusable prompt in the IDE or a deeper reference doc for a specific task" | -| 6 | **Workflows** | `.github/workflows/` | GitHub Actions automation and remote triggers | "I need this to run on a label, schedule, dispatch, or PR event" | - -![Configuration files structure across the six .github families](./media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-v2.svg) - -*This structure diagram turns the six file families into one navigable map so you can see which pieces are baseline, specialized, reusable, or event-driven.* - -![Stylized .github home showing where instructions, agents, skills, prompts, and workflows live](./media/2026-06-03-copilot-config-files-guide/image-2-where-they-live.png) - -*The folder-house metaphor emphasizes that these files live together, but each room has a different job.* - - - -Those are the most commonly confused files. There are also `AGENTS.md` (an OpenAI/Anthropic agent convention — not a GitHub Copilot feature), hooks, and MCP configs. - -## The Copilot Instructions File: Governance Layer - -`/.github/copilot-instructions.md` is the ambient context that sits behind Copilot work in a repo. It's not something I invoke manually. It's the baseline. - -**What it contains:** -- Coding standards and conventions -- Architecture guidelines -- Documentation expectations -- Review requirements -- What "done" looks like -- Security constraints -- Naming conventions - -**Real examples:** - -[Microsoft MCP Copilot Instructions](https://github.com/microsoft/mcp/blob/main/.github/copilot-instructions.md) — a focused baseline file. The heading is `Coding Instructions for GitHub Copilot`, not "Comprehensive Overview," and it goes straight into always-apply rules, build expectations, and PR guidance. - -[Azure SDK for JavaScript Copilot Instructions](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/copilot-instructions.md) — a denser governance file. The Azure SDK guidance gets specific about API design, implementation choices, and when to explain a deviation from the house style. In my experience, this kind of baseline makes Copilot more likely to produce code aligned with review expectations. - -**When you use it in Copilot:** -- Open Copilot chat in the repo -- Ask it to "write a PR description" -- Copilot includes the repo instructions automatically - -**How long should it be?** -Short enough that a human can still scan it. MCP's file is compact. Azure's is more opinionated. If the instructions file starts reading like a runbook instead of repo policy, I move the task-specific detail somewhere else. - -**Key rule:** Instructions describe outcomes and standards. They are the repo's rules of engagement, not the step-by-step workflow. - -### Path-Specific Instructions: Scoped Rules - -I missed this feature entirely until I was reviewing a monorepo that had three different instruction files and I couldn't figure out why Copilot kept changing tone between the frontend and backend code. Turns out, Copilot supports **path-specific instruction files** in `.github/instructions/` — and they're additive with the repo-wide file. - -**Format:** `{name}.instructions.md` files inside `.github/instructions/` - -**Example structure:** -``` -.github/ - copilot-instructions.md # repo-wide (always-on) - instructions/ - frontend.instructions.md # applies to /frontend - backend.instructions.md # applies to /backend - tests.instructions.md # applies to test files -``` - -Each file uses YAML frontmatter with an `applyTo` key to declare which paths it covers: - -```yaml ---- -applyTo: "src/frontend/**" ---- -Use React functional components with TypeScript. -Prefer CSS modules over inline styles. -``` - -**Key behavior:** When I'm working in a file that matches a path-specific instruction, Copilot combines **both** the repo-wide instructions and the path-specific ones. It doesn't replace — it layers. This is different from how I initially assumed it worked. - -**When to use path-specific instructions instead of the repo-wide file:** -- Your monorepo has distinct language/framework areas with different conventions -- Test files need different guidance than production code -- API code has stricter rules than internal scripts - -**When NOT to use them:** -- Rules that apply everywhere (keep those in `copilot-instructions.md`) -- Task-specific procedures (those belong in skills) -- One-off guidance (just say it in chat) - -**Official docs:** [Adding path-specific custom instructions](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions#creating-path-specific-custom-instructions) - ---- - -## Agent Definitions: Specialist Persona - -`.github/agents/` is where I expect to find specialist agents — focused reviewers or operators with their own scope, tool boundaries, and output format. - -**What an agent file contains:** -- What the agent specializes in -- Which tools it can access -- Task-specific constraints -- Expected output format -- When to use it over the default assistant - -**Real examples:** - -[Azure SDK: archie.agent.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md) — architecture review specialist. The file defines the reviewer's purpose, allowed tools, scope, and output format. It also references `../prompts/architecture-review-guidelines.md` to load its review guidelines. - -[Azure SDK: scribe.agent.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/scribe.agent.md) — documentation review specialist. Same pattern, different charter: README, CHANGELOG, snippets, samples, and TSDoc. - -**How to invoke it:** -The exact path depends on the surface. GitHub's [customization cheat sheet](https://docs.github.com/en/copilot/reference/customization-cheat-sheet) is the clearest map I found: select the custom agent in the UI, use `/agent` in Copilot CLI, or reference the agent naturally in chat. - -**How it differs from instructions:** -- **Instructions:** Always-on, repo-wide governance -- **Agent:** Specialized, on-demand, with its own boundaries - -I don't need agents for every repo. A lot of projects are fine with instructions alone. But once I have a recurring task like architecture review or docs review, an agent gives that work a clear owner. - ---- - -## Skills: Reusable Procedures - -A skill is a folder with a `SKILL.md` file plus whatever supporting templates, scripts, or resources the workflow needs. GitHub's docs describe skills as packages that Copilot can load when they're relevant to a task. That detail matters. A skill is not just a long prompt. It's a reusable procedure. - -**What a skill contains:** -- When to use the skill -- What it does -- Input requirements -- Output expectations -- Links to deeper references -- Templates or helper assets -- Scripts or automation, if the workflow needs them - -**Real examples:** - -[OpenAI Agents Python: code-change-verification](https://github.com/openai/openai-agents-python/blob/main/.agents/skills/code-change-verification/SKILL.md) — a concrete verification skill. It tells Copilot when to run the verification stack and points to scripts that execute the checks. - -[Vercel Next.js: authoring-skills](https://github.com/vercel/next.js/blob/canary/.agents/skills/authoring-skills/SKILL.md) — a nice example of a skill that explains what belongs in a skill versus in `AGENTS.md`. - -**How it gets used:** -- In surfaces that support skills, Copilot may auto-load it when the task matches -- You can ask for that workflow explicitly -- A custom agent can rely on it as part of a larger procedure - -**Where they live:** -- `.github/skills/` — the GitHub Copilot canonical path -- `.agents/skills/` — the cross-agent open standard path (used by OpenAI, Vercel, and others) - -**Skill vs. Agent vs. Instructions — the mental model:** - -GitHub's documentation describes what each feature does, but doesn't frame the relationship as explicitly as I'd like. Here's my mental model: **Instructions set the rules. Agents decide. Skills execute.** This is my interpretation, not GitHub's official framing, but it helps me remember which tool to reach for. - -![Mental model hierarchy showing instructions governing agents and skills](./media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3-color.svg) - -*This cascade makes the control flow explicit: rules constrain decisions, and decisions choose the reusable execution path.* - ---- - -## Skills vs. Prompts: The Critical Difference - -This is the distinction that tripped me up most, because people use the word "prompt" to mean two different things. - -| Aspect | Skill | Prompt file / prompt doc | -|--------|-------|--------------------------| -| **What it is** | Agent-skill package with instructions, resources, and sometimes scripts | Either an official `.prompt.md` template or a repo-local markdown doc used as reference context | -| **How it gets used** | In supported surfaces, Copilot may auto-load it when relevant, or you ask for it explicitly | Official prompt files are typically user-selected or referenced in supported IDEs; repo-local docs can also be linked from agents or workflows | -| **What's inside** | Steps, commands, templates, helper assets | Examples, patterns, checklists, input variables, edge cases | -| **CLI support** | Yes | Official `.prompt.md` prompt files are IDE-focused, not Copilot CLI | - -**The caveat that matters:** Official GitHub prompt files use `.prompt.md` and are an IDE feature. Azure's `.github/prompts/*.md` files are different. They're repo-local reference docs that agents or workflows load, not the product feature GitHub documents as prompt files. - -That means my old rule of thumb was too neat. Prompts are not always passive reference, and skills are not always the only place with step-by-step guidance. The better distinction is this: skills are packaged workflows Copilot can use as skills; prompt files and prompt docs are reusable context. - -![Decision tree for choosing between skills, official prompts, prompt docs, or no file](./media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree-light.svg) - -*The decision tree compresses the distinction into one question sequence: reusable workflow first, reusable prompt second, reference doc third.* - ---- - -## Prompts: Task-Specific Expertise - -`.github/prompts/` is where many repos store task-specific context. Sometimes those files are official GitHub prompt files ending in `.prompt.md`. Sometimes, and this is what Azure JS does, they are plain markdown docs that reviewers load as guidance. - -**What a prompt file or prompt doc contains:** -- Patterns and examples -- Detailed guidance for a specific task -- Decision rules -- Known edge cases -- Sometimes input placeholders if it's an official prompt file - -**Real examples:** - -[Azure SDK: architecture-review-guidelines.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/prompts/architecture-review-guidelines.md) — a repo-local reference doc. It defines the review scope and checklist for architecture review, and [Archie points to it directly](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md). - -[GitHub gh-aw: create-agentic-workflow.md](https://github.com/github/gh-aw/blob/v0.71.1/.github/aw/create-agentic-workflow.md#L13-L25) — another repo-local guide. It explains the markdown workflow structure used by `gh-aw`. Useful context, yes. An official GitHub prompt-file feature, no. - -**How agents use them:** -Agents or workflows can read these docs at runtime. In Azure JS, the architecture review guidance also points back to `.github/copilot-instructions.md`, which is a nice example of the layers staying connected instead of duplicating each other. - -**Where they live:** -- Official prompt files: `.github/prompts/*.prompt.md` -- Repo-local reference docs: often `.github/prompts/*.md` -- Organized by task: architecture review, dependency review, release prep, and so on - -**Why separate files?** -Because the detail belongs close to the task, not smeared across every Copilot interaction. When instructions become hard to scan, moving task-specific context into separate files keeps the baseline clean. - ---- - -## Workflows: Automation Triggers - -`.github/workflows/` is standard GitHub Actions. I include it here because people often blame Copilot for behavior that is really coming from a workflow trigger. - -**What a workflow does:** -- Listens for triggers such as push, label, schedule, or manual dispatch -- Runs remote automation on GitHub -- Starts a reviewer or other automation path -- Posts status, comments, or checks back to the PR - -**Real example:** - -[Azure SDK for JavaScript reviewer workflows](https://github.com/Azure/azure-sdk-for-js/tree/main/.github/workflows) — not one big controller that fans everything out. Each reviewer has its own workflow file. [Archie](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md) and [Dexter](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md) both trigger on `pull_request_target` with `types: [labeled]`, and [Dash](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md) says plainly that its job is to review a PR for performance regressions. - -**How it connects to agents and skills:** -The workflow is the remote trigger. In Azure JS, each reviewer workflow posts its own findings back to the PR. In other repos, a workflow might also call a custom agent or load a skill, but that's not the part I can prove from this example. - ---- - -## How They Wire Together: A Real Workflow - -Here's the version of the Azure SDK flow I can actually defend with links. - -**1. A label triggers the run** -In Azure JS, the review workflows listen for `pull_request_target` with `types: [labeled]`, not for PR creation. You can see that in [archie.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md) and [dexter.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md). - -**2. Each reviewer has its own workflow** -[Archie](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md), [Dash](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md), [Dexter](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md), and [Scribe](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/scribe.md) are separate files under `.github/workflows/`. They can run independently when their trigger label appears. This is not one workflow spawning four reviewers in parallel. - -**3. The workflow itself states the review job** -[Dash](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md) literally says it reviews the PR for performance regressions and anti-patterns. Archie and Dexter follow the same pattern for architecture and dependency review. - -**4. Agent files and prompt docs are the reusable layer** -Separately from the workflow trigger, [archie.agent.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md) defines the architecture reviewer as a reusable custom agent and references `../prompts/architecture-review-guidelines.md`. That prompt doc then points back to the repo instructions in [architecture-review-guidelines.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/prompts/architecture-review-guidelines.md). - -**5. Findings land on the PR from each workflow** -[Archie](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md) and [Scribe](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/scribe.md) both declare `create-pull-request-review-comment` and `submit-pull-request-review` in `safe-outputs`, with run messages for the PR review lifecycle. So the accurate mental model is: each reviewer workflow posts its own findings. There isn't a separate "collector" workflow in this example. - -**6. Skills are adjacent, not proven by this example** -Skills still matter to the overall ecosystem, but Azure's review workflows are not the example I would use to claim that agents are invoking skills behind the scenes. If I want to show skills, I use an actual `SKILL.md` repo. - -That's the loop I trust: a label starts a workflow, the workflow runs the reviewer, the reviewer uses repo guidance, and comments come back to the PR. - -![Sequence diagram for the Azure SDK architecture review workflow](./media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-color.svg) - -*This sequence shows the asynchronous handoff from label to workflow to reviewer guidance and back to a PR comment.* - ---- - -## Using Copilot with These Files: Chat and CLI - -### In Copilot Chat (Browser or VS Code) - -**Scenario:** You're in a repo and you open Copilot chat. - -``` -You: write a PR description -``` - -Copilot reads `.github/copilot-instructions.md` and picks up things like: -- PR title format -- Required sections -- Review expectations - -Result: the draft is much more likely to match the repo's stored rules. - -**Scenario 2:** You want the specialist reviewer. - -``` -You: use the archie agent to review my API changes -``` - -Depending on the surface, you might select `archie` in the agent picker, use `/agent` in Copilot CLI, or reference it naturally in chat. The important part is the same: the agent file gives that review task its own scope and constraints. - -### In Copilot CLI - -**Scenario:** You're working locally and you want a code review from the terminal. - -```shell -copilot -/review focus on bugs and security issues in my current changes -``` - -GitHub documents `/review` as the CLI code review path in its [Copilot CLI docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) and [agentic code review guide](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review). This is the replacement for the old `gh copilot pr-review` mental model I had in my head. - -**Scenario 2:** You want to trigger the remote GitHub Actions reviewer from your terminal. - -```shell -gh workflow run archie.md -f item_number=42 -``` - -That command is a **remote workflow dispatch through GitHub CLI**, not local Copilot behavior. Azure's reviewer workflows expose `workflow_dispatch` with an `item_number` input in [archie.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md), so `gh` can start the run on GitHub. - ---- - -## Decision Table: Which File for What? - -![Decision tree for placing work in instructions, agents, skills, prompts, or workflows](./media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree-light.svg) - -*This placement tree turns the file choice into a routing problem: match the task shape, then drop it in the right folder.* - -| I need to... | Put it in... | Why | -|--------------|--------------|-----| -| Set coding standards | Copilot instructions | Always-on, repo-wide governance | -| Require testing notes on all PRs | Copilot instructions | It's a rule, not a workflow | -| Automate PR review on labels | Workflows + reviewer definitions | Labels are a GitHub Actions trigger, and the reviewer needs its own scope | -| Store detailed architecture patterns | Prompt docs | Too bulky for baseline instructions; reviewers can load them when needed | -| Make code generation or verification repeatable | Skills | Copilot can load the packaged workflow when the task matches | -| Handle a one-time task | Chat | Some work doesn't need a file at all | - ---- - -## Minimal Repo Setup - -If I'm starting fresh and I don't want to overengineer this, I keep it boring. - -**Minimal viable setup:** -- `.github/copilot-instructions.md` (recommended baseline) -- No agents yet unless I have a recurring specialist task -- No skills yet unless I keep repeating the same workflow -- No prompt docs yet unless the task-specific context is making the instructions file noisy - -**As the repo grows:** -- Add agents when a task needs its own tool restrictions or review charter -- Add skills when a workflow deserves packaging -- Add prompt docs when a reviewer or task needs deeper context than the baseline file should carry - -Start minimal, then add layers only when each layer removes confusion. - ---- - -## How to Find Examples in Real Repos - -Here are the examples I would study first. - -**Azure SDK for JavaScript** — the clearest end-to-end example I found -- Instructions baseline: [`.github/copilot-instructions.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/copilot-instructions.md) -- Architecture reviewer: [`.github/agents/archie.agent.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md) -- Prompt doc Archie loads: [`.github/prompts/architecture-review-guidelines.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/prompts/architecture-review-guidelines.md) -- Performance reviewer workflow: [`.github/workflows/dash.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md) -- Dependency reviewer workflow: [`.github/workflows/dexter.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md) -- Documentation reviewer: [`.github/agents/scribe.agent.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/scribe.agent.md) - -**Microsoft MCP** — a readable baseline instructions file -- Instructions: [`.github/copilot-instructions.md`](https://github.com/microsoft/mcp/blob/main/.github/copilot-instructions.md) - -**GitHub gh-aw** — a good example of repo-local workflow guidance that looks prompt-like -- Workflow authoring guide: [`.github/aw/create-agentic-workflow.md` lines 13-25](https://github.com/github/gh-aw/blob/v0.71.1/.github/aw/create-agentic-workflow.md#L13-L25) - -**Vercel Next.js** — useful for skill design patterns -- Skill example: [`.agents/skills/authoring-skills/SKILL.md`](https://github.com/vercel/next.js/blob/canary/.agents/skills/authoring-skills/SKILL.md) - - ---- - -## The One-Sentence Rule - -![Woman viewing four landscape paintings on a wall — the same mountain at sunrise, noon, rain, and sunset — representing the config files seen from different angles](./media/2026-06-03-copilot-config-files-guide/watercolor-5-putting-it-together.png) - -If I'm stuck deciding where something belongs, this is still the fastest check I know: -- If it reads like a rule, put it in instructions. -- If it reads like a reusable workflow, put it in a skill. -- If it reads like task-specific context, put it in a prompt doc or prompt file. -- If it has to run on GitHub events, put it in a workflow.** - diff --git a/website/blog/authors.yml b/website/blog/authors.yml deleted file mode 100644 index 0793f6ed..00000000 --- a/website/blog/authors.yml +++ /dev/null @@ -1,2 +0,0 @@ -dfberry: - name: dfberry diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-1-mental-model-v3.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-1-mental-model-v3.svg deleted file mode 100644 index be23c169..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-1-mental-model-v3.svg +++ /dev/null @@ -1,68 +0,0 @@ - - Layers of Governance - A monochrome governance mental model with instructions above the rings, agents to the right, skills to the lower left, and a three-line center summary inside the inner circle. - - - - - - - - - INSTRUCTIONS - Repo rules and guardrails - shape the whole space - - - - - AGENTS - Interpret rules for - the current context - - - - - SKILLS - Carry out reusable - steps and assets - - - - - - - - - - - - - - Instructions set rules. - Agents decide. - Skills execute. - - - - Layers of Governance - Rules constrain decisions, then reusable skills carry out the work. - - - - - - - - \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-2-configuration-files-structure-light.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-2-configuration-files-structure-light.svg deleted file mode 100644 index ebf8f86d..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-2-configuration-files-structure-light.svg +++ /dev/null @@ -1 +0,0 @@ -workflows/prompts/skills/agents/Governancegovernsgovernsgovernsgovernsloadstriggerscan triggershares reference patterns with.github/copilot-instructions.mdarchie.agent.mdscribe.agent.md{name}/SKILL.mdarchitecture-review-guidelines.md*.prompt.mdarchie.yml / *.yml \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-2-configuration-files-structure.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-2-configuration-files-structure.svg deleted file mode 100644 index 23ef79b0..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-2-configuration-files-structure.svg +++ /dev/null @@ -1 +0,0 @@ -

workflows/

prompts/

skills/

agents/

Governance

governs

governs

governs

governs

loads

triggers

can trigger

shares reference patterns with

.github/

copilot-instructions.md

archie.agent.md

scribe.agent.md

{name}/SKILL.md

architecture-review-guidelines.md

*.prompt.md

archie.yml / *.yml

 \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-2-file-families-v3.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-2-file-families-v3.svg deleted file mode 100644 index 86864991..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-2-file-families-v3.svg +++ /dev/null @@ -1 +0,0 @@ -

prompts/

agents/

skills/

workflows/

Governance

governs

governs

governs

governs

loads

triggers

can trigger

shares reference patterns with

.github/

copilot-instructions.md

archie.yml / *.yml

{name}/SKILL.md

archie.agent.md

scribe.agent.md

architecture-review-guidelines.md

*.prompt.md

 \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree-light.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree-light.svg deleted file mode 100644 index 9f3102c2..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree-light.svg +++ /dev/null @@ -1 +0,0 @@ -YesNoYesNoYesNoNeed reusable workflow?Need reusable user-selected template?Need deeper task reference context?Use SkillUse Official PromptUse Prompt DocNo file needed \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree.svg deleted file mode 100644 index 9565a0d6..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree.svg +++ /dev/null @@ -1 +0,0 @@ -

Yes

No

Yes

No

Yes

No

Need reusable workflow?

Need reusable user-selected template?

Need deeper task reference context?

Use Skill

Use Official Prompt

Use Prompt Doc

No file needed

 \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-3-top-level-routing-v3.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-3-top-level-routing-v3.svg deleted file mode 100644 index 5586f509..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-3-top-level-routing-v3.svg +++ /dev/null @@ -1 +0,0 @@ -

Yes

No

Yes

No

Yes

No

Need reusable workflow?

Need reusable user-selected template?

Need deeper task reference context?

Use Skill

Use Official Prompt

Use Prompt Doc

No file needed

 \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-4-agent-routing-v3.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-4-agent-routing-v3.svg deleted file mode 100644 index e22782ce..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-4-agent-routing-v3.svg +++ /dev/null @@ -1 +0,0 @@ -Pull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperAsync GitHub-hosted runAdd archie label to PRTrigger pull_request_target[labeled]Load reviewer definitionLoad architecture checklistReturn guidance + repo linksArchitecture review findingsCreate review + commentsComment appears on PR \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-light.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-light.svg deleted file mode 100644 index fe3a7294..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-light.svg +++ /dev/null @@ -1 +0,0 @@ -Pull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperPull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperAsync GitHub-hosted runAdd archie label to PRTrigger pull_request_target[labeled]Load reviewer definitionLoad architecture checklistReturn guidance + repo linksArchitecture review findingsCreate review + commentsComment appears on PR \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger.svg deleted file mode 100644 index 1dc7aa76..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger.svg +++ /dev/null @@ -1 +0,0 @@ -Pull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperPull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperAsync GitHub-hosted runAdd archie label to PRTrigger pull_request_target[labeled]Load reviewer definitionLoad architecture checklistReturn guidance + repo linksArchitecture review findingsCreate review + commentsComment appears on PR \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-5-file-placement-decision-tree-light.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-5-file-placement-decision-tree-light.svg deleted file mode 100644 index c864bbdc..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-5-file-placement-decision-tree-light.svg +++ /dev/null @@ -1 +0,0 @@ -What's the task?Coding standards.github/copilot-instructions.mdRecurring specialist task.github/agents/Repeatable workflow.github/skills/One-time prompt or reference.github/prompts/Schedule, label, or PR event.github/workflows/ \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-5-file-placement-decision-tree.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-5-file-placement-decision-tree.svg deleted file mode 100644 index 51cc3228..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-5-file-placement-decision-tree.svg +++ /dev/null @@ -1 +0,0 @@ -

What's the task?

Coding standards
.github/copilot-instructions.md

Recurring specialist task
.github/agents/

Repeatable workflow
.github/skills/

One-time prompt or reference
.github/prompts/

Schedule, label, or PR event
.github/workflows/

 \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-5-input-parsing-v3.svg b/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-5-input-parsing-v3.svg deleted file mode 100644 index 6e935621..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/diagram-5-input-parsing-v3.svg +++ /dev/null @@ -1 +0,0 @@ -

What's the task?

Coding standards
.github/copilot-instructions.md

Recurring specialist task
.github/agents/

Repeatable workflow
.github/skills/

One-time prompt or reference
.github/prompts/

Schedule, label, or PR event
.github/workflows/

 \ No newline at end of file diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/generate-images.sh b/website/blog/media/2026-05-31-copilot-config-files-guide/generate-images.sh deleted file mode 100755 index b081f842..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/generate-images.sh +++ /dev/null @@ -1,178 +0,0 @@ -#!/bin/bash -# Image Generation Script for Copilot Configuration Files Guide Blog Post -# Generated: 2026-05-31 -# Purpose: Regenerate all SVG diagrams, PNG infographics, and watercolor illustrations -# -# All commands use the Stable Diffusion image generation pipeline. -# Prompt source: image-specs-and-prompts.md and watercolor-prompts.md -# Device auto-detection: uses CUDA if available, MPS on Apple Silicon, falls back to CPU -# -# Usage: bash generate-images.sh [filter] -# filter (optional): "svg", "png", or "watercolor" to run only that subset -# Example: bash generate-images.sh watercolor - -set -e - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -OUTPUT_DIR="$SCRIPT_DIR" -SEED_BASE=52 - -# Colors for terminal output -GREEN='\033[0;32m' -BLUE='\033[0;34m' -NC='\033[0m' # No Color - -echo -e "${BLUE}=== Copilot Config Files Guide: Image Generation ===${NC}\n" - -# ============================================================================ -# SVG DIAGRAMS (Mermaid → SVG export) -# ============================================================================ - -generate_svg_diagrams() { - echo -e "${GREEN}Generating SVG diagrams...${NC}\n" - - # Diagram 1: Mental Model (three rings with cards) - echo "1. diagram-1-mental-model-v3.svg" - echo " Cards: INSTRUCTIONS, AGENTS, SKILLS around three nested rings" - echo " Color: White bg, black text, light gray lines (#cccccc), light fills (#f5f7fa)" - echo " ✓ Manual Mermaid export or direct SVG creation\n" - - # Diagram 2: File Families Decision Tree - echo "2. diagram-2-file-families-v3.svg" - echo " Structure: Root node → 5 file family branches (instructions, agents, skills, prompts, workflows)" - echo " Labels: concise routing decisions" - echo " ✓ Manual Mermaid export or direct SVG creation\n" - - # Diagram 3: Skills vs. Prompts Decision Tree - echo "3. diagram-3-top-level-routing-v3.svg" - echo " Decision flow: Does it reuse? → skills | Is it situational? → prompts" - echo " ✓ Manual Mermaid export or direct SVG creation\n" - - # Diagram 4: Agent Routing (agents → handlers → channels) - echo "4. diagram-4-agent-routing-v3.svg" - echo " Flow: Multiple agents dispatched based on role + task type" - echo " ✓ Manual Mermaid export or direct SVG creation\n" - - # Diagram 5: File Placement Decision Tree - echo "5. diagram-5-input-parsing-v3.svg" - echo " Decision: Where do these config files live? (.github, root, dotenv, etc.)" - echo " ✓ Manual Mermaid export or direct SVG creation\n" -} - -# ============================================================================ -# PNG INFOGRAPHICS (Simple stable-diffusion generation) -# ============================================================================ - -generate_png_infographics() { - echo -e "${GREEN}Generating PNG infographics...${NC}\n" - - # Image 1: Quick Reference Table (visual rendering of file families table) - echo "📋 image-1-quick-reference-table.png" - python3 simple_config.py \ - --prompt "A clean reference table layout showing file families, descriptions, and locations in a organized grid format, light background, black text, minimal design, professional appearance, no decorative elements, clear typography" \ - --preset production \ - --style infographic \ - --size blog-hero \ - --seed $((SEED_BASE + 1)) \ - --output "$OUTPUT_DIR/image-1-quick-reference-table.png" \ - --modifier clarity \ - --modifier organized - echo " ✓ Generated\n" - - # Image 2: Where They Live (file system layout visualization) - echo "📂 image-2-where-they-live.png" - python3 simple_config.py \ - --prompt "Folder and file structure diagram showing .github directory, root config files, environment variables, visual hierarchy with clear separation between file types, light background, monochrome, professional infographic style, no text labels inside boxes" \ - --preset production \ - --style infographic \ - --size blog-hero \ - --seed $((SEED_BASE + 2)) \ - --output "$OUTPUT_DIR/image-2-where-they-live.png" \ - --modifier structure \ - --modifier clarity - echo " ✓ Generated\n" -} - -# ============================================================================ -# WATERCOLOR ILLUSTRATIONS (Story-driven, character-focused) -# ============================================================================ - -generate_watercolors() { - echo -e "${GREEN}Generating watercolor illustrations...${NC}\n" - - # Watercolor 1: Mapping the Five File Families - echo "🎨 watercolor-1-mapping-file-families.png" - python3 simple_config.py \ - --prompt "Normal woman at desk sorting five distinct stacks of repository files into order, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed $((SEED_BASE + 3)) \ - --output "$OUTPUT_DIR/watercolor-1-mapping-file-families.png" \ - --modifier painterly \ - --modifier loose - echo " ✓ Generated\n" - - # Watercolor 2: Understanding the Layers - echo "🎨 watercolor-2-understanding-layers.png" - python3 simple_config.py \ - --prompt "Normal woman examining nested transparent layers of governance documents, comparing one layer to another, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed $((SEED_BASE + 4)) \ - --output "$OUTPUT_DIR/watercolor-2-understanding-layers.png" \ - --modifier painterly \ - --modifier loose - echo " ✓ Generated\n" - - # Watercolor 3: Tracing a Real Workflow - echo "🎨 watercolor-3-tracing-workflow.png" - python3 simple_config.py \ - --prompt "Normal woman in home office tracing a path between pinned repository notes and workflow folders, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed $((SEED_BASE + 5)) \ - --output "$OUTPUT_DIR/watercolor-3-tracing-workflow.png" \ - --modifier painterly \ - --modifier loose - echo " ✓ Generated\n" -} - -# ============================================================================ -# MAIN EXECUTION -# ============================================================================ - -FILTER="${1:-all}" - -case "$FILTER" in - svg) - generate_svg_diagrams - ;; - png) - generate_png_infographics - ;; - watercolor) - generate_watercolors - ;; - all) - generate_svg_diagrams - generate_png_infographics - generate_watercolors - ;; - *) - echo "Unknown filter: $FILTER" - echo "Usage: bash generate-images.sh [svg|png|watercolor|all]" - exit 1 - ;; -esac - -echo -e "${GREEN}✓ Image generation complete!${NC}\n" -echo "Generated files are in: $OUTPUT_DIR" -echo "" -echo "Next steps:" -echo "1. Review all generated images in the media folder" -echo "2. Compare against image-specs-and-prompts.md specifications" -echo "3. Update blog post references if needed" -echo "4. Commit all images with: git add media/2026-05-31-copilot-config-files-guide/*.{svg,png}" diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/image-2-where-they-live.png b/website/blog/media/2026-05-31-copilot-config-files-guide/image-2-where-they-live.png deleted file mode 100644 index 8b15cf92..00000000 Binary files a/website/blog/media/2026-05-31-copilot-config-files-guide/image-2-where-they-live.png and /dev/null differ diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/image-generation-reference.md b/website/blog/media/2026-05-31-copilot-config-files-guide/image-generation-reference.md deleted file mode 100644 index 14045fbb..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/image-generation-reference.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -title: "Image Generation CLI Reference" ---- - -# Image Generation Commands Reference - -This document contains all CLI commands for regenerating the blog post's visual assets. Use this when modifying prompts, regenerating specific images, or troubleshooting output. - -## Quick Start - -```bash -# Regenerate all images -bash generate-images.sh all - -# Regenerate only watercolors -bash generate-images.sh watercolor - -# Regenerate only PNG infographics -bash generate-images.sh png - -# Regenerate only SVG diagrams -bash generate-images.sh svg -``` - ---- - -## Image Specifications - -### Design System (All Images) -- **Background:** Light (#ffffff or #f5f7fa) -- **Text:** Black (#000000) -- **Lines/Connectors:** Light gray (#cccccc) -- **Size:** 1536×1024 pixels (blog-hero standard) -- **Text Constraint:** No overlapping text; minimum 8-24px clearance from shapes -- **Style:** Monochrome, no gradients, no accent colors - -### Color Schema (Watercolors Only) -- **Technique:** Soft wet-on-wet washes -- **Texture:** Visible paper texture -- **Tones:** Warm, muted palette -- **Brushwork:** Loose, painterly -- **Text:** None - ---- - -## SVG Diagrams - -### 1. Mental Model (Three Rings + Cards) -``` -diagram-1-mental-model-v3.svg -``` -- **Content:** Three nested rings (Instructions → Agents → Skills cascade) -- **Cards:** INSTRUCTIONS (top), AGENTS (right), SKILLS (left) with light backgrounds (#f5f7fa) -- **Layout:** Symmetric, centered -- **Clearance:** 24px minimum from text to shapes - -**Manual regeneration:** -1. Export from Mermaid diagram editor -2. Post-process: ensure card fills are #f5f7fa, no pill labels -3. Verify clearance zones: top card INSTRUCTIONS | right card AGENTS | left card SKILLS | center copy - -### 2. File Families Decision Tree -``` -diagram-2-file-families-v3.svg -``` -- **Root Node:** "Config Files" -- **Branches:** Instructions | Agents | Skills | Prompts | Workflows -- **Edge Labels:** Routing decisions (2-3 words max) -- **Layout:** Hierarchical tree - -### 3. Skills vs. Prompts Decision Tree -``` -diagram-3-top-level-routing-v3.svg -``` -- **Decision Point:** "Does it reuse across many prompts?" -- **Left path:** "Yes" → Skills -- **Right path:** "No" → Prompts -- **Layout:** Binary decision flow - -### 4. Agent Routing -``` -diagram-4-agent-routing-v3.svg -``` -- **Flow:** Agents (by role + task type) → Handlers → Execution Channels -- **Elements:** Agent boxes, handler boxes, channel endpoints -- **Connectors:** Labeled edges showing routing logic - -### 5. File Placement Decision Tree -``` -diagram-5-input-parsing-v3.svg -``` -- **Question:** "Where do these files live?" -- **Decisions:** Scope (repo-wide vs. per-branch) → Location (.github vs. root vs. dotenv) -- **Leaf nodes:** Final placement recommendations - ---- - -## PNG Infographics - -### Image 1: Quick Reference Table -```bash -python3 simple_config.py \ - --prompt "A clean reference table layout showing file families, descriptions, and locations in a organized grid format, light background, black text, minimal design, professional appearance, no decorative elements, clear typography" \ - --preset production \ - --style infographic \ - --size blog-hero \ - --seed 53 \ - --output outputs/image-1-quick-reference-table.png \ - --cpu \ - --modifier clarity \ - --modifier organized -``` - -**What it shows:** -- Structured table of file families (Instructions, Agents, Skills, Prompts, Workflows) -- Columns: Family Name | Purpose | File Name(s) | Location -- Professional grid layout, no decorative elements - -### Image 2: Where They Live (File System Structure) -```bash -python3 simple_config.py \ - --prompt "Folder and file structure diagram showing .github directory, root config files, environment variables, visual hierarchy with clear separation between file types, light background, monochrome, professional infographic style, no text labels inside boxes" \ - --preset production \ - --style infographic \ - --size blog-hero \ - --seed 54 \ - --output outputs/image-2-where-they-live.png \ - --cpu \ - --modifier structure \ - --modifier clarity -``` - -**What it shows:** -- Visual tree of `.github/` directory structure -- Root-level config files (copilot.json, etc.) -- Environment variable locations -- Clear visual separation of file types - ---- - -## Watercolor Illustrations - -Each watercolor uses **tight, focused prompts** (~20 words) to avoid competing visual details. See `watercolor-prompts.md` for narrative context. - -### Watercolor 1: Mapping the Five File Families -```bash -python3 simple_config.py \ - --prompt "Normal woman at desk sorting five distinct stacks of repository files into order, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed 55 \ - --output outputs/watercolor-1-mapping-file-families.png \ - --cpu \ - --modifier painterly \ - --modifier loose -``` - -**Narrative:** Opening section — woman physically organizing the five file families into one usable mental model. - -**Key elements:** -- Normal woman (average features, practical clothes) -- Desk with papers/folders -- Five distinct stacks being sorted -- Warm, loose watercolor technique - -### Watercolor 2: Understanding the Layers -```bash -python3 simple_config.py \ - --prompt "Normal woman examining nested transparent layers of governance documents, comparing one layer to another, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed 56 \ - --output outputs/watercolor-2-understanding-layers.png \ - --cpu \ - --modifier painterly \ - --modifier loose -``` - -**Narrative:** Instructions, Agents, Skills section — woman examining nested layers to understand how they sit together. - -**Key elements:** -- Woman at desk -- Transparent/translucent layers (trays or sheets) -- One layer lifted/compared to another -- Focused, curious expression -- Watercolor technique - -### Watercolor 3: Tracing a Real Workflow -```bash -python3 simple_config.py \ - --prompt "Normal woman in home office tracing a path between pinned repository notes and workflow folders, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed 57 \ - --output outputs/watercolor-3-tracing-workflow.png \ - --cpu \ - --modifier painterly \ - --modifier loose -``` - -**Narrative:** Azure workflow section and decision table — woman tracing a concrete path from abstract categories to real implementation. - -**Key elements:** -- Woman at home office -- Pinned notes on wall or board -- Workflow folders/documents -- Following a line/path between elements -- Hands-on, investigative posture -- Watercolor technique - ---- - -## Prompt Engineering Rules - -### Watercolor Prompts (Critical) -- **Length:** Keep to ~20 words (PRDs blog style) -- **Structure:** `[Subject] [one clear focal action] [technique keywords] [result constraint]` -- **Avoid:** Multiple competing actions, vague subjects, text overlays -- **Character:** Always "normal woman" (not beautified, not styled) -- **Setting:** Grounded work environment (desk, home office, etc.) -- **Technique keywords:** "watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" - -### PNG Infographic Prompts -- **Length:** 15–25 words -- **Style:** "light background, black text, minimal design, professional" -- **Avoid:** Decorative elements, gradients, accent colors -- **Modifiers:** `--modifier clarity`, `--modifier organized`, `--modifier structure` - -### Common Modifiers -| Modifier | Effect | -|----------|--------| -| `painterly` | Loose, artistic technique | -| `loose` | Relaxed brushwork (watercolor) | -| `clarity` | Sharp focus, clear text | -| `organized` | Clean layout, grid structure | -| `structure` | Visual hierarchy, spatial relationships | -| `crisper` | Defined edges, precision | -| `more-detailed` | Additional visual information | - ---- - -## Seed Values - -**Base seed:** 52 (assigned at start of image generation batch) - -**Increment:** +1 for each subsequent image in order: -- PNG Image 1: seed 53 -- PNG Image 2: seed 54 -- Watercolor 1: seed 55 -- Watercolor 2: seed 56 -- Watercolor 3: seed 57 - -**Why:** Consistent but varied results. Change the base seed (e.g., 100, 200) to explore different style directions while keeping relative relationships. - ---- - -## Troubleshooting - -### Images Look Poor Quality or Confusing -**Likely cause:** Prompt is too verbose or has competing visual elements. - -**Fix:** Tighten the prompt. Remove secondary actions. Focus on ONE clear subject + ONE action. Example: -- ❌ "Woman at desk working on files, thinking deeply, with visible code snippets and diagrams around her" -- ✅ "Woman at desk sorting five distinct stacks of repository files, watercolor illustration" - -### Text Overlaps Other Elements -**Likely cause:** Mermaid diagram text clearance zones not respected. - -**Fix:** Review `image-specs-and-prompts.md` clearance constraints. Ensure 8–24px minimum space around all text. - -### Watercolor Colors Don't Match PRDs Blog Style -**Likely cause:** Seed or modifier settings differ. - -**Fix:** Check exact seed value and modifiers (`--modifier painterly --modifier loose`). Compare against reference images from PRDs blog. If still incorrect, adjust prompt to be more specific about tone (e.g., "ochre and soft blue undertones"). - -### SVG Diagrams Not Rendering in Docusaurus -**Likely cause:** SVG file size, missing xmlns, or embedded elements. - -**Fix:** Verify SVG has `xmlns="http://www.w3.org/2000/svg"`. Check file size (should be <50KB). Test rendering locally: `npm start` in website directory. - ---- - -## File Organization - -All images live in: -``` -website/blog/media/2026-05-31-copilot-config-files-guide/ -``` - -**Naming convention:** -- SVGs: `diagram-{N}-{kebab-case-name}-v3.svg` -- PNG infographics: `image-{N}-{kebab-case-name}.png` -- Watercolors: `watercolor-{N}-{kebab-case-name}.png` - -**Referenced in blog post:** -```markdown -![Alt text](./media/2026-05-31-copilot-config-files-guide/diagram-1-mental-model-v3.svg) -![Alt text](./media/2026-05-31-copilot-config-files-guide/watercolor-1-mapping-file-families.png) -``` - ---- - -## Next Steps - -1. **Review regenerated images** against `image-specs-and-prompts.md` -2. **Integrate into blog post** (markdown image references) -3. **Test Docusaurus build:** `npm run build` in website directory -4. **Commit all media:** `git add media/2026-05-31-copilot-config-files-guide/` -5. **Publish blog post** when ready - ---- - -## Reference Files - -- **`watercolor-prompts.md`** — Narrative context and exact prompts for all 3 watercolor illustrations -- **`image-specs-and-prompts.md`** — Master reference with production specs, layout rationale, and modification guides for all 7 visual assets -- **`watercolor-manifest.md`** — Tracking file for watercolor generation status -- **`generate-images.sh`** — Bash script to regenerate all images with one command diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/image-specs-and-prompts.md b/website/blog/media/2026-05-31-copilot-config-files-guide/image-specs-and-prompts.md deleted file mode 100644 index 249318c4..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/image-specs-and-prompts.md +++ /dev/null @@ -1,440 +0,0 @@ -# Image Specs and Prompts - -These specs were extracted from the existing 7 assets in this folder. - -Notes: -- For SVGs, I read the source and reconstructed editable structure. -- For PNGs, I examined the rendered image and provide a faithful editable production spec. -- I did **not** find a separate original prompt file for these 7 assets in the repo, so the PNG sections include an extracted **specification/prompt** rather than a repo-authored source prompt. - ---- - -## 1. `diagram-1-mental-model.svg` - -**Type:** custom SVG composition - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Canvas:** `viewBox="0 0 807 646"` -**Title in file:** `Layers of Governance` - -Production specification (revised for text layout) -This is not a native Mermaid diagram; it is a custom SVG built around the post's mental model: instructions create the boundary, agents interpret inside it, and skills sit at the execution center. - -```text -Canvas: viewBox 0 0 807 646 on a white background (#ffffff). -Use black text only (#000000), light-gray strokes (#cccccc), and white/light fills only where specified. -Treat the composition as four protected text zones: the top INSTRUCTIONS card, the right AGENTS card, the left SKILLS card, and the inner-circle center copy. Text from one zone must never enter another zone. -Build the diagram around a centered three-ring system. Keep generous negative space around the rings so the rings read as layers, not collisions. -Top card: place a rounded rectangle centered above the rings for INSTRUCTIONS with a soft light fill such as #f5f7fa (or #f0f4f8) so it pops against the white canvas while staying subtle. Keep at least 24px of vertical gap between the bottom of this card and any connector. Inside the card, use 18-20px side padding, at least 16px top/bottom padding, a bold all-caps heading, then two short lines of body copy. If the text feels tight, increase card height before reducing spacing. -Right card: place a rounded rectangle to the right of the rings for AGENTS using the same soft light fill (#f5f7fa or #f0f4f8). Keep at least 24px of horizontal clearance between the card edge and the outer ring. Put the AGENTS label inside the card as the card heading, then keep the body copy inside the card with 18-20px internal padding and no more than two short lines. -Left card: place a rounded rectangle lower-left for SKILLS using the same soft light fill (#f5f7fa or #f0f4f8). Keep at least 24px of clearance from the outer ring and enough width that the supporting copy stays fully inside the card. Put the SKILLS label inside the card as the card heading. Increase card height or width instead of squeezing text. -Connectors: use thin light-gray connectors, but route them so they stop before any text area. No connector may pass under or through a text label. -Center copy: place three stacked lines inside the inner circle only. Keep all center text at least 16px away from the inner circle boundary on every side. Use shorter lines and a slightly smaller size than the card headings so the hierarchy stays clear. -Typography for web-sized viewing (~600px content column): card headings should read like 18-20px, supporting copy like 13-15px, center copy like 15-17px, title like 24-28px, and subtitle like 14-16px. -Bottom title block: keep the title, subtitle, and three dots centered below the diagram with enough separation that the caption reads as a footer, not part of the rings. -Overall style: minimal editorial explainer, monochrome, airy, and legible at small blog-column display sizes, with softly tinted cards on a white canvas for contrast. -``` - -### What each element represents -- **Top card:** the always-on repo rules and guardrails that shape the space before anything else happens. -- **Right card:** agents as the interpretation layer that decides how to apply those rules in context. -- **Left card:** skills as reusable procedures and assets that carry out the chosen work. -- **Rings:** a nested-ring cascade, not three unrelated badges: instructions define the outer boundary, agents work inside it, and skills sit at the center where execution happens. -- **Center copy:** the author's shorthand for remembering the model: `Instructions set the rules. Agents decide. Skills execute.` -- **Bottom title block:** the caption that restates the blog's key claim that rules constrain decisions and decisions choose the execution path. - -### Layout choices -- The composition reads like a cascade into the center, not just cards surrounding circles. -- The instructions card sits highest and feeds straight into the rings to signal baseline governance. -- The agents card is offset right and tied to the upper rings so it feels like the interpretation layer. -- The skills card sits lower-left and closer to the core so execution reads as downstream from agent choice. -- The title/caption is isolated below the diagram so the visual makes the mental model first and the text closes the argument. - -### How to modify it -- **Change a label:** edit the `` or `` values. -- **Add a new governance layer:** add another circle around the existing ring group, then reposition connector paths. -- **Add another callout card:** duplicate one `` card block, move its `rect` and text coordinates, then add a new connector ``. -- **Adjust emphasis:** increase stroke width or font weight for one layer. -- **Keep visual consistency:** white canvas, `#f5f7fa` (or `#f0f4f8`) card fills, `#cccccc` stroke, black text, rounded rectangles, and airy spacing. - ---- - -## 2. `diagram-2-configuration-files-structure.svg` - -**Type:** Mermaid-generated flowchart SVG - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Canvas:** `viewBox="0 0 1584.6875 673"` - -### Editable Mermaid reconstruction -```mermaid -%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap. -flowchart LR - root[".github/"] - - subgraph governance["Governance"] - ci["copilot-instructions.md"] - end - - subgraph workflows["workflows/"] - wf["archie.yml / *.yml"] - end - - subgraph skills["skills/"] - skill["{name}/SKILL.md"] - end - - subgraph agents["agents/"] - archie["archie.agent.md"] - scribe["scribe.agent.md"] - end - - subgraph prompts["prompts/"] - promptdoc["architecture-review-guidelines.md"] - promptfile["*.prompt.md"] - end - - root --> ci - root --> archie - root --> scribe - root --> skill - root --> promptdoc - root --> promptfile - root --> wf - - ci -. governs .-> archie - ci -. governs .-> scribe - ci -. governs .-> skill - ci -. governs .-> wf - - archie -. loads .-> promptdoc - wf -->|triggers| archie - wf -. can trigger .-> scribe - skill -. shares reference patterns with .-> promptfile -``` - -### What each element represents -- **`.github/` root node:** the shared home for the whole configuration ecosystem. -- **Governance cluster:** the baseline instruction layer that applies across the repo. -- **Agents cluster:** specialist reviewer/persona files with tighter scope and boundaries. -- **Skills cluster:** packaged, repeatable procedures Copilot can reuse. -- **Prompts cluster:** both official `.prompt.md` templates and repo-local reference docs. -- **Workflows cluster:** GitHub Actions entry points for label-, schedule-, dispatch-, or PR-driven automation. -- **Dotted labeled edges:** the blog's relationship layer — who governs, loads, triggers, or shares patterns with what. -- **Solid root edges:** the simple file-placement fact that all five families live under one `.github` home. - -### Layout choices -- The diagram reads left-to-right as `.github` -> five file families -> cross-links. -- Governance sits closest to the root because it is the baseline layer. -- Skills and workflows occupy the middle because they represent the reusable and event-driven operational paths. -- Agents and prompts sit farther right to show specialists depending on loaded guidance and reference material. -- The overall framing matches the post's quick-reference lens: one navigable map of baseline, specialized, reusable, reference, and event-driven files. - -### How to modify it -- **Add a new file family:** add another `subgraph` and connect it from `root`. -- **Add another agent:** add a node inside `agents` and optionally connect governance/workflow edges. -- **Add a new relationship:** add a dotted edge with a label. -- **Rename paths/files:** change the node labels only; the structure can stay the same. - ---- - -## 3. `diagram-3-skills-vs-prompts-decision-tree.svg` - -**Type:** Mermaid-generated decision tree - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Canvas:** `viewBox="0 0 665.625 1080.9375"` - -### Editable Mermaid reconstruction -```mermaid -%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap. -flowchart TD - start{"Need reusable workflow?"} - promptReuse{"Need reusable user-selected template?"} - promptDoc{"Need deeper task reference context?"} - - skill["Use Skill"] - official["Use Official Prompt"] - doc["Use Prompt Doc"] - none["No file needed"] - - start -- Yes --> skill - start -- No --> promptReuse - promptReuse -- Yes --> official - promptReuse -- No --> promptDoc - promptDoc -- Yes --> doc - promptDoc -- No --> none -``` - -### What each element represents -- **Diamond 1:** the first and most important question from the post — is this a reusable workflow? -- **Diamond 2:** only appears if the answer is no; it checks whether you need an official reusable prompt template instead. -- **Diamond 3:** if it is not a prompt template, it asks whether the task needs deeper repo-local reference context. -- **Terminal boxes:** the four outcomes the article distinguishes: skill, official prompt file, prompt doc, or no extra file. - -### Layout choices -- The strict top-to-bottom order mirrors the blog's sequence: reusable workflow first, reusable prompt second, reference doc third. -- “Yes” exits early because the whole point is to stop once you have the right file family. -- Uniform outcome boxes keep the emphasis on the routing questions instead of making one option feel privileged. - -### How to modify it -- **Add another decision:** insert another diamond between `promptDoc` and the terminal nodes. -- **Change wording:** update node labels directly. -- **Change file taxonomy:** rename `Use Official Prompt`, `Use Prompt Doc`, etc. -- **Preserve readability:** keep the branching direction consistent (`Yes`/`No`). - ---- - -## 4. `diagram-4-azure-sdk-workflow-trigger.svg` - -**Type:** Mermaid-generated sequence diagram - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Canvas:** `viewBox="-50 -10 1478 572"` - -### Editable Mermaid reconstruction -```mermaid -%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap. -sequenceDiagram - participant Dev as Developer - participant GH as GitHub Actions - participant WF as archie.yml - participant Agent as archie.agent.md - participant Guide as guidelines.md - participant PR as Pull Request - - Dev->>PR: Add archie label to PR - PR->>GH: Trigger pull_request_target[labeled] - Note over GH,WF: Async GitHub-hosted run - WF->>Agent: Load reviewer definition - Agent->>Guide: Load architecture checklist - Guide-->>Agent: Return guidance + repo links - Agent-->>WF: Architecture review findings - WF->>PR: Create review + comments - PR-->>Dev: Comment appears on PR -``` - -### What each element represents -- **Developer:** the person who adds the reviewer label to the PR. -- **Pull Request:** both the trigger surface and the place where findings show up again as comments. -- **GitHub Actions / archie.yml:** the remote asynchronous workflow layer started by that label event. -- **archie.agent.md:** the reusable architecture-reviewer definition the workflow loads. -- **guidelines.md:** the repo guidance/checklist that the reviewer uses as reference context. -- **Return arrows:** findings come back directly to the PR from the workflow path shown here; the post is explicit that there is no separate collector loop in this example. - -### Layout choices -- Left-to-right order follows the loop the article says it trusts: label -> workflow -> reviewer -> guidance -> PR comment. -- The PR remains at the far right because it is both the initiation target and the visible output surface. -- The async note sits between GitHub Actions and the workflow file to emphasize GitHub-hosted automation rather than local Copilot behavior. - -### How to modify it -- **Add another reviewer asset:** insert another participant between `Agent` and `Guide`. -- **Add another step:** add a new message line in sequence order. -- **Rename the workflow:** change `archie.yml` everywhere. -- **Show additional outputs:** add another message from `WF` to `PR` or another participant. - ---- - -## 5. `diagram-5-file-placement-decision-tree.svg` - -**Type:** Mermaid-generated routing diagram - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Canvas:** `viewBox="0 0 1441.15625 336.78125"` - -### Editable Mermaid reconstruction -```mermaid -%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap. -flowchart TB - start{"What's the task?"} - - standards["Coding standards
.github/copilot-instructions.md"] - recurring["Recurring specialist task
.github/agents/"] - repeatable["Repeatable workflow
.github/skills/"] - onetime["One-time prompt or reference
.github/prompts/"] - events["Schedule, label, or PR event
.github/workflows/"] - - start --> standards - start --> recurring - start --> repeatable - start --> onetime - start --> events -``` - -### What each element represents -- **Center diamond:** the routing question the section cares about — what shape of task is this? -- **Five output boxes:** the same five file families from the quick reference and decision table. -- **Two-line box labels:** line one names the task pattern; line two gives the folder/path so you can match the task shape and drop it in the right place. - -### Layout choices -- A single fan-out keeps the emphasis on classification rather than process. -- The five destination boxes spread horizontally so the families read like peers in one routing table. -- There are no deeper branches because this section is a placement cheat sheet, not a nuanced workflow diagram. - -### How to modify it -- **Add a sixth destination:** add another box and connect from `start`. -- **Change repo paths:** update the second line in each node. -- **Simplify for a smaller image:** collapse to three outputs or split into two rows. - ---- - -## 6. `image-1-layers.png` - -**Type:** raster infographic - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Size:** `1614 x 1292` - - -### Visual metaphor and hierarchy -- **Metaphor:** the blog's nested-ring governance model. -- **Primary visual:** three concentric circles that make the control flow explicit rather than decorative. -- **Supporting callouts:** instructions above, agents to the right, and skills lower-left, each feeding into the same ring system. -- **Narrative hierarchy:** instructions shape the space -> agents interpret inside that boundary -> skills execute at the center -> the caption restates that rules constrain decisions. - -### Shapes and geometry -- White background. -- Three light-gray concentric circles. -- Three large rounded cards: top, right, lower-left. -- Two capsule labels embedded over the circles: `AGENTS` and `SKILLS`. -- Thin connector lines from the cards into the circular system. -- Bottom title block and three small centered dots. - -### Colors -Approximate palette from the rendered image: -- Background: white -- Lines and borders: light gray -- Text: black -- No accent fill colors; the design is monochrome/minimal - -### Editable production specification -Use this if recreating in Figma, Illustrator, or SVG: - -```text -Canvas: 1614x1292. Use a white or very light background (#ffffff or #f5f5f5). -All text must be black only (#000000). -All ring strokes, card borders, capsule outlines, and connector lines must be light gray (#cccccc). -All shapes should use white or very light fills (#ffffff or #fafafa) with light gray borders. -Build the composition as four clearly separated text regions: top INSTRUCTIONS card, right AGENTS card, lower-left SKILLS card, and center-copy inside the inner ring. Never let text from one region cross into another. -Center a three-ring system in the upper-middle of the canvas so it reads like nested governance rings, but reserve dedicated label lanes around it before placing any text. -Top card: use a rounded rectangle for INSTRUCTIONS with a bold all-caps heading and at most two short lines of supporting copy. Keep 20-24px internal side padding, at least 18px top/bottom padding, and at least 24px of vertical clearance between the card and any ring label below it. -Right card: place AGENTS far enough right that the card does not collide with the center copy or ring labels. Keep at least 24px between the card edge and the outer ring, and keep all supporting copy fully inside the card with 20px padding. -Lower-left card: place SKILLS far enough left and low that its body copy stays inside the card and does not run into the ring system. Keep at least 24px between the card and the outer ring. If needed, widen or heighten the card rather than shrinking padding. -Ring pills: use AGENTS and SKILLS pill labels only if each pill has its own isolated space. Do not place the AGENTS pill inside the top INSTRUCTIONS card. Keep every pill at least 12px from a ring stroke and at least 16px from any card, connector, or other text. If space is tight, move the pill outside the ring and connect it with a short leader line. -Center copy: keep the three statements inside the inner circle only, on three separate lines, with at least 20px clearance from the circle boundary. Use shorter line lengths, lighter weight, or slightly smaller type before allowing any overlap. -Connectors: keep all connectors thin and behind the composition, but do not let them pass under text. End connector lines before they enter a text box or pill. -Typography must remain readable when the image is displayed in a ~600px-wide blog column. Target an effective display scale of roughly: card headings 18-22px, supporting copy 13-15px, pill labels 16-18px, center copy 15-17px, title 24-28px, subtitle 14-16px. -At the bottom center, place the title “Layers of Governance”, then the subtitle “Rules constrain decisions, then reusable skills carry out the work.”, then three small black dots. Keep generous spacing so the footer reads separately from the diagram. -Style: minimal editorial explainer, monochrome, airy, and easy to read — more like a remembered mental model than a product UI mock. -``` - -### How to modify it -- **Best option:** edit `diagram-1-mental-model.svg` and re-export PNG. -- **If editing the PNG design manually:** keep the circle system centered and keep all callout boxes aligned to the current top/right/lower-left pattern. -- **If adding another layer:** add another ring and corresponding callout card. -- **If changing the message:** update the center copy first, then title/subtitle if needed. - ---- - -## 7. `image-2-where-they-live.png` - -**Type:** raster infographic - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Size:** `1400 x 900` - - -### Visual metaphor and hierarchy -- **Metaphor:** a single `.github` home with distinct rooms, matching the blog's point that these files live together but do different jobs. -- **Primary focal point:** one large neutral folder-house container on the left-middle with `.github` text in black. -- **Secondary structure:** five family labels stacked on the right, one for each room/file family. -- **Connector logic:** light-gray lines show that every family belongs to the same home while staying separate by purpose. -- **Reading order:** title -> subtitle -> shared home/container -> room labels. - -### Shapes and geometry -- White or very light full-bleed background. -- Large folder/house shape with white or very light fill and a light-gray outline, including a tab/roof shape at the upper-left. -- Five rounded pill/box labels stacked vertically on the right. -- Five diagonal light-gray connector lines from the folder body to each pill. - -### Colors -Standardized production palette: -- Background: white or very light gray (`#ffffff`, `#f5f5f5`) -- Folder house and pills: white or very light fill (`#ffffff`, `#fafafa`) -- Borders and connector lines: light gray (`#cccccc`) -- All text, including `.github`, title, subtitle, and labels: black (`#000000`) -- No accent colors, gradients, or dark theme treatments - -### Editable production prompt/specification -No separate prompt file was found in the repo; use this extracted art-direction spec: - -```text -Create a 1400x900 editorial infographic with a white or very light background (#ffffff or #f5f5f5). -All text must be black only (#000000). -All shape outlines and connector lines must be light gray (#cccccc). -Top-left: large black title “Where They Live”. -Below it: smaller black subtitle reading “A single .github home with distinct rooms for rules, specialists, reusable procedures, prompts, and triggers.” -Center-left: a large stylized `.github` folder that also reads as one shared home. Use a light background (white or #f5f5f5). Text must be black (#000000). -All shape outlines must be light gray (#cccccc). -Connector lines must be light gray (#cccccc). -Text labels for file families (copilot-instructions.md, agents/, skills/, prompts/, workflows/) must each have minimum 8–10px clearance from adjacent shapes and from each other. No overlaps. -Right side: stack five rounded rectangular pills vertically with generous spacing, one per file family. -Label them, top to bottom: -1. copilot-instructions.md -2. agents/ -3. skills/ -4. prompts/ -5. workflows/ -Connect the folder-house to each pill with its own light-gray line so each line reads like a room assignment inside the same home. -Use white or very light fills for the folder-house and each pill, keeping the design monochrome and editorial. -All text labels must have minimum 8px clearance from adjacent shapes and other text, with 8–10px preferred. -Style: clean explainer graphic, flat vector shapes, soft rounded corners, no texture, strong contrast, and a clear “live together, different jobs” message. -``` - -### How to modify it -- **Change a family name:** edit the text inside one pill only. -- **Add a new family:** add another pill to the stack and route a new light-gray connector line from the folder. -- **Change the metaphor:** keep the same connector system, but swap the folder-house for another “single home/container” shape. -- **Keep hierarchy stable:** title and subtitle stay top-left; container stays left; destinations stay right. diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-1-layers-of-governance.png b/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-1-layers-of-governance.png deleted file mode 100644 index 81e24ec7..00000000 Binary files a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-1-layers-of-governance.png and /dev/null differ diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-1-mapping-file-families.png b/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-1-mapping-file-families.png deleted file mode 100644 index 5cbee2a8..00000000 Binary files a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-1-mapping-file-families.png and /dev/null differ diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-2-understanding-layers.png b/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-2-understanding-layers.png deleted file mode 100644 index 6d6803c4..00000000 Binary files a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-2-understanding-layers.png and /dev/null differ diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-2-where-they-live.png b/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-2-where-they-live.png deleted file mode 100644 index c21e1ff3..00000000 Binary files a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-2-where-they-live.png and /dev/null differ diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-3-tracing-workflow.png b/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-3-tracing-workflow.png deleted file mode 100644 index cc4baf1b..00000000 Binary files a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-3-tracing-workflow.png and /dev/null differ diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-manifest.md b/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-manifest.md deleted file mode 100644 index 5a4e1795..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-manifest.md +++ /dev/null @@ -1,17 +0,0 @@ -# Generated Watercolor Illustrations - -Generated on: 2026-05-31 20:47:16 - -## Images - -1. watercolor-1-mapping-file-families.png - - Purpose: Opening section and quick reference table, where the post turns scattered `.github` files into one usable mental model. - - Status: ✅ Generated - -2. watercolor-2-understanding-layers.png - - Purpose: Instructions, agents, and skills section, where the post builds the author's mental model of governance, decision-making, and reusable execution. - - Status: ✅ Generated - -3. watercolor-3-tracing-workflow.png - - Purpose: The Azure workflow section and the later decision table, where the post moves from abstract categories to a concrete path the author can actually defend with links. - - Status: ✅ Generated diff --git a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-prompts.md b/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-prompts.md deleted file mode 100644 index 3d5e4f16..00000000 --- a/website/blog/media/2026-05-31-copilot-config-files-guide/watercolor-prompts.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: "Watercolor Prompts for Copilot Config Files Guide" ---- - -# Watercolor Illustration Prompts - -## Style & Character -Style: Watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text -Character: Normal woman with average appearance and practical clothes in a grounded work setting - -## 1. Mapping the Five File Families -- **Narrative context:** Opening section and quick reference table, where the post turns scattered `.github` files into one usable mental model. -- **Woman's activity:** She sits at a desk with folders, notes, and small stacks representing instructions, agents, skills, prompts, and workflows, physically sorting them into a layout that finally makes sense. -- **Prompt:** Normal woman at desk sorting five distinct stacks of repository files into order, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text - -## 2. Understanding the Layers -- **Narrative context:** Instructions, agents, and skills section, where the post builds the author's mental model of governance, decision-making, and reusable execution. -- **Woman's activity:** She studies nested trays or transparent layers on a desk, lifting one layer at a time to understand how the pieces sit together instead of blending into one confusing pile. -- **Prompt:** Normal woman examining nested transparent layers of governance documents, comparing one layer to another, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text - -## 3. Tracing a Real Workflow -- **Narrative context:** The Azure workflow section and the later decision table, where the post moves from abstract categories to a concrete path the author can actually defend with links. -- **Woman's activity:** She follows a line of pinned notes and folders from one workstation area to another, checking how a label, a workflow, a reviewer, and a returned comment connect in practice. -- **Prompt:** Normal woman in home office tracing a path between pinned repository notes and workflow folders, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text diff --git a/website/blog/media/2026-05-31-instructions-vs-skills/hero.png b/website/blog/media/2026-05-31-instructions-vs-skills/hero.png deleted file mode 100644 index 0a2399f8..00000000 Binary files a/website/blog/media/2026-05-31-instructions-vs-skills/hero.png and /dev/null differ diff --git a/website/blog/media/2026-05-31-instructions-vs-skills/image-prompts.md b/website/blog/media/2026-05-31-instructions-vs-skills/image-prompts.md deleted file mode 100644 index 54e64667..00000000 --- a/website/blog/media/2026-05-31-instructions-vs-skills/image-prompts.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "Image prompts: Instructions vs Skills" -draft: true ---- - -# Image prompts — 2026-05-31 instructions vs skills - -## Hero image — governance vs execution workbenches - -**Prompt for Midjourney / DALL-E:** -A clean Pacific Northwest workshop interior with two parallel workbenches under soft overcast morning light, one bench labeled "governance" with neatly arranged rule cards, checklists, blueprints, and a wall-mounted standards board, the other bench labeled "execution" with active tools, jigs, clamps, a laptop showing workflow steps, and parts in motion; cedar wood textures, rain-muted windows, Mount Baker mood, calm professional atmosphere, human-centered technical metaphor, editorial blog hero composition, wide framing, no people, subtle teal and evergreen palette, highly legible labels, clean minimalist layout, PNW watercolor style blended with crisp digital illustration, suitable for a technical blog hero image --ar 16:9 - -## Supporting image — instructions vs skills decision tree - -**Prompt for Midjourney / DALL-E:** -A minimalist technical flowchart poster showing a decision tree for "instructions vs skills" with short branch labels like "always applies?", "rule or policy?", "needs steps?", "tool-backed workflow?" leading to two destinations: "repo instructions" and "skill"; clean white background, evergreen and slate accent colors, subtle Pacific Northwest design cues, modern product-diagram aesthetic, sharp typography, generous spacing, flat vector style, optimized for a 600px blog column, clean minimalist technical diagram diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3-color.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3-color.svg deleted file mode 100644 index b53771a9..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3-color.svg +++ /dev/null @@ -1,68 +0,0 @@ - - Layers of Governance - A monochrome governance mental model with instructions above the rings, agents to the right, skills to the lower left, and a three-line center summary inside the inner circle. - - - - - - - - - INSTRUCTIONS - Repo rules and guardrails - shape the whole space - - - - - AGENTS - Interpret rules for - the current context - - - - - SKILLS - Carry out reusable - steps and assets - - - - - - - - - - - - - - Instructions set rules. - Agents decide. - Skills execute. - - - - Layers of Governance - Rules constrain decisions, then reusable skills carry out the work. - - - - - - - - \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3.svg deleted file mode 100644 index be23c169..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3.svg +++ /dev/null @@ -1,68 +0,0 @@ - - Layers of Governance - A monochrome governance mental model with instructions above the rings, agents to the right, skills to the lower left, and a three-line center summary inside the inner circle. - - - - - - - - - INSTRUCTIONS - Repo rules and guardrails - shape the whole space - - - - - AGENTS - Interpret rules for - the current context - - - - - SKILLS - Carry out reusable - steps and assets - - - - - - - - - - - - - - Instructions set rules. - Agents decide. - Skills execute. - - - - Layers of Governance - Rules constrain decisions, then reusable skills carry out the work. - - - - - - - - \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-light.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-light.svg deleted file mode 100644 index ebf8f86d..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-light.svg +++ /dev/null @@ -1 +0,0 @@ -workflows/prompts/skills/agents/Governancegovernsgovernsgovernsgovernsloadstriggerscan triggershares reference patterns with.github/copilot-instructions.mdarchie.agent.mdscribe.agent.md{name}/SKILL.mdarchitecture-review-guidelines.md*.prompt.mdarchie.yml / *.yml \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-v2.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-v2.svg deleted file mode 100644 index 16538f31..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-v2.svg +++ /dev/null @@ -1,118 +0,0 @@ - - - The Six .github File Families - - - - .github/ - - - - - - - - - - - - - - - - - - - - 1 - Copilot Instructions - copilot-instructions.md - - Repository-wide - governance rules - (always-on context) - - - - - - - 2 - Path-specific Instructions - instructions/ - *.instructions.md - - Scoped rules for - specific directories - - - - - narrows - - - - - - 3 - Agent Definitions - agents/ - {name}.agent.md - - Specialist persona with - scope, tools, constraints - - - - - - - 4 - Skills - skills/{name}/ - SKILL.md - - Reusable workflow - packages & procedures - - - - - loads - - - - - - 5 - Prompt Files - prompts/ - *.prompt.md - - Reusable templates & - reference context - - - - - - - 6 - Workflows - workflows/ - *.yml - - GitHub Actions - automation & triggers - - - - - Legend: - - Copilot config - - Actions (not Copilot-specific) - - Relationship - \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure.svg deleted file mode 100644 index 23ef79b0..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure.svg +++ /dev/null @@ -1 +0,0 @@ -

workflows/

prompts/

skills/

agents/

Governance

governs

governs

governs

governs

loads

triggers

can trigger

shares reference patterns with

.github/

copilot-instructions.md

archie.agent.md

scribe.agent.md

{name}/SKILL.md

architecture-review-guidelines.md

*.prompt.md

archie.yml / *.yml

 \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-file-families-v3.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-file-families-v3.svg deleted file mode 100644 index 86864991..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-file-families-v3.svg +++ /dev/null @@ -1 +0,0 @@ -

prompts/

agents/

skills/

workflows/

Governance

governs

governs

governs

governs

loads

triggers

can trigger

shares reference patterns with

.github/

copilot-instructions.md

archie.yml / *.yml

{name}/SKILL.md

archie.agent.md

scribe.agent.md

architecture-review-guidelines.md

*.prompt.md

 \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree-light.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree-light.svg deleted file mode 100644 index 9f3102c2..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree-light.svg +++ /dev/null @@ -1 +0,0 @@ -YesNoYesNoYesNoNeed reusable workflow?Need reusable user-selected template?Need deeper task reference context?Use SkillUse Official PromptUse Prompt DocNo file needed \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree.svg deleted file mode 100644 index 9565a0d6..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree.svg +++ /dev/null @@ -1 +0,0 @@ -

Yes

No

Yes

No

Yes

No

Need reusable workflow?

Need reusable user-selected template?

Need deeper task reference context?

Use Skill

Use Official Prompt

Use Prompt Doc

No file needed

 \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-top-level-routing-v3.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-top-level-routing-v3.svg deleted file mode 100644 index 5586f509..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-top-level-routing-v3.svg +++ /dev/null @@ -1 +0,0 @@ -

Yes

No

Yes

No

Yes

No

Need reusable workflow?

Need reusable user-selected template?

Need deeper task reference context?

Use Skill

Use Official Prompt

Use Prompt Doc

No file needed

 \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-agent-routing-v3.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-agent-routing-v3.svg deleted file mode 100644 index e22782ce..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-agent-routing-v3.svg +++ /dev/null @@ -1 +0,0 @@ -Pull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperAsync GitHub-hosted runAdd archie label to PRTrigger pull_request_target[labeled]Load reviewer definitionLoad architecture checklistReturn guidance + repo linksArchitecture review findingsCreate review + commentsComment appears on PR \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-color.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-color.svg deleted file mode 100644 index 3aa505bd..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-color.svg +++ /dev/null @@ -1 +0,0 @@ -Pull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperPull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperAsync GitHub-hosted runAdd archie label to PRTrigger pull_request_target[labeled]Load reviewer definitionLoad architecture checklistReturn guidance + repo linksArchitecture review findingsCreate review + commentsComment appears on PR \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-light.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-light.svg deleted file mode 100644 index fe3a7294..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-light.svg +++ /dev/null @@ -1 +0,0 @@ -Pull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperPull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperAsync GitHub-hosted runAdd archie label to PRTrigger pull_request_target[labeled]Load reviewer definitionLoad architecture checklistReturn guidance + repo linksArchitecture review findingsCreate review + commentsComment appears on PR \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger.svg deleted file mode 100644 index 1dc7aa76..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger.svg +++ /dev/null @@ -1 +0,0 @@ -Pull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperPull Requestguidelines.mdarchie.agent.mdarchie.ymlGitHub ActionsDeveloperAsync GitHub-hosted runAdd archie label to PRTrigger pull_request_target[labeled]Load reviewer definitionLoad architecture checklistReturn guidance + repo linksArchitecture review findingsCreate review + commentsComment appears on PR \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree-light.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree-light.svg deleted file mode 100644 index c864bbdc..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree-light.svg +++ /dev/null @@ -1 +0,0 @@ -What's the task?Coding standards.github/copilot-instructions.mdRecurring specialist task.github/agents/Repeatable workflow.github/skills/One-time prompt or reference.github/prompts/Schedule, label, or PR event.github/workflows/ \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree.svg deleted file mode 100644 index 51cc3228..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree.svg +++ /dev/null @@ -1 +0,0 @@ -

What's the task?

Coding standards
.github/copilot-instructions.md

Recurring specialist task
.github/agents/

Repeatable workflow
.github/skills/

One-time prompt or reference
.github/prompts/

Schedule, label, or PR event
.github/workflows/

 \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-input-parsing-v3.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-input-parsing-v3.svg deleted file mode 100644 index 6e935621..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-input-parsing-v3.svg +++ /dev/null @@ -1 +0,0 @@ -

What's the task?

Coding standards
.github/copilot-instructions.md

Recurring specialist task
.github/agents/

Repeatable workflow
.github/skills/

One-time prompt or reference
.github/prompts/

Schedule, label, or PR event
.github/workflows/

 \ No newline at end of file diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/generate-images.sh b/website/blog/media/2026-06-03-copilot-config-files-guide/generate-images.sh deleted file mode 100644 index b081f842..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/generate-images.sh +++ /dev/null @@ -1,178 +0,0 @@ -#!/bin/bash -# Image Generation Script for Copilot Configuration Files Guide Blog Post -# Generated: 2026-05-31 -# Purpose: Regenerate all SVG diagrams, PNG infographics, and watercolor illustrations -# -# All commands use the Stable Diffusion image generation pipeline. -# Prompt source: image-specs-and-prompts.md and watercolor-prompts.md -# Device auto-detection: uses CUDA if available, MPS on Apple Silicon, falls back to CPU -# -# Usage: bash generate-images.sh [filter] -# filter (optional): "svg", "png", or "watercolor" to run only that subset -# Example: bash generate-images.sh watercolor - -set -e - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -OUTPUT_DIR="$SCRIPT_DIR" -SEED_BASE=52 - -# Colors for terminal output -GREEN='\033[0;32m' -BLUE='\033[0;34m' -NC='\033[0m' # No Color - -echo -e "${BLUE}=== Copilot Config Files Guide: Image Generation ===${NC}\n" - -# ============================================================================ -# SVG DIAGRAMS (Mermaid → SVG export) -# ============================================================================ - -generate_svg_diagrams() { - echo -e "${GREEN}Generating SVG diagrams...${NC}\n" - - # Diagram 1: Mental Model (three rings with cards) - echo "1. diagram-1-mental-model-v3.svg" - echo " Cards: INSTRUCTIONS, AGENTS, SKILLS around three nested rings" - echo " Color: White bg, black text, light gray lines (#cccccc), light fills (#f5f7fa)" - echo " ✓ Manual Mermaid export or direct SVG creation\n" - - # Diagram 2: File Families Decision Tree - echo "2. diagram-2-file-families-v3.svg" - echo " Structure: Root node → 5 file family branches (instructions, agents, skills, prompts, workflows)" - echo " Labels: concise routing decisions" - echo " ✓ Manual Mermaid export or direct SVG creation\n" - - # Diagram 3: Skills vs. Prompts Decision Tree - echo "3. diagram-3-top-level-routing-v3.svg" - echo " Decision flow: Does it reuse? → skills | Is it situational? → prompts" - echo " ✓ Manual Mermaid export or direct SVG creation\n" - - # Diagram 4: Agent Routing (agents → handlers → channels) - echo "4. diagram-4-agent-routing-v3.svg" - echo " Flow: Multiple agents dispatched based on role + task type" - echo " ✓ Manual Mermaid export or direct SVG creation\n" - - # Diagram 5: File Placement Decision Tree - echo "5. diagram-5-input-parsing-v3.svg" - echo " Decision: Where do these config files live? (.github, root, dotenv, etc.)" - echo " ✓ Manual Mermaid export or direct SVG creation\n" -} - -# ============================================================================ -# PNG INFOGRAPHICS (Simple stable-diffusion generation) -# ============================================================================ - -generate_png_infographics() { - echo -e "${GREEN}Generating PNG infographics...${NC}\n" - - # Image 1: Quick Reference Table (visual rendering of file families table) - echo "📋 image-1-quick-reference-table.png" - python3 simple_config.py \ - --prompt "A clean reference table layout showing file families, descriptions, and locations in a organized grid format, light background, black text, minimal design, professional appearance, no decorative elements, clear typography" \ - --preset production \ - --style infographic \ - --size blog-hero \ - --seed $((SEED_BASE + 1)) \ - --output "$OUTPUT_DIR/image-1-quick-reference-table.png" \ - --modifier clarity \ - --modifier organized - echo " ✓ Generated\n" - - # Image 2: Where They Live (file system layout visualization) - echo "📂 image-2-where-they-live.png" - python3 simple_config.py \ - --prompt "Folder and file structure diagram showing .github directory, root config files, environment variables, visual hierarchy with clear separation between file types, light background, monochrome, professional infographic style, no text labels inside boxes" \ - --preset production \ - --style infographic \ - --size blog-hero \ - --seed $((SEED_BASE + 2)) \ - --output "$OUTPUT_DIR/image-2-where-they-live.png" \ - --modifier structure \ - --modifier clarity - echo " ✓ Generated\n" -} - -# ============================================================================ -# WATERCOLOR ILLUSTRATIONS (Story-driven, character-focused) -# ============================================================================ - -generate_watercolors() { - echo -e "${GREEN}Generating watercolor illustrations...${NC}\n" - - # Watercolor 1: Mapping the Five File Families - echo "🎨 watercolor-1-mapping-file-families.png" - python3 simple_config.py \ - --prompt "Normal woman at desk sorting five distinct stacks of repository files into order, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed $((SEED_BASE + 3)) \ - --output "$OUTPUT_DIR/watercolor-1-mapping-file-families.png" \ - --modifier painterly \ - --modifier loose - echo " ✓ Generated\n" - - # Watercolor 2: Understanding the Layers - echo "🎨 watercolor-2-understanding-layers.png" - python3 simple_config.py \ - --prompt "Normal woman examining nested transparent layers of governance documents, comparing one layer to another, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed $((SEED_BASE + 4)) \ - --output "$OUTPUT_DIR/watercolor-2-understanding-layers.png" \ - --modifier painterly \ - --modifier loose - echo " ✓ Generated\n" - - # Watercolor 3: Tracing a Real Workflow - echo "🎨 watercolor-3-tracing-workflow.png" - python3 simple_config.py \ - --prompt "Normal woman in home office tracing a path between pinned repository notes and workflow folders, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed $((SEED_BASE + 5)) \ - --output "$OUTPUT_DIR/watercolor-3-tracing-workflow.png" \ - --modifier painterly \ - --modifier loose - echo " ✓ Generated\n" -} - -# ============================================================================ -# MAIN EXECUTION -# ============================================================================ - -FILTER="${1:-all}" - -case "$FILTER" in - svg) - generate_svg_diagrams - ;; - png) - generate_png_infographics - ;; - watercolor) - generate_watercolors - ;; - all) - generate_svg_diagrams - generate_png_infographics - generate_watercolors - ;; - *) - echo "Unknown filter: $FILTER" - echo "Usage: bash generate-images.sh [svg|png|watercolor|all]" - exit 1 - ;; -esac - -echo -e "${GREEN}✓ Image generation complete!${NC}\n" -echo "Generated files are in: $OUTPUT_DIR" -echo "" -echo "Next steps:" -echo "1. Review all generated images in the media folder" -echo "2. Compare against image-specs-and-prompts.md specifications" -echo "3. Update blog post references if needed" -echo "4. Commit all images with: git add media/2026-05-31-copilot-config-files-guide/*.{svg,png}" diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/image-2-where-they-live.png b/website/blog/media/2026-06-03-copilot-config-files-guide/image-2-where-they-live.png deleted file mode 100644 index 8b15cf92..00000000 Binary files a/website/blog/media/2026-06-03-copilot-config-files-guide/image-2-where-they-live.png and /dev/null differ diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/image-generation-reference.md b/website/blog/media/2026-06-03-copilot-config-files-guide/image-generation-reference.md deleted file mode 100644 index 14045fbb..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/image-generation-reference.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -title: "Image Generation CLI Reference" ---- - -# Image Generation Commands Reference - -This document contains all CLI commands for regenerating the blog post's visual assets. Use this when modifying prompts, regenerating specific images, or troubleshooting output. - -## Quick Start - -```bash -# Regenerate all images -bash generate-images.sh all - -# Regenerate only watercolors -bash generate-images.sh watercolor - -# Regenerate only PNG infographics -bash generate-images.sh png - -# Regenerate only SVG diagrams -bash generate-images.sh svg -``` - ---- - -## Image Specifications - -### Design System (All Images) -- **Background:** Light (#ffffff or #f5f7fa) -- **Text:** Black (#000000) -- **Lines/Connectors:** Light gray (#cccccc) -- **Size:** 1536×1024 pixels (blog-hero standard) -- **Text Constraint:** No overlapping text; minimum 8-24px clearance from shapes -- **Style:** Monochrome, no gradients, no accent colors - -### Color Schema (Watercolors Only) -- **Technique:** Soft wet-on-wet washes -- **Texture:** Visible paper texture -- **Tones:** Warm, muted palette -- **Brushwork:** Loose, painterly -- **Text:** None - ---- - -## SVG Diagrams - -### 1. Mental Model (Three Rings + Cards) -``` -diagram-1-mental-model-v3.svg -``` -- **Content:** Three nested rings (Instructions → Agents → Skills cascade) -- **Cards:** INSTRUCTIONS (top), AGENTS (right), SKILLS (left) with light backgrounds (#f5f7fa) -- **Layout:** Symmetric, centered -- **Clearance:** 24px minimum from text to shapes - -**Manual regeneration:** -1. Export from Mermaid diagram editor -2. Post-process: ensure card fills are #f5f7fa, no pill labels -3. Verify clearance zones: top card INSTRUCTIONS | right card AGENTS | left card SKILLS | center copy - -### 2. File Families Decision Tree -``` -diagram-2-file-families-v3.svg -``` -- **Root Node:** "Config Files" -- **Branches:** Instructions | Agents | Skills | Prompts | Workflows -- **Edge Labels:** Routing decisions (2-3 words max) -- **Layout:** Hierarchical tree - -### 3. Skills vs. Prompts Decision Tree -``` -diagram-3-top-level-routing-v3.svg -``` -- **Decision Point:** "Does it reuse across many prompts?" -- **Left path:** "Yes" → Skills -- **Right path:** "No" → Prompts -- **Layout:** Binary decision flow - -### 4. Agent Routing -``` -diagram-4-agent-routing-v3.svg -``` -- **Flow:** Agents (by role + task type) → Handlers → Execution Channels -- **Elements:** Agent boxes, handler boxes, channel endpoints -- **Connectors:** Labeled edges showing routing logic - -### 5. File Placement Decision Tree -``` -diagram-5-input-parsing-v3.svg -``` -- **Question:** "Where do these files live?" -- **Decisions:** Scope (repo-wide vs. per-branch) → Location (.github vs. root vs. dotenv) -- **Leaf nodes:** Final placement recommendations - ---- - -## PNG Infographics - -### Image 1: Quick Reference Table -```bash -python3 simple_config.py \ - --prompt "A clean reference table layout showing file families, descriptions, and locations in a organized grid format, light background, black text, minimal design, professional appearance, no decorative elements, clear typography" \ - --preset production \ - --style infographic \ - --size blog-hero \ - --seed 53 \ - --output outputs/image-1-quick-reference-table.png \ - --cpu \ - --modifier clarity \ - --modifier organized -``` - -**What it shows:** -- Structured table of file families (Instructions, Agents, Skills, Prompts, Workflows) -- Columns: Family Name | Purpose | File Name(s) | Location -- Professional grid layout, no decorative elements - -### Image 2: Where They Live (File System Structure) -```bash -python3 simple_config.py \ - --prompt "Folder and file structure diagram showing .github directory, root config files, environment variables, visual hierarchy with clear separation between file types, light background, monochrome, professional infographic style, no text labels inside boxes" \ - --preset production \ - --style infographic \ - --size blog-hero \ - --seed 54 \ - --output outputs/image-2-where-they-live.png \ - --cpu \ - --modifier structure \ - --modifier clarity -``` - -**What it shows:** -- Visual tree of `.github/` directory structure -- Root-level config files (copilot.json, etc.) -- Environment variable locations -- Clear visual separation of file types - ---- - -## Watercolor Illustrations - -Each watercolor uses **tight, focused prompts** (~20 words) to avoid competing visual details. See `watercolor-prompts.md` for narrative context. - -### Watercolor 1: Mapping the Five File Families -```bash -python3 simple_config.py \ - --prompt "Normal woman at desk sorting five distinct stacks of repository files into order, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed 55 \ - --output outputs/watercolor-1-mapping-file-families.png \ - --cpu \ - --modifier painterly \ - --modifier loose -``` - -**Narrative:** Opening section — woman physically organizing the five file families into one usable mental model. - -**Key elements:** -- Normal woman (average features, practical clothes) -- Desk with papers/folders -- Five distinct stacks being sorted -- Warm, loose watercolor technique - -### Watercolor 2: Understanding the Layers -```bash -python3 simple_config.py \ - --prompt "Normal woman examining nested transparent layers of governance documents, comparing one layer to another, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed 56 \ - --output outputs/watercolor-2-understanding-layers.png \ - --cpu \ - --modifier painterly \ - --modifier loose -``` - -**Narrative:** Instructions, Agents, Skills section — woman examining nested layers to understand how they sit together. - -**Key elements:** -- Woman at desk -- Transparent/translucent layers (trays or sheets) -- One layer lifted/compared to another -- Focused, curious expression -- Watercolor technique - -### Watercolor 3: Tracing a Real Workflow -```bash -python3 simple_config.py \ - --prompt "Normal woman in home office tracing a path between pinned repository notes and workflow folders, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \ - --preset production \ - --style watercolor \ - --size blog-hero \ - --seed 57 \ - --output outputs/watercolor-3-tracing-workflow.png \ - --cpu \ - --modifier painterly \ - --modifier loose -``` - -**Narrative:** Azure workflow section and decision table — woman tracing a concrete path from abstract categories to real implementation. - -**Key elements:** -- Woman at home office -- Pinned notes on wall or board -- Workflow folders/documents -- Following a line/path between elements -- Hands-on, investigative posture -- Watercolor technique - ---- - -## Prompt Engineering Rules - -### Watercolor Prompts (Critical) -- **Length:** Keep to ~20 words (PRDs blog style) -- **Structure:** `[Subject] [one clear focal action] [technique keywords] [result constraint]` -- **Avoid:** Multiple competing actions, vague subjects, text overlays -- **Character:** Always "normal woman" (not beautified, not styled) -- **Setting:** Grounded work environment (desk, home office, etc.) -- **Technique keywords:** "watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" - -### PNG Infographic Prompts -- **Length:** 15–25 words -- **Style:** "light background, black text, minimal design, professional" -- **Avoid:** Decorative elements, gradients, accent colors -- **Modifiers:** `--modifier clarity`, `--modifier organized`, `--modifier structure` - -### Common Modifiers -| Modifier | Effect | -|----------|--------| -| `painterly` | Loose, artistic technique | -| `loose` | Relaxed brushwork (watercolor) | -| `clarity` | Sharp focus, clear text | -| `organized` | Clean layout, grid structure | -| `structure` | Visual hierarchy, spatial relationships | -| `crisper` | Defined edges, precision | -| `more-detailed` | Additional visual information | - ---- - -## Seed Values - -**Base seed:** 52 (assigned at start of image generation batch) - -**Increment:** +1 for each subsequent image in order: -- PNG Image 1: seed 53 -- PNG Image 2: seed 54 -- Watercolor 1: seed 55 -- Watercolor 2: seed 56 -- Watercolor 3: seed 57 - -**Why:** Consistent but varied results. Change the base seed (e.g., 100, 200) to explore different style directions while keeping relative relationships. - ---- - -## Troubleshooting - -### Images Look Poor Quality or Confusing -**Likely cause:** Prompt is too verbose or has competing visual elements. - -**Fix:** Tighten the prompt. Remove secondary actions. Focus on ONE clear subject + ONE action. Example: -- ❌ "Woman at desk working on files, thinking deeply, with visible code snippets and diagrams around her" -- ✅ "Woman at desk sorting five distinct stacks of repository files, watercolor illustration" - -### Text Overlaps Other Elements -**Likely cause:** Mermaid diagram text clearance zones not respected. - -**Fix:** Review `image-specs-and-prompts.md` clearance constraints. Ensure 8–24px minimum space around all text. - -### Watercolor Colors Don't Match PRDs Blog Style -**Likely cause:** Seed or modifier settings differ. - -**Fix:** Check exact seed value and modifiers (`--modifier painterly --modifier loose`). Compare against reference images from PRDs blog. If still incorrect, adjust prompt to be more specific about tone (e.g., "ochre and soft blue undertones"). - -### SVG Diagrams Not Rendering in Docusaurus -**Likely cause:** SVG file size, missing xmlns, or embedded elements. - -**Fix:** Verify SVG has `xmlns="http://www.w3.org/2000/svg"`. Check file size (should be <50KB). Test rendering locally: `npm start` in website directory. - ---- - -## File Organization - -All images live in: -``` -website/blog/media/2026-05-31-copilot-config-files-guide/ -``` - -**Naming convention:** -- SVGs: `diagram-{N}-{kebab-case-name}-v3.svg` -- PNG infographics: `image-{N}-{kebab-case-name}.png` -- Watercolors: `watercolor-{N}-{kebab-case-name}.png` - -**Referenced in blog post:** -```markdown -![Alt text](./media/2026-05-31-copilot-config-files-guide/diagram-1-mental-model-v3.svg) -![Alt text](./media/2026-05-31-copilot-config-files-guide/watercolor-1-mapping-file-families.png) -``` - ---- - -## Next Steps - -1. **Review regenerated images** against `image-specs-and-prompts.md` -2. **Integrate into blog post** (markdown image references) -3. **Test Docusaurus build:** `npm run build` in website directory -4. **Commit all media:** `git add media/2026-05-31-copilot-config-files-guide/` -5. **Publish blog post** when ready - ---- - -## Reference Files - -- **`watercolor-prompts.md`** — Narrative context and exact prompts for all 3 watercolor illustrations -- **`image-specs-and-prompts.md`** — Master reference with production specs, layout rationale, and modification guides for all 7 visual assets -- **`watercolor-manifest.md`** — Tracking file for watercolor generation status -- **`generate-images.sh`** — Bash script to regenerate all images with one command diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/image-specs-and-prompts.md b/website/blog/media/2026-06-03-copilot-config-files-guide/image-specs-and-prompts.md deleted file mode 100644 index 249318c4..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/image-specs-and-prompts.md +++ /dev/null @@ -1,440 +0,0 @@ -# Image Specs and Prompts - -These specs were extracted from the existing 7 assets in this folder. - -Notes: -- For SVGs, I read the source and reconstructed editable structure. -- For PNGs, I examined the rendered image and provide a faithful editable production spec. -- I did **not** find a separate original prompt file for these 7 assets in the repo, so the PNG sections include an extracted **specification/prompt** rather than a repo-authored source prompt. - ---- - -## 1. `diagram-1-mental-model.svg` - -**Type:** custom SVG composition - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Canvas:** `viewBox="0 0 807 646"` -**Title in file:** `Layers of Governance` - -Production specification (revised for text layout) -This is not a native Mermaid diagram; it is a custom SVG built around the post's mental model: instructions create the boundary, agents interpret inside it, and skills sit at the execution center. - -```text -Canvas: viewBox 0 0 807 646 on a white background (#ffffff). -Use black text only (#000000), light-gray strokes (#cccccc), and white/light fills only where specified. -Treat the composition as four protected text zones: the top INSTRUCTIONS card, the right AGENTS card, the left SKILLS card, and the inner-circle center copy. Text from one zone must never enter another zone. -Build the diagram around a centered three-ring system. Keep generous negative space around the rings so the rings read as layers, not collisions. -Top card: place a rounded rectangle centered above the rings for INSTRUCTIONS with a soft light fill such as #f5f7fa (or #f0f4f8) so it pops against the white canvas while staying subtle. Keep at least 24px of vertical gap between the bottom of this card and any connector. Inside the card, use 18-20px side padding, at least 16px top/bottom padding, a bold all-caps heading, then two short lines of body copy. If the text feels tight, increase card height before reducing spacing. -Right card: place a rounded rectangle to the right of the rings for AGENTS using the same soft light fill (#f5f7fa or #f0f4f8). Keep at least 24px of horizontal clearance between the card edge and the outer ring. Put the AGENTS label inside the card as the card heading, then keep the body copy inside the card with 18-20px internal padding and no more than two short lines. -Left card: place a rounded rectangle lower-left for SKILLS using the same soft light fill (#f5f7fa or #f0f4f8). Keep at least 24px of clearance from the outer ring and enough width that the supporting copy stays fully inside the card. Put the SKILLS label inside the card as the card heading. Increase card height or width instead of squeezing text. -Connectors: use thin light-gray connectors, but route them so they stop before any text area. No connector may pass under or through a text label. -Center copy: place three stacked lines inside the inner circle only. Keep all center text at least 16px away from the inner circle boundary on every side. Use shorter lines and a slightly smaller size than the card headings so the hierarchy stays clear. -Typography for web-sized viewing (~600px content column): card headings should read like 18-20px, supporting copy like 13-15px, center copy like 15-17px, title like 24-28px, and subtitle like 14-16px. -Bottom title block: keep the title, subtitle, and three dots centered below the diagram with enough separation that the caption reads as a footer, not part of the rings. -Overall style: minimal editorial explainer, monochrome, airy, and legible at small blog-column display sizes, with softly tinted cards on a white canvas for contrast. -``` - -### What each element represents -- **Top card:** the always-on repo rules and guardrails that shape the space before anything else happens. -- **Right card:** agents as the interpretation layer that decides how to apply those rules in context. -- **Left card:** skills as reusable procedures and assets that carry out the chosen work. -- **Rings:** a nested-ring cascade, not three unrelated badges: instructions define the outer boundary, agents work inside it, and skills sit at the center where execution happens. -- **Center copy:** the author's shorthand for remembering the model: `Instructions set the rules. Agents decide. Skills execute.` -- **Bottom title block:** the caption that restates the blog's key claim that rules constrain decisions and decisions choose the execution path. - -### Layout choices -- The composition reads like a cascade into the center, not just cards surrounding circles. -- The instructions card sits highest and feeds straight into the rings to signal baseline governance. -- The agents card is offset right and tied to the upper rings so it feels like the interpretation layer. -- The skills card sits lower-left and closer to the core so execution reads as downstream from agent choice. -- The title/caption is isolated below the diagram so the visual makes the mental model first and the text closes the argument. - -### How to modify it -- **Change a label:** edit the `` or `` values. -- **Add a new governance layer:** add another circle around the existing ring group, then reposition connector paths. -- **Add another callout card:** duplicate one `` card block, move its `rect` and text coordinates, then add a new connector ``. -- **Adjust emphasis:** increase stroke width or font weight for one layer. -- **Keep visual consistency:** white canvas, `#f5f7fa` (or `#f0f4f8`) card fills, `#cccccc` stroke, black text, rounded rectangles, and airy spacing. - ---- - -## 2. `diagram-2-configuration-files-structure.svg` - -**Type:** Mermaid-generated flowchart SVG - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Canvas:** `viewBox="0 0 1584.6875 673"` - -### Editable Mermaid reconstruction -```mermaid -%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap. -flowchart LR - root[".github/"] - - subgraph governance["Governance"] - ci["copilot-instructions.md"] - end - - subgraph workflows["workflows/"] - wf["archie.yml / *.yml"] - end - - subgraph skills["skills/"] - skill["{name}/SKILL.md"] - end - - subgraph agents["agents/"] - archie["archie.agent.md"] - scribe["scribe.agent.md"] - end - - subgraph prompts["prompts/"] - promptdoc["architecture-review-guidelines.md"] - promptfile["*.prompt.md"] - end - - root --> ci - root --> archie - root --> scribe - root --> skill - root --> promptdoc - root --> promptfile - root --> wf - - ci -. governs .-> archie - ci -. governs .-> scribe - ci -. governs .-> skill - ci -. governs .-> wf - - archie -. loads .-> promptdoc - wf -->|triggers| archie - wf -. can trigger .-> scribe - skill -. shares reference patterns with .-> promptfile -``` - -### What each element represents -- **`.github/` root node:** the shared home for the whole configuration ecosystem. -- **Governance cluster:** the baseline instruction layer that applies across the repo. -- **Agents cluster:** specialist reviewer/persona files with tighter scope and boundaries. -- **Skills cluster:** packaged, repeatable procedures Copilot can reuse. -- **Prompts cluster:** both official `.prompt.md` templates and repo-local reference docs. -- **Workflows cluster:** GitHub Actions entry points for label-, schedule-, dispatch-, or PR-driven automation. -- **Dotted labeled edges:** the blog's relationship layer — who governs, loads, triggers, or shares patterns with what. -- **Solid root edges:** the simple file-placement fact that all five families live under one `.github` home. - -### Layout choices -- The diagram reads left-to-right as `.github` -> five file families -> cross-links. -- Governance sits closest to the root because it is the baseline layer. -- Skills and workflows occupy the middle because they represent the reusable and event-driven operational paths. -- Agents and prompts sit farther right to show specialists depending on loaded guidance and reference material. -- The overall framing matches the post's quick-reference lens: one navigable map of baseline, specialized, reusable, reference, and event-driven files. - -### How to modify it -- **Add a new file family:** add another `subgraph` and connect it from `root`. -- **Add another agent:** add a node inside `agents` and optionally connect governance/workflow edges. -- **Add a new relationship:** add a dotted edge with a label. -- **Rename paths/files:** change the node labels only; the structure can stay the same. - ---- - -## 3. `diagram-3-skills-vs-prompts-decision-tree.svg` - -**Type:** Mermaid-generated decision tree - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Canvas:** `viewBox="0 0 665.625 1080.9375"` - -### Editable Mermaid reconstruction -```mermaid -%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap. -flowchart TD - start{"Need reusable workflow?"} - promptReuse{"Need reusable user-selected template?"} - promptDoc{"Need deeper task reference context?"} - - skill["Use Skill"] - official["Use Official Prompt"] - doc["Use Prompt Doc"] - none["No file needed"] - - start -- Yes --> skill - start -- No --> promptReuse - promptReuse -- Yes --> official - promptReuse -- No --> promptDoc - promptDoc -- Yes --> doc - promptDoc -- No --> none -``` - -### What each element represents -- **Diamond 1:** the first and most important question from the post — is this a reusable workflow? -- **Diamond 2:** only appears if the answer is no; it checks whether you need an official reusable prompt template instead. -- **Diamond 3:** if it is not a prompt template, it asks whether the task needs deeper repo-local reference context. -- **Terminal boxes:** the four outcomes the article distinguishes: skill, official prompt file, prompt doc, or no extra file. - -### Layout choices -- The strict top-to-bottom order mirrors the blog's sequence: reusable workflow first, reusable prompt second, reference doc third. -- “Yes” exits early because the whole point is to stop once you have the right file family. -- Uniform outcome boxes keep the emphasis on the routing questions instead of making one option feel privileged. - -### How to modify it -- **Add another decision:** insert another diamond between `promptDoc` and the terminal nodes. -- **Change wording:** update node labels directly. -- **Change file taxonomy:** rename `Use Official Prompt`, `Use Prompt Doc`, etc. -- **Preserve readability:** keep the branching direction consistent (`Yes`/`No`). - ---- - -## 4. `diagram-4-azure-sdk-workflow-trigger.svg` - -**Type:** Mermaid-generated sequence diagram - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Canvas:** `viewBox="-50 -10 1478 572"` - -### Editable Mermaid reconstruction -```mermaid -%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap. -sequenceDiagram - participant Dev as Developer - participant GH as GitHub Actions - participant WF as archie.yml - participant Agent as archie.agent.md - participant Guide as guidelines.md - participant PR as Pull Request - - Dev->>PR: Add archie label to PR - PR->>GH: Trigger pull_request_target[labeled] - Note over GH,WF: Async GitHub-hosted run - WF->>Agent: Load reviewer definition - Agent->>Guide: Load architecture checklist - Guide-->>Agent: Return guidance + repo links - Agent-->>WF: Architecture review findings - WF->>PR: Create review + comments - PR-->>Dev: Comment appears on PR -``` - -### What each element represents -- **Developer:** the person who adds the reviewer label to the PR. -- **Pull Request:** both the trigger surface and the place where findings show up again as comments. -- **GitHub Actions / archie.yml:** the remote asynchronous workflow layer started by that label event. -- **archie.agent.md:** the reusable architecture-reviewer definition the workflow loads. -- **guidelines.md:** the repo guidance/checklist that the reviewer uses as reference context. -- **Return arrows:** findings come back directly to the PR from the workflow path shown here; the post is explicit that there is no separate collector loop in this example. - -### Layout choices -- Left-to-right order follows the loop the article says it trusts: label -> workflow -> reviewer -> guidance -> PR comment. -- The PR remains at the far right because it is both the initiation target and the visible output surface. -- The async note sits between GitHub Actions and the workflow file to emphasize GitHub-hosted automation rather than local Copilot behavior. - -### How to modify it -- **Add another reviewer asset:** insert another participant between `Agent` and `Guide`. -- **Add another step:** add a new message line in sequence order. -- **Rename the workflow:** change `archie.yml` everywhere. -- **Show additional outputs:** add another message from `WF` to `PR` or another participant. - ---- - -## 5. `diagram-5-file-placement-decision-tree.svg` - -**Type:** Mermaid-generated routing diagram - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Canvas:** `viewBox="0 0 1441.15625 336.78125"` - -### Editable Mermaid reconstruction -```mermaid -%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap. -flowchart TB - start{"What's the task?"} - - standards["Coding standards
.github/copilot-instructions.md"] - recurring["Recurring specialist task
.github/agents/"] - repeatable["Repeatable workflow
.github/skills/"] - onetime["One-time prompt or reference
.github/prompts/"] - events["Schedule, label, or PR event
.github/workflows/"] - - start --> standards - start --> recurring - start --> repeatable - start --> onetime - start --> events -``` - -### What each element represents -- **Center diamond:** the routing question the section cares about — what shape of task is this? -- **Five output boxes:** the same five file families from the quick reference and decision table. -- **Two-line box labels:** line one names the task pattern; line two gives the folder/path so you can match the task shape and drop it in the right place. - -### Layout choices -- A single fan-out keeps the emphasis on classification rather than process. -- The five destination boxes spread horizontally so the families read like peers in one routing table. -- There are no deeper branches because this section is a placement cheat sheet, not a nuanced workflow diagram. - -### How to modify it -- **Add a sixth destination:** add another box and connect from `start`. -- **Change repo paths:** update the second line in each node. -- **Simplify for a smaller image:** collapse to three outputs or split into two rows. - ---- - -## 6. `image-1-layers.png` - -**Type:** raster infographic - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Size:** `1614 x 1292` - - -### Visual metaphor and hierarchy -- **Metaphor:** the blog's nested-ring governance model. -- **Primary visual:** three concentric circles that make the control flow explicit rather than decorative. -- **Supporting callouts:** instructions above, agents to the right, and skills lower-left, each feeding into the same ring system. -- **Narrative hierarchy:** instructions shape the space -> agents interpret inside that boundary -> skills execute at the center -> the caption restates that rules constrain decisions. - -### Shapes and geometry -- White background. -- Three light-gray concentric circles. -- Three large rounded cards: top, right, lower-left. -- Two capsule labels embedded over the circles: `AGENTS` and `SKILLS`. -- Thin connector lines from the cards into the circular system. -- Bottom title block and three small centered dots. - -### Colors -Approximate palette from the rendered image: -- Background: white -- Lines and borders: light gray -- Text: black -- No accent fill colors; the design is monochrome/minimal - -### Editable production specification -Use this if recreating in Figma, Illustrator, or SVG: - -```text -Canvas: 1614x1292. Use a white or very light background (#ffffff or #f5f5f5). -All text must be black only (#000000). -All ring strokes, card borders, capsule outlines, and connector lines must be light gray (#cccccc). -All shapes should use white or very light fills (#ffffff or #fafafa) with light gray borders. -Build the composition as four clearly separated text regions: top INSTRUCTIONS card, right AGENTS card, lower-left SKILLS card, and center-copy inside the inner ring. Never let text from one region cross into another. -Center a three-ring system in the upper-middle of the canvas so it reads like nested governance rings, but reserve dedicated label lanes around it before placing any text. -Top card: use a rounded rectangle for INSTRUCTIONS with a bold all-caps heading and at most two short lines of supporting copy. Keep 20-24px internal side padding, at least 18px top/bottom padding, and at least 24px of vertical clearance between the card and any ring label below it. -Right card: place AGENTS far enough right that the card does not collide with the center copy or ring labels. Keep at least 24px between the card edge and the outer ring, and keep all supporting copy fully inside the card with 20px padding. -Lower-left card: place SKILLS far enough left and low that its body copy stays inside the card and does not run into the ring system. Keep at least 24px between the card and the outer ring. If needed, widen or heighten the card rather than shrinking padding. -Ring pills: use AGENTS and SKILLS pill labels only if each pill has its own isolated space. Do not place the AGENTS pill inside the top INSTRUCTIONS card. Keep every pill at least 12px from a ring stroke and at least 16px from any card, connector, or other text. If space is tight, move the pill outside the ring and connect it with a short leader line. -Center copy: keep the three statements inside the inner circle only, on three separate lines, with at least 20px clearance from the circle boundary. Use shorter line lengths, lighter weight, or slightly smaller type before allowing any overlap. -Connectors: keep all connectors thin and behind the composition, but do not let them pass under text. End connector lines before they enter a text box or pill. -Typography must remain readable when the image is displayed in a ~600px-wide blog column. Target an effective display scale of roughly: card headings 18-22px, supporting copy 13-15px, pill labels 16-18px, center copy 15-17px, title 24-28px, subtitle 14-16px. -At the bottom center, place the title “Layers of Governance”, then the subtitle “Rules constrain decisions, then reusable skills carry out the work.”, then three small black dots. Keep generous spacing so the footer reads separately from the diagram. -Style: minimal editorial explainer, monochrome, airy, and easy to read — more like a remembered mental model than a product UI mock. -``` - -### How to modify it -- **Best option:** edit `diagram-1-mental-model.svg` and re-export PNG. -- **If editing the PNG design manually:** keep the circle system centered and keep all callout boxes aligned to the current top/right/lower-left pattern. -- **If adding another layer:** add another ring and corresponding callout card. -- **If changing the message:** update the center copy first, then title/subtitle if needed. - ---- - -## 7. `image-2-where-they-live.png` - -**Type:** raster infographic - -### Design System (applies to all diagrams) -- **Background:** White or light gray (#ffffff, #f5f5f5) -- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc) -- **Text color:** Black (#000000) always -- **Lines/Connectors:** Light gray (#cccccc) -- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room. - -**Size:** `1400 x 900` - - -### Visual metaphor and hierarchy -- **Metaphor:** a single `.github` home with distinct rooms, matching the blog's point that these files live together but do different jobs. -- **Primary focal point:** one large neutral folder-house container on the left-middle with `.github` text in black. -- **Secondary structure:** five family labels stacked on the right, one for each room/file family. -- **Connector logic:** light-gray lines show that every family belongs to the same home while staying separate by purpose. -- **Reading order:** title -> subtitle -> shared home/container -> room labels. - -### Shapes and geometry -- White or very light full-bleed background. -- Large folder/house shape with white or very light fill and a light-gray outline, including a tab/roof shape at the upper-left. -- Five rounded pill/box labels stacked vertically on the right. -- Five diagonal light-gray connector lines from the folder body to each pill. - -### Colors -Standardized production palette: -- Background: white or very light gray (`#ffffff`, `#f5f5f5`) -- Folder house and pills: white or very light fill (`#ffffff`, `#fafafa`) -- Borders and connector lines: light gray (`#cccccc`) -- All text, including `.github`, title, subtitle, and labels: black (`#000000`) -- No accent colors, gradients, or dark theme treatments - -### Editable production prompt/specification -No separate prompt file was found in the repo; use this extracted art-direction spec: - -```text -Create a 1400x900 editorial infographic with a white or very light background (#ffffff or #f5f5f5). -All text must be black only (#000000). -All shape outlines and connector lines must be light gray (#cccccc). -Top-left: large black title “Where They Live”. -Below it: smaller black subtitle reading “A single .github home with distinct rooms for rules, specialists, reusable procedures, prompts, and triggers.” -Center-left: a large stylized `.github` folder that also reads as one shared home. Use a light background (white or #f5f5f5). Text must be black (#000000). -All shape outlines must be light gray (#cccccc). -Connector lines must be light gray (#cccccc). -Text labels for file families (copilot-instructions.md, agents/, skills/, prompts/, workflows/) must each have minimum 8–10px clearance from adjacent shapes and from each other. No overlaps. -Right side: stack five rounded rectangular pills vertically with generous spacing, one per file family. -Label them, top to bottom: -1. copilot-instructions.md -2. agents/ -3. skills/ -4. prompts/ -5. workflows/ -Connect the folder-house to each pill with its own light-gray line so each line reads like a room assignment inside the same home. -Use white or very light fills for the folder-house and each pill, keeping the design monochrome and editorial. -All text labels must have minimum 8px clearance from adjacent shapes and other text, with 8–10px preferred. -Style: clean explainer graphic, flat vector shapes, soft rounded corners, no texture, strong contrast, and a clear “live together, different jobs” message. -``` - -### How to modify it -- **Change a family name:** edit the text inside one pill only. -- **Add a new family:** add another pill to the stack and route a new light-gray connector line from the folder. -- **Change the metaphor:** keep the same connector system, but swap the folder-house for another “single home/container” shape. -- **Keep hierarchy stable:** title and subtitle stay top-left; container stays left; destinations stay right. diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-layers-of-governance.png b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-layers-of-governance.png deleted file mode 100644 index f068d011..00000000 Binary files a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-layers-of-governance.png and /dev/null differ diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-mapping-file-families.png b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-mapping-file-families.png deleted file mode 100644 index 5cbee2a8..00000000 Binary files a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-mapping-file-families.png and /dev/null differ diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-2-understanding-layers.png b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-2-understanding-layers.png deleted file mode 100644 index 6d6803c4..00000000 Binary files a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-2-understanding-layers.png and /dev/null differ diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-4-skills-vs-prompts.png b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-4-skills-vs-prompts.png deleted file mode 100644 index ee295b20..00000000 Binary files a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-4-skills-vs-prompts.png and /dev/null differ diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-5-putting-it-together.png b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-5-putting-it-together.png deleted file mode 100644 index 6045fc42..00000000 Binary files a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-5-putting-it-together.png and /dev/null differ diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-manifest.md b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-manifest.md deleted file mode 100644 index 5a4e1795..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-manifest.md +++ /dev/null @@ -1,17 +0,0 @@ -# Generated Watercolor Illustrations - -Generated on: 2026-05-31 20:47:16 - -## Images - -1. watercolor-1-mapping-file-families.png - - Purpose: Opening section and quick reference table, where the post turns scattered `.github` files into one usable mental model. - - Status: ✅ Generated - -2. watercolor-2-understanding-layers.png - - Purpose: Instructions, agents, and skills section, where the post builds the author's mental model of governance, decision-making, and reusable execution. - - Status: ✅ Generated - -3. watercolor-3-tracing-workflow.png - - Purpose: The Azure workflow section and the later decision table, where the post moves from abstract categories to a concrete path the author can actually defend with links. - - Status: ✅ Generated diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-prompts.md b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-prompts.md deleted file mode 100644 index 3d5e4f16..00000000 --- a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-prompts.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: "Watercolor Prompts for Copilot Config Files Guide" ---- - -# Watercolor Illustration Prompts - -## Style & Character -Style: Watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text -Character: Normal woman with average appearance and practical clothes in a grounded work setting - -## 1. Mapping the Five File Families -- **Narrative context:** Opening section and quick reference table, where the post turns scattered `.github` files into one usable mental model. -- **Woman's activity:** She sits at a desk with folders, notes, and small stacks representing instructions, agents, skills, prompts, and workflows, physically sorting them into a layout that finally makes sense. -- **Prompt:** Normal woman at desk sorting five distinct stacks of repository files into order, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text - -## 2. Understanding the Layers -- **Narrative context:** Instructions, agents, and skills section, where the post builds the author's mental model of governance, decision-making, and reusable execution. -- **Woman's activity:** She studies nested trays or transparent layers on a desk, lifting one layer at a time to understand how the pieces sit together instead of blending into one confusing pile. -- **Prompt:** Normal woman examining nested transparent layers of governance documents, comparing one layer to another, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text - -## 3. Tracing a Real Workflow -- **Narrative context:** The Azure workflow section and the later decision table, where the post moves from abstract categories to a concrete path the author can actually defend with links. -- **Woman's activity:** She follows a line of pinned notes and folders from one workstation area to another, checking how a label, a workflow, a reviewer, and a returned comment connect in practice. -- **Prompt:** Normal woman in home office tracing a path between pinned repository notes and workflow folders, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 59dd0901..eb3f6e2c 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -41,7 +41,6 @@ const site = require('./site.config'); // editUrl: // 'https://github.com/facebook/docusaurus/edit/master/website/blog/', path: 'blog', - exclude: ['**/media/**'], blogSidebarCount: site.blog.sidebarCount, blogSidebarTitle: site.blog.sidebarTitle, postsPerPage: site.blog.postsPerPage,