agentops-awesome-list

name

agentops-awesome-list

description

Use when performing a read-only, interactive health check of an agent, multi-agent workflow, agent framework template, MCP-enabled assistant, memory system, evidence gate, state machine, eval loop, or self-evolution design, especially to compare it against a complete agent architecture baseline and find missing components. This skill must clarify the user's intended purpose before final scoring and must produce a Markdown health-check report with only audit findings, risks, and optimization suggestions, not implementation changes.

Agent Optimization Health Check

Overview

This skill is an interactive diagnostic plugin for agent architecture. It is not an agent runtime, not an agent framework, not an optimizer, and not an implementation planner.

Its job is to inspect a target agent project, clarify the user's intended use case through conversation, select the right completeness template, then produce a Chinese health check report with architecture gaps, functional risks, and optimization advice.

The output is advisory only and should be delivered as Markdown. The skill may recommend concrete improvements, but it must not implement them, rewrite the target project, delete files, create optimization branches, or turn recommendations into a work plan unless the user starts a separate implementation request.

Core principle: first compare the target against the complete agent architecture baseline, then judge gaps against the user's purpose and difficulty tier. Do not require enterprise features for a personal assistant, and do not accept a prompt collection as a production agent system.

Scope Guard

Use this skill only for diagnosis, review results, and recommendations.

• Do not modify the target project during the health check.
• Do not implement optimizations during the health check.
• Do not produce a step-by-step implementation plan as the main deliverable; provide prioritized recommendations and acceptance checks instead.
• Do not run fix, repair, apply, migration, generation, or destructive commands against the target project. Read-only commands and safe dry-run/smoke checks are allowed when they support the audit.
• The only allowed write during a health check is an explicit Markdown audit report requested by the user. Prefer a user-specified path; otherwise ask before writing. Do not change source, config, runtime, agent, or knowledge files as part of the health check.
• Do not treat this skill itself as an agent base.
• Do not assume the target is production-grade, enterprise-grade, or a framework.
• Do not mix in previous project history unless the user asks for historical comparison.
• Do not score "planned later" as implemented.
• Do not skip user-purpose clarification before final scoring unless the user explicitly asks for a quick, assumption-based pass.

Required Interaction Flow

1. Read the target first

Collect enough local evidence before asking broad questions. Prefer these files when present:

• README*, AGENTS.md, CLAUDE.md, redmaple.md, or project instructions
• package.json, pyproject.toml, config files, scripts, entrypoints
• agents/, .agents/, .claude/agents/, .project/, knowledge/
• MCP configs, tool definitions, workflow/state/evidence/eval files
• tests, evals, run logs, docs, and generated reports

If the user gives no repository path, ask for the target path or inspect the current workspace only after confirming it is the intended target.

2. Clarify the user's goal

Clarification is a hard gate before final scoring. After reading the target, pause and ask the user to confirm the intended purpose, deployment scope, and risk boundary unless the current user request already answers them or explicitly says "快速审查 / 不用问 / 按假设继续".

Use a brainstorming-like dialogue:

• Ask one concise Chinese question at a time.
• Start with a short evidence summary, then ask the most important missing question.
• Do not dump all questions at once unless the user asks for a questionnaire.
• After each answer, decide whether another question is needed.
• Do not produce the final health check report until the core purpose and risk assumptions are confirmed or explicitly waived.

Default clarification questions:

1. 这个 agent 主要服务什么任务或业务场景？
2. 它是个人本地使用，还是团队、客户或多用户使用？
3. 它会不会写文件、执行命令、调用外部 API、MCP 或其他工具？
4. 它是否需要长期记忆、项目状态恢复、多 agent 交接或审查门？
5. 错误操作的风险等级是什么：低风险建议、文件修改、生产数据、资金、隐私/合规？

If the user asks for a quick pass, does not answer, or explicitly authorizes assumption-based scoring, continue with clear assumptions and mark confidence lower.

3. Select a difficulty template

Read references/difficulty-templates.md when choosing the tier.

Tier	Use when
T0 Simple Conversation	The agent only answers in chat and has no tools or durable state.
T1 Personal Assistant	The agent uses tools for one user and needs approval for actions.
T2 Entertainment Project	The agent runs interactive stateful experiences such as games or roleplay.
T3 Production Project	The agent writes files, calls tools, coordinates work, or may affect real users/data.
T4 Enterprise Project	The agent is multi-user, multi-tenant, regulated, cross-team, or mission-critical.

Choose the highest tier triggered by the target's actual behavior and risk. State why the selected tier fits.

4. Audit the architecture

Always read references/complete-agent-architecture.md and references/component-map.md before final scoring. Use the complete baseline to find missing components, then use the component map to inspect evidence, red flags, and implementation detail. Load additional references only when the target needs them:

Situation	Read
multi-agent, handoff, workflow, A2A, MCP, state machine	references/multi-agent-protocols-state.md
memory, knowledge base, self-evolution	references/memory-and-evolution.md
evidence gates, project ledger, operation records	references/project-evidence-gates.md
evals, safety, release gates, risk controls	references/evaluation-and-risk.md
open-source comparison requested	references/open-source-framework-scan.md and references/source-map.md

Score each component as:

• missing: no meaningful implementation or contract exists.
• weak: docs/prompts exist, but no reliable execution or validation path.
• adequate: implemented enough for the selected tier with clear evidence.
• strong: implemented, validated, observable, and maintainable.
• not-needed: not required for the selected tier or stated purpose.

Completeness gate:

• Every baseline component in references/complete-agent-architecture.md must be classified before the final report.
• Use present, weak, missing, or intentionally-not-needed for baseline presence, and separately note the tier requirement as required, lightweight, optional, or not-needed.
• Do not treat an unmentioned component as not-needed. If evidence is absent, score it as missing or weak.
• If a required baseline component is missing or weak, the verdict cannot be ready.
• Difficulty tiers decide priority and implementation depth; they do not hide the component from the audit.

5. Produce the Markdown report

The final answer must be in Chinese unless the user requests another language. Lead with practical findings, not methodology.

The final deliverable is a Markdown health-check report:

• If the user only asked for a report, output Markdown in chat.
• If the user explicitly asks to "落实为 md", "保存报告", "生成报告文件", or provides a report path, write the Markdown report to disk.
• If no path is specified, ask where to save it. A safe default is agentops-health-check-YYYY-MM-DD.md in the current working directory or a clearly named audit/report folder chosen by the user.
• Writing this report file is not permission to edit the target project itself.

Use this output contract:

## 体检结论
- 判定：ready / risky / blocked
- 适用模板：T0 / T1 / T2 / T3 / T4
- 一句话结论：
- 置信度：high / medium / low

## 用户目标与审查边界
- 我理解的目标：
- 已向用户确认的信息：
- 当前假设：
- 不在本次审查范围内：

## 完整架构基线
| 基线组件 | 难度要求 | 状态 | 当前证据 | 缺口 / 不需要的理由 |
|---|---|---|---|---|

## 缺失组件清单
| 优先级 | 缺失组件 | 为什么重要 | 建议补齐方式 |
|---|---|---|---|

## 架构地图
| 模块 | 当前证据 | 评分 | 说明 |
|---|---|---|---|

## 功能审查报告
| 功能/能力 | 是否存在 | 完整度 | 主要问题 | 建议 |
|---|---|---|---|---|

## 关键问题
| 优先级 | 问题 | 为什么重要 | 建议修复 |
|---|---|---|---|

## 优化建议
| 优先级 | 建议 | 预期收益 | 实施成本 | 验收方式 |
|---|---|---|---|---|

## 下一步
1. ...
2. ...
3. ...

The report may include recommended fixes, but it must frame them as advice with acceptance checks. Do not present the recommendations as work already performed, do not stage edits, and do not continue into implementation from this skill.

When a report file is written, state the absolute path and summarize that no source/config/runtime files were changed.

Component Checklist

Use this checklist according to the chosen tier. Do not force every item when it is not needed.

This table is a digest for quick reading. The mandatory completeness baseline is references/complete-agent-architecture.md; do not skip it when producing the final health-check report.

Area	What to check
Task intake	Intent classification, constraints, unsupported tasks, success criteria.
Agent loop	Observe/plan/act/review loop, stop conditions, retry limits.
Model layer	Model selection, prompt versioning, structured output, fallback.
Tool layer	Tool schemas, permissions, dry-run, idempotency, retry, timeout, rollback.
State machine	Explicit states, legal transitions, checkpointing, recovery.
Project ledger	Current objective, decisions, operations, evidence, versions, gate log.
Evidence system	Claim-to-evidence mapping, source paths, freshness, trust level.
Gate system	Evidence gate, risk gate, human approval, postcondition checks.
Sessions/users	Session isolation, user/project scope, retention, RBAC if needed.
Memory	Working, short-term, long-term, write gates, conflict and decay rules.
Retrieval/context	Ranking, citations, compression, untrusted-content boundaries.
Artifacts/workspace	Artifact owner, version, checksum, provenance, sandbox policy.
Registry/routing	Agent identity, capabilities, health, route policy, fallback.
Multi-agent handoff	Task packet, accept/reject, review, complete/fail/cancel lifecycle.
Coordination/conflict	Shared state, locks/leases, artifact ownership, arbitration log.
A2A/MCP	Capability discovery, typed tools/resources, auth, trust boundary.
Observability	Tool spans, state diffs, memory write logs, cost/latency metrics.
Evaluation	Golden tasks, trajectory eval, regression, red-team, canary/shadow.
Guardrails	Prompt injection, tool misuse, secret handling, data leakage.
Self-evolution	Candidate change, sandbox test, eval gate, human approval, rollback.

Report Rules

• Cite concrete files, scripts, configs, or missing paths as evidence.
• Separate "exists in documentation" from "enforced by code/runtime".
• Separate "template placeholder" from "working feature".
• Include the complete architecture baseline and missing component list in the final report.
• Do not hide a missing component by calling it optional without explaining the selected tier and reason.
• Use not-needed for modules outside the selected tier.
• Prefer a short prioritized fix list over a giant undifferentiated checklist.
• If the user asks whether the skill helps, explain what new risks or missing modules the skill surfaced compared with a normal code read.

Common Mistakes

Mistake	Correction
Auditing before knowing the target purpose	Ask goal/risk/deployment questions, then select a tier.
Treating every target as enterprise	Match the selected template; mark extra modules as optional.
Calling prompts an architecture	Require loop, state, tools, evidence, evals, and failure handling when the tier demands them.
Counting TODOs or placeholders as features	Score placeholders as weak or missing.
Giving only abstract advice	Tie every recommendation to a concrete missing module or file.
Editing the project during audit	Keep the health check read-only unless user explicitly asks to implement fixes.
Hiding uncertainty	State assumptions and confidence clearly.

Self-Update Protocol

Only update this skill when the user explicitly asks to improve the health-check plugin, or when repeated audit failures show that the checklist misses an important agent architecture issue.

1. Verify recency-sensitive facts with current sources before changing reference claims.
2. Put durable research facts in references/source-map.md.
3. Put practical audit rules in the relevant reference file or this SKILL.md.
4. Record accepted updates in references/update-ledger.md.
5. Keep this file focused on interaction flow and report contract.
6. Validate the skill folder after edits when a validation script exists.