An inspection for AI workflows you built yourself. Hand over your prompt text, tool inventory, or agent config, and you get a 1 to 5 score on five dimensions, an overall score out of 25, and the fixes ranked by severity.
Prompts, Skills, multi-agent pipelines: once they run end to end, most people call them done. The structural problems that break them in production were already there the moment the first run succeeded.
diagnose is a diagnostic Skill. It scores Prompt Quality, Context Efficiency, Tool Health, Architecture Fitness, and Safety & Reliability from 1 to 5 each, then returns a scorecard out of 25 with the critical findings and the fixes ordered by severity.
What comes back is not a generic checklist. A score has to land on a specific layer, and every finding has to cite its evidence.
In each pair, the left side is the state before you use it and the right side is what you hold after a diagnosis.
Once an AI workflow is built, there is usually one signal available for judging it: it ran without errors. Whether the output format is defined, whether it recovers from failure, whether cost has a ceiling, you reconstruct all of that from memory afterward.
Five dimensions, each scored 1 to 5, each one stating where points were lost. Anything under 3 is flagged, so you can see which layer the problem sits in.
From “looks fine to me” to “I know which dimension scored 2, and why.”
The problems are scattered across prompts, scripts, config, and memory. Reviewing the workflow means rereading every file, and with no fixed format to compare against, you finish with an impression rather than a list.
A report out of 25: five dimension bars with an overall score, three critical findings ranked by severity, and the fix for each one.
From “I think this part might be a problem” to “these three are what to fix now.”
A prompt you can still eyeball from experience. Once the scripts multiply and the layers deepen, there is no general way to check it, and the more files there are, the more you miss.
One scoring scale covers three orders of magnitude: a single-file prompt, a multi-stage gated pipeline, and a system with scripts and external side effects.
From “only prompts are auditable” to “1 file or 52 files, same scale.”
| Dimension | CASE 01 | CASE 02 | CASE 03 |
|---|---|---|---|
| Subject | Single-file prompt Skill | Multi-stage gated pipeline | Execution system with real side effects |
| Files | 1 | 10 | 52 |
| Scripts | 0 | 0 | 37 |
| Size (bytes) | 7,535 | 39,992 | 1,921,632 |
| Prompt Quality | 4 | 5 | 4 |
| Context Efficiency | 3 | 3 | 4 |
| Tool Health | 2 | 2 | 2 |
| Architecture | 4 | 4 | 3 |
| Safety & Reliability | 4 | 5 | 3 |
| Overall | 17 / 25 | 19 / 25 | 16 / 25 |
| Most damaging finding | A declared script does not exist | A tool capability the flow requires was never declared | Undeclared webhook and command-execution channels |
All three situations below come from real workflows. None of them is hypothetical.
A prompt Skill at 123 lines / 7,535 bytes. The logic is clear, the steps are complete, every path and version number is spelled out. It reads like a finished product you can use as is.
But it points to six scripts described as already included and ready to copy, and those six files were never in the package. The author had them on their own machine. The reader does not.
A gated copy pipeline whose output contract, banned-word list, and self-check are written more carefully than most. Its anti-fabrication rules run four levels deep on evidence.
Yet it puts searching official pages to verify links into the required flow, whenever the network happens to be available, while the documentation never declares a single tool capability.
An execution system across five exchanges with 37 scripts. Credentials live only in environment variables, every order is confirmed by the user first, and no pre-trade check is missing.
But one script marked optional can POST data to any URL, and can execute an external command named by an environment variable. Neither channel appears in its capability declaration.
They share one property: they run clean and they pass the tests. They only surface in a particular environment, on a particular call path. So no check for “does it work” will ever stop them.
And the tools people reach for by default do not operate on this layer. Prompt-writing articles hand you a generic checklist that never looks at your workflow. Code checkers understand syntax but cannot tell whether a prompt defines its output format. Rereading the files yourself mostly surfaces what you meant when you wrote them, not the gaps in the structure.
What you get is delayed exposure. The problem does not appear while you are building. It appears when other people start using it, after launch, once it starts moving real money.
What is missing is not more experience. It is one review run against fixed dimensions. Structural problems only come out under direct questioning: does this section define its output? Do the declared tools match actual behavior? What happens after a failure? Is there a ceiling on cost?
diagnose is that questioning, made repeatable. It splits the review into five fixed dimensions and asks the same questions every time, so two diagnoses land on the same scale and a revision shows up as better or worse.
Three steps from input to output, and nothing in between needs configuring.
Any one of these four is enough to start. The more specific you are, the sharper the findings.
Whether role, context, instructions, and output region each sit where they should, whether the output format is written down or left implied, whether edge cases are covered, and whether obvious anti-patterns are present.
Whether the budget was planned, whether key information sits at the start or the end, whether state and memory are managed explicitly or left to defaults, and whether length matches the task.
Whether the tool count sits in a workable range, whether descriptions are specific, whether error handling exists, whether input, output, and error are all defined, and whether repeat calls are safe. It also separates the tools a project configures from the tools an agent brings with it, and only counts the first group.
Whether a single agent is enough, whether multiple agents are genuinely needed, whether boundaries overlap, whether handoffs have a protocol, whether decisions leave a trace, and whether cost has a budget.
Input validation, output filtering, cost ceilings, failure recovery, evaluation strategy. Risk is judged against how far the data actually travels, not against a blanket maximum.
All three cases are real workflows scored against its five dimensions in this session. Every score and every finding can be checked line by line.
A single-file prompt Skill that audits websites with a real headless browser. Its own rule: every conclusion has to trace back to a number, a screenshot, or a raw response.
17 / 25. The most damaging finding is a missing packaged dependency: the flow states that six reusable scripts live in audit/ and can simply be copied, while a full search for all six filenames returns 0 hits and the directory does not exist. The other two environment claims in the same document, the Chromium binary path and the playwright-core install location, both checked out as true.
True and false claims sit in the same stretch of text. Trusting the whole block misses the break, and doubting the whole block wrongly discards two correct claims. Only checking line by line works, and that is exactly what a manual reread skips.
A copy-production pipeline with a fixed nine-section output contract, three human gates, four evidence tiers, and 11 final self-checks. It explicitly bans fabricated screenshots, data, and links.
19 / 25, the highest of the three. The typical gap is an empty tool contract: the flow requires searching official pages to verify links whenever the network is available, while the documentation declares no tool capability at all, so the same workflow behaves differently on different hosts. Each invocation also carries a fixed 35,363-byte preload that cannot be trimmed on demand.
Its anti-fabrication design is the strongest of the three, and its score is in fact the highest. Scoring is not fault-finding. It also registers what was done right.
An algorithmic execution system across five exchanges that can create, modify, and cancel real orders. Credentials stay in environment variables, and every write requires user confirmation.
16 / 25, the lowest of the three. The core finding is a declared surface smaller than the actual behavior: one script marked optional can POST data to any URL and execute an external command named by an environment variable, and neither channel appears in the capability declaration. On top of that, all 37 scripts sit flat in one directory, which makes choosing between them costly.
The more complex the workflow, the more likely it carries an undeclared capability surface, and a single functional test never reaches that gap. It will not turn any test red.
The scores, file counts, line counts, and search results in all three cases come from this session's runs against the five dimensions, and can be verified one by one in diagnostic-runs.md. The scorecard, the key findings, and the comparison table in section 02 are rendered from that same record: they visualise the data, they are not screenshots of an interface. If real screenshots become available, they can replace them.
Because the five dimensions are scored separately, a 2 points to a specific layer. Tool Health scored 2 in all three cases for three different reasons: a missing dependency, an empty tool contract, and tool overload.
A blanket “too many tools” would misjudge two of them. Layered scoring does not.
Its rules require concrete findings for every dimension, not just a number. The zero hits for six scripts, the fixed 35,363-byte preload, and the undeclared POST channel in the three cases all trace back to something you can check.
Whoever holds the report can verify it themselves, without first trusting the reviewer.
The dimensions, the score range, and the meaning of the five bands are fixed. Score again after a change and both numbers land on the same scale, so you can see whether it improved or regressed instead of re-deciding from scratch.
That is what a generic checklist cannot give you, because a checklist has no score.
Tool Health carries a specific rule: separate the tools a project configures from the tools an agent ships with or installs globally, and deduct only for the first group. Otherwise a report charges your host environment’s tool count to you, and it reads as a long list of problems you cannot fix.
Every finding left in the report is one you can act on.
What diagnose changes is not the result of one review. It is where in the timeline the discovery happens.
Put a fixed check between “it runs” and “you ship it”, and problems move from the moment someone hits them to before it goes out. Because the dimensions are fixed, the check is reusable: score again after editing the prompt, after adding a script, after switching hosts, and every score lands on the same scale.
One diagnosis leaves you with more than three fixes. It also shows which dimension of your own workflow is thinnest. Once you know that, the next workflow you build starts with that layer reinforced.
Diagnose
AI workflow diagnostic Skill · five dimensions · a report out of 25
gh skills install github/awesome-copilot diagnose
Requires GitHub CLI v2.90.0+
Official source: github/awesome-copilot · skills/diagnose
A workflow description, prompt text, a tool inventory, or an agent config. Any one of the four is enough to start.
A 1 to 5 score on five dimensions, a scorecard out of 25, and the critical findings with fixes ordered by severity.