| name | agent-review |
| description | Review and audit a Pi agent markdown file for spec compliance and design quality. Use when: reviewing an agent file, checking if an agent is ready to deploy, auditing agent description or system prompt quality. Do NOT use when: reviewing a skill directory (use skill-review), designing a new agent (use brainstorming), or testing agent runtime behavior. |
Agent Review
Purpose: Audit a Pi agent markdown file for spec compliance and design quality.
Input: Agent file path from user.
Output: Diagnostic report grouped by severity, with evidence and concrete fixes.
Prerequisite Check
If the agent file path is not provided, ask before proceeding:
Which agent file should I review? Please provide the path.
Example: agents/my-agent.md
Verify the file exists and ends in .md. If not, stop and report.
Workflow
Phase 1: Load References
Read both reference files before starting the review:
references/agent-spec.md — Pi frontmatter format rules and valid field valuesreferences/rubric.md — 8 review dimensions with criteria and severity guidance
Phase 2: Frontmatter Review
Read the target agent file. Extract the YAML frontmatter block (between --- delimiters).
Check against agent-spec.md:
- All four fields present:
name, description, tools, model
name matches the filename (without .md extension)name format: lowercase-hyphenated, 1–64 chars- Each value in
tools is from the valid list in agent-spec.md
model is a recognized value
Phase 3: System Prompt Review
Read the system prompt body (everything after the closing ---).
Evaluate against all 8 dimensions in rubric.md:
- Frontmatter 合规 (covered in Phase 2)
- 身份清晰度
- 输入规格
- 工作流结构
- 输出格式
- 失败处理
- Guardrails
- 工具最小化
For each dimension: cite the exact line or section from the agent file as evidence. If a dimension passes cleanly, note it as passing — do not skip it silently.
Phase 4: Write Report
Produce the diagnostic report using the Output Format below.
Output Format
Start with this summary block:
## agent-review: <filename>
Found: X critical, Y warnings, Z suggestions.
Dimensions evaluated: 8 / 8
Use this format for each finding:
### [SEVERITY] Dimension N: <Dimension Name>
Labels: SPEC | BEST_PRACTICE | PROJECT_POLICY
**Issue:** One sentence describing the problem precisely.
**Evidence:**
<exact quote or concrete file state>
**Why it matters:**
<one sentence on impact>
**Suggested fix:**
<concrete replacement text or specific action>
Severity levels:
[CRITICAL] — prevents correct loading or execution[WARNING] — degrades reliability or output quality[SUGGESTION] — improvement opportunity
Group findings: CRITICAL first, then WARNING, then SUGGESTION.
If a dimension has no issues, include a one-line pass note after the findings section.
Done Criteria
- Both reference files were loaded before review started.
- All 8 dimensions were evaluated (none skipped).
- Every finding cites exact evidence from the agent file.
- Report starts with the summary block.
- Report language follows the user's language.
Guardrails
Every finding must cite an exact quote or concrete file state. No exceptions.
- Do NOT invent issues. If you cannot point to a specific line, do not report it.
- Do NOT skip dimensions because the agent "looks fine". Evaluate all 8.
- Do NOT merge multiple distinct issues into one finding.
- Do NOT label a project preference as a spec violation.
