Teach builder to author DeepAgents skills

agent_builder/skills/agent-quality-review/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: agent-quality-review
+description: Review a generated a2a-pack agent before sandbox testing or deploy. Use to catch broken cards, missing schemas, fake tools, unwired DeepAgents skills, missing runtime mirrors, unsafe IO, and stale live Agent Card schemas.
+---
+# Agent Quality Review
+
+Before `test_agent_in_sandbox` and before deploy, review the generated project
+as source code, not just as text.
+
+## Required Files
+
+Every generated project needs:
+
+- `agent.py`
+- `a2a.yaml`
+- `requirements.txt`
+- Optional `skills/<skill-name>/SKILL.md` bundles for nontrivial DeepAgents
+  behavior
+
+Run `list_agent_files` and read the files that matter. If the project was
+deployed before, use `sync_agent_workspace_from_repo` before editing when the
+builder needs to continue from the current managed repo source.
+
+## Agent.py Review
+
+Check these items:
+
+- Public `@skill` methods are async and have `RunContext[...]` plus typed JSON
+  arguments.
+- The public schema is small and stable. No unbounded command strings, hidden
+  prompt fragments, or provider credentials as public inputs.
+- The implementation reads `ctx.llm` when `llm_provisioning` is
+  `CALLER_PROVIDED`.
+- Any use of DeepAgents file tools passes `backend=ctx.workspace_backend()`.
+- Any project skills are seeded into the backend and passed with
+  `skills=skill_sources or None`.
+- Custom subagents that need project skills include their own `skills` field.
+- Deterministic tools do exact work; no fake canned-response tools.
+- File-producing skills call `ctx.write_artifact` and `ctx.emit_artifact`.
+- External calls, secrets, workspace access, pricing, and resources are
+  declared on the class.
+
+## A2A YAML Review
+
+Mirror deployment-only details in `a2a.yaml` because the platform reads it
+before importing user code:
+
+```yaml
+name: research-agent
+version: 0.1.0
+entrypoint: agent:ResearchAgent
+expose:
+  public: true
+runtime:
+  apt_packages: [ffmpeg]
+  resources:
+    cpu: "2"
+    memory: 2Gi
+    max_runtime_seconds: 900
+```
+
+Use `runtime.apt_packages` only for Debian system binaries. Python packages
+belong in `requirements.txt`.
+
+## Sandbox And Live Card
+
+Always run `test_agent_in_sandbox(name)` before deploy. Treat nonzero exit as
+source failure, then read stderr, edit, and rerun.
+
+After `cp_deploy_tarball`, compare `live_skills[].input_schema` with the
+actual public `@skill` signatures. If a live schema is missing an argument or
+shows an old shape, refresh or redeploy until the live Agent Card matches the
+source.
+
+## Minimal Good Result
+
+For most generated agents, a good result is one public A2A `@skill`, one
+workspace-backed DeepAgent, one or two internal DeepAgents skills, and a few
+small deterministic tools. Resist broad endpoint sets unless the user asked
+for a multi-operation agent.