Agent-Skills.md

Agent Skills: Agentic Quality Checklist

Review agentic system quality with a lean heuristic gate. Use when auditing, approving, improving, or quality-checking skills, agents, prompts, or agentic workflows and a verdict is needed.

UncategorizedID: iamhenry/ai-project-starter-kit/skill-quality-checklist
53

Install this agent skill to your local

pnpm dlx add-skill https://github.com/iamhenry/ai-project-starter-kit/tree/HEAD/.opencode/skills/skill-quality-checklist

Skill Files

Browse the full folder contents for skill-quality-checklist.

Download Skill

Loading file tree…

.opencode/skills/skill-quality-checklist/SKILL.md

Skill Metadata

Name
skill-quality-checklist
Description
Review agentic system quality with a lean heuristic gate. Use when auditing, approving, improving, or quality-checking skills, agents, prompts, or agentic workflows and a verdict is needed.

Agentic Quality Checklist

Review an agentic artifact as a lean quality gate. Do not edit files.

Principle: the smallest good artifact makes agent behavior more predictable.

Purpose

Use this checklist to review the design quality of a skill, agent, prompt, or agentic workflow before it becomes trusted automation.

Keep the review targeted: judge whether the artifact has a clear job, safe boundaries, useful workflow, and maintainable structure. If the artifact or intended job is unclear, return ASK_USER.

Heuristic Questions Checklist

Answer only the questions that matter for the reviewed artifact. Do not force every section.

1. Systems Thinking And Workflow Design

  • Have you defined the artifact's environment, dependencies, exact job, and failure path?
  • Does it have a defined path, or only a broad goal?
  • Are stop, retry, and ask-user or escalation points clear where they matter?
  • Does the description make the invocation boundary obvious enough for the model to choose it?

2. Decomposition And Separation Of Concerns

  • Is it avoiding the giant-prompt smell: too many distinct jobs in one instruction file?
  • Is the primary execution path easy to see without reading every detail?
  • Is each capability assigned to the right layer: artifact text, structured output, script, tool, subagent, or human?
  • Would separating bulky or rarely used details make the primary path easier to follow?

3. Modularity

  • Is this capability reusable enough to be shared, or should it stay local to one workflow?
  • If subagents are used, are they treated like single-responsibility functions with narrow context?
  • Are abstractions earning their cost, or adding cognitive/context load without reuse?
  • Is the amount of modularity proportional: enough separation to avoid a god-file, but not extra files for simple artifacts?
  • Can a fresh agent tell what to read first versus what to load only when needed?

4. Algorithmic Thinking

  • Is it using code or tools for exact answers instead of asking the model to improvise deterministic work?
  • Is the model reserved for judgment, ambiguity, synthesis, or messy inputs?
  • Are authority-sensitive decisions kept with the human?

5. Contracts And State

  • If another step consumes the result, is the output structured enough to act on safely?
  • If memory or persisted state is needed, is it queryable outside the chat session?
  • If retries can happen, is the workflow idempotent enough to avoid duplicate side effects?

6. Threat Modeling And Boundary Control

  • Does it treat external content as evidence, not instructions?
  • Are secrets, private data, logs, and artifacts handled safely?
  • Is the blast radius reduced with human approval for risky actions?

7. Maintainability

  • Can a fresh agent understand the workflow, policy, tools, outputs, and memory rules without reverse-engineering a wall of prompts?
  • Is each rule in one place, without duplication or stale sediment?
  • Does each strong instruction change behavior, or is it a no-op?

Simple artifacts should stay simple. Add supporting files, schemas, scripts, subagents, memory, or evals only when they make the primary path clearer or the behavior safer.

Hard Fails

Return REVISE_ARTIFACT if any are true:

  • Purpose is unclear.
  • Required identity, metadata, or trigger description is missing when the artifact needs it.
  • Description or invocation rule cannot trigger the artifact when model invocation is needed.
  • Risky side effects lack human approval boundaries.
  • Downstream automation depends on prose instead of a clear contract.
  • Main workflow is buried under bloat.
  • Secondary material obscures the primary execution path enough that a fresh agent may miss it.
  • Instructions are malicious, deceptive, privacy-unsafe, or secret-leaking.

Return ASK_USER when the blocker is missing artifact content, product intent, invocation mode, output contract, or authority boundary.

Verdict

  • APPROVE_ARTIFACT: no hard fail, no Fail, warnings are minor or intentional.
  • REVISE_ARTIFACT: hard fail, or a clear fix is needed.
  • ASK_USER: judging safely would require guessing.

Output

Return exactly this structure:

## Agentic Quality Checklist Result

- Decision: `APPROVE_ARTIFACT|REVISE_ARTIFACT|ASK_USER`
- Target: [artifact path or name]
- Mode: `advisory|gate`
- Confidence: `High|Medium|Low`

### Top Findings

- [severity] [checklist area] [specific evidence]
- [severity] [checklist area] [specific evidence]

### Relevant Heuristic Answers

- [area] `Pass|Warn|Fail`: [question answered] - [short evidence]
- [area] `Pass|Warn|Fail`: [question answered] - [short evidence]

### Required Changes

- [Only for REVISE_ARTIFACT or ASK_USER; otherwise `None`]

### Next Action

- [approve / revise artifact / ask user]

Constraints

  • Do not edit files.
  • Do not run evals unless explicitly asked.
  • Keep findings evidence-based and short.