Guide · Agent skill
How to use the AI Workflow Diagnostics agent skill (diagnose)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The diagnose skill is an agent skill that asks your AI assistant to review an AI workflow or agent setup across five areas: prompt quality, context efficiency, tool health, architecture fitness, and safety and reliability. It returns a scored report with critical findings and recommended actions. This guide explains what an agent skill is, how to install this one, how to trigger it, and where its limits are.
AI Workflow Diagnosticsgithub/awesome-copilot · MIT Download the skill Quick start
- 1Download the ZIP. Get the diagnose skill ZIP from the directory page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or .claude/skills/ inside a project.
- 3Or upload in the Claude apps. Go to Settings → Capabilities → Skills and upload the skill there instead.
- 4Gather your workflow material. Collect the prompt text, tool list, and description of how the agents work together.
- 5Ask for a diagnosis. Describe the task in plain language, such as asking the agent to diagnose or health-check the workflow, and paste the material.
- 6Review the scored report. Read the five scores, the critical findings, and the recommended actions, starting with the most severe.
What an agent skill is and what this one makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load when a task matches them. This skill's SKILL.md tells the agent to act as a systematic AI workflow auditor.
When invoked, the agent checks each of five dimensions and scores each one from 1 to 5 with specific findings. It then lists the most serious problems and a prioritized set of concrete fixes.
- Prompt Quality: structure, output schema, instruction clarity, edge cases, anti-patterns
- Context Efficiency: context budget, critical information placement, context window use, state and memory
- Tool Health: tool count, descriptions, error handling, schema completeness, idempotency, scope
- Architecture Fitness: single vs. multi-agent topology, agent boundaries, handoffs, observability, cost awareness
- Safety & Reliability: input validation, output filtering, cost controls, error recovery, evaluation strategy
Install the diagnose skill
Download the ZIP for the skill from the directory page, then choose one of the following methods.
For a personal install across your projects, unzip the download into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
The download contains one file, SKILL.md, so the unzipped folder should contain that file.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with a natural request
You do not need a special command. Ask the agent in plain language to diagnose your workflow, and paste in what it needs to review. The skill works from text you provide, so include the workflow description, prompt text, tool list, or agent configuration.
The skill's own usage notes say the more detail you provide, the more precise the findings will be.
- Diagnose this agent workflow and score it across the five dimensions. Here is the system prompt and tool list: [paste]
- Run a health check on my agent before I ship it. Here is the description of how it works: [paste]
- We changed the prompts and tools this week. Audit the setup and give me a prioritized fix list: [paste]
Read the diagnostic report
The report starts with a score table, one row per dimension, and an overall score out of 25. Below it are critical findings in order of severity, followed by recommended actions that map to those findings.
Scores use a fixed guide. A 5 means production-excellent with no action needed. A 3 means functional but risky, where you should add error handling or reduce complexity. A 2 means significant issues needing immediate attention, such as adding retries or guards. A 1 means broken or missing, where the advice is to rebuild with clear structure.
Safety notes and limits
This skill runs no scripts and makes no network calls. It does not run your code or connect to outside services. It reviews only the text and configuration you give it.
Because of that, it cannot confirm how a live workflow actually behaves. Its scores are judgement-based from the descriptions it reads. The safety dimension is a checklist-style review, so it does not replace penetration testing or a compliance audit.
For tool health, the skill separates tools your project controls (custom scripts, project MCP servers) from agent-level tools (built-in IDE tools, global MCP servers), and only flags overhead for tools the project can control.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
Tips for better results
Give the skill the actual prompt text and the full tool list, not a summary. Descriptions of tools are judged on their specificity, so vague summaries lead to vague findings.
If you change things after a review, run the diagnosis again on the updated setup and compare the scores. For the safety dimension, the skill scopes output filtering by context: data passed between your own frontend and backend is treated as lower risk than data sent to external services, so say which applies.
- Paste full prompts and complete tool definitions
- Include how the agents hand work to each other, if there are several
- Mention which data goes to external services
- Ask for the prioritized fix list if you want to act on it straight away
What people use it for
- Reviewing a customer-support agent's prompts and tool list before a production launch
- Health-checking a multi-agent pipeline after changing its handoff logic
- Finding tools with vague descriptions or missing error handling in an existing agent
- Checking whether a workflow has cost ceilings and evaluation tests before it goes live
- Producing a prioritized fix list for a team to work through in order
Frequently asked questions
How do I install the diagnose agent skill?
Download the ZIP from the directory page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Does the diagnose skill cost money or require a licence?
The skill is licensed under MIT, as listed on the directory page. The source does not list any prices or other requirements, and the skill is listed as requiring nothing.
What does the diagnose skill need to run?
The listing says it requires nothing, runs no scripts, and uses no network. It works from the text you paste in: prompts, tool lists, or a workflow description.
Can the diagnose skill test my live AI agent?
No. It reviews only the text and configuration you provide and cannot confirm how the workflow actually performs. Its scores are based on judgement from the descriptions.
Is the diagnose skill a replacement for security testing?
No. The safety dimension is a checklist-style review, not a penetration test or compliance audit. Use formal security testing for those needs.
What should I do if the skill does not appear or does not trigger?
Check that the unzipped folder contains SKILL.md and sits in ~/.claude/skills/ or the project's .claude/skills/ folder. Then ask for the diagnosis explicitly and paste your workflow material, since the skill works from that text.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use diagnose if you have built an AI agent or workflow and want a structured review before production, a health check after changing prompts or tools, or a prioritized fix list. Pick something else if you need a test of how a live system actually behaves or a formal security or compliance audit.
Download the skill