@standardagents/skill 0.15.3 → 0.16.1-next.1e58032

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/skill",
-  "version": "0.15.3",
+  "version": "0.16.1-next.1e58032",
   "private": false,
   "publishConfig": {
     "access": "public",

package/skills/agentbuilder/SKILL.md

@@ -33,7 +33,7 @@ For deeper reference material that this skill links to, see:
 
 ## Before you write any code
 
-Most failed Standard Agent projects fail in the same six ways. Read this section first and answer all six questions explicitly before creating any code. Each links to the deeper section that explains *how*.
+Most failed Standard Agent projects fail in the same seven ways. Read this section first and answer all seven questions explicitly before creating any code. Each links to the deeper section that explains *how*.
 
 **1. Architect the agent graph before picking types.**
 List the domains the system touches. Determine the tree (coordinator → domain agents → sub-domain agents). *Then* decide what each node is. Do not start by writing one agent and bolting tools onto it. → [Architecture & decomposition](#architecture--decomposition)
@@ -53,6 +53,9 @@ Fetch the official current docs. Confirm auth, base URL, endpoint paths, payload
 **6. Check `ThreadState` before adding any dependency.**
 Before reaching for S3, Redis, an external cron, a queue service, or even `node:fs`, confirm the framework does not already provide the capability via `ThreadState`. It almost always does. → [ThreadState first](#threadstate-first)
 
+**7. Ship complete, polished definitions — not skeletons.**
+A new agent is not done when it typechecks. It is done when it has a specific name, a `description`, an `icon`, human side labels, session tools wired in all three required places, and a prompt that handles the realistic edge cases of its domain. → [Creating a new agent: the completeness bar](#creating-a-new-agent-the-completeness-bar)
+
 ---
 
 ## What is a Standard Agent?
@@ -253,6 +256,140 @@ A `dual_ai` agent with no `sessionStop`, no `sessionFail`, and no `maxSessionTur
 
 ---
 
+## Creating a new agent: the completeness bar
+
+The most common quality failure when a coding agent creates a Standard Agent is **shipping a skeleton**: a bare `name`, no icon, sides called "Side A" and "Side B", a two-sentence prompt, and session tools that are bound on the agent but missing from the prompt's tool list. The agent typechecks, runs once, and then behaves badly in every way that matters. Hold every new agent to the bar in this section before calling it done.
+
+### Identity & presentation (required, not optional)
+
+| Field | Bar | Bad | Good |
+|---|---|---|---|
+| `name` | snake_case, domain + role. Suffix coordinators `_coordinator`, reviewers `_reviewer`, leaf agents `_agent`. | `assistant`, `my_agent`, `helper` | `gmail_agent`, `invoice_audit_reviewer`, `marketing_comms_coordinator` |
+| `description` | One concrete sentence: what it does, for whom, with what. Shown in UIs. | "An agent that helps with email." | "Triages the support inbox, drafts replies for known issues, and escalates unknowns to a human queue." |
+| `toolDescription` | Written for the **calling model**, not a human: when to choose this tool, what the key arguments are, what comes back. Required when `exposeAsTool: true`. | "Research agent." | "Research a topic with web search and source-backed URLs; returns a cited answer after an internal sufficiency review. Use for questions that need current or verifiable facts." |
+| `icon` | Always set one. See below. | omitted | inline SVG data URI or hosted URL |
+| `sideA.label` / `sideB.label` | Always set both on `dual_ai`. Name the **roles in the conversation** — they appear in the UI and logs. | "Side A" / "Side B", "AI 1" / "AI 2" | "Researcher" / "Reviewer", "Pilot" / "ATC", "Drafter" / "Editor", "Support" / "Customer" |
+
+Side labels are also a design check: if you can't name the two roles, side_b probably doesn't have a real job yet — go back to [Session boundary discipline](#session-boundary-discipline).
+
+### Icons
+
+Every agent gets an `icon`. Don't skip it because no asset exists — author one. The value is any image URL, and an inline SVG data URI is self-contained and needs no hosting:
+
+```ts
+// agents/agents/invoice_audit_agent.ts
+const icon = `data:image/svg+xml;utf8,${encodeURIComponent(
+  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+    <rect width="32" height="32" rx="7" fill="#0f766e"/>
+    <path d="M10 9h12v14l-3-2-3 2-3-2-3 2z" fill="none" stroke="#ffffff" stroke-width="2" stroke-linejoin="round"/>
+    <path d="M13 14h6M13 18h4" stroke="#5eead4" stroke-width="2" stroke-linecap="round"/>
+  </svg>`,
+)}`;
+```
+
+Design rules for generated icons: one recognizable glyph for the domain (envelope for email, magnifier for research, calendar for scheduling), a filled rounded-square background in a single saturated color, two or three colors total, no text, no gradients, legible at 20×20. Give sibling agents in one project different background colors so they're distinguishable in the sidebar.
+
+### Session tools must exist in three places
+
+A session-ending tool is not "configured" until it appears in **all three** of these places. Missing any one produces a broken agent that still typechecks:
+
+1. **`agents/tools/<name>.ts`** — a real `defineTool` whose args schema carries the payload fields (e.g. `final_answer`, `failure_summary`). The tool body can be a simple formatter; its job is to be callable and carry structured args.
+2. **The side's prompt `tools` array** — the model can only call tools listed at the active step. A `sessionStop` binding to a tool the prompt never offers means the session *can never end on purpose*; it burns `maxSessionTurns` and fails opaquely.
+3. **The `SideConfig` binding** — `sessionStop: { name: 'complete_research', messageProperty: 'final_answer' }`. Prefer the object form: `messageProperty` (and `attachmentsProperty` when files are returned) define the canonical payload the parent receives from a subagent. A bare string binding with no mapped property returns a vague payload upstream.
+
+And a fourth, softer place: **the prompt text must tell the model when to call it** ("When the renders pass review, call `submit_video_assets` with ..."). Models do not infer termination protocol from tool names.
+
+Quick failure-mode table:
+
+| Symptom | Likely miss |
+|---|---|
+| Session always runs to `maxSessionTurns` | Session tool missing from the prompt's `tools` array, or prompt never says when to call it |
+| Runtime error: unknown tool in session binding | Binding `name` typo, or tool file never created |
+| Parent receives an empty / useless completion payload | `messageProperty` missing or doesn't match an arg field in the tool schema |
+| Child fails but parent sees a "success" with garbage | No `sessionFail` bound — the model abused `sessionStop` to bail out |
+
+### Prompt quality rubric
+
+A two-sentence system prompt is a skeleton, not a prompt. Every side's prompt should cover, roughly in this order:
+
+1. **Role and counterpart.** Who this side is *and who it is talking to*: "You are the researcher. The other participant is the user who needs the question answered." In `dual_ai`, each side must understand the other side's role or the conversation degrades into two assistants being polite to each other.
+2. **Objective and definition of done.** One sentence the model can test against: "Done means every factual claim has a source URL and the reviewer has approved."
+3. **Tool guidance.** When to use which tool — including the session tools: name them, say exactly what triggers calling them, and what belongs in each argument. For resumable subagents, distinguish `subagent_create` (new topic/instance) from `subagent_message` (follow-up to an existing instance).
+4. **Edge cases.** This is what separates a thoughtful prompt from a placeholder. Walk the domain and enumerate what realistically goes wrong, with an instruction for each. The recurring ones:
+   - *Empty or low-quality results* — retry differently, broaden, or report honestly? How many attempts before giving up?
+   - *Auth / permission / quota errors from tools* — never retry blindly; call `sessionFail` with what the operator must fix.
+   - *Ambiguous request* — ask the counterpart side, or make a stated assumption? Pick one and say so.
+   - *Partial success* — deliver the partial result with gaps called out, or fail? Define the threshold.
+   - *Out-of-scope or unsafe asks* — refuse and route where?
+   - *Conflicting instructions between turns* — which takes precedence?
+5. **Output format and quality bar.** Terse vs. comprehensive, citation requirements, structure of the final payload.
+6. **Negative space.** What the model must NOT do: don't echo secrets, don't call `complete_*` before review, don't invent IDs, don't message the parent for FYI-only info.
+
+High-leverage extra: include one **worked contrast example** inside the prompt — "this answer is insufficient, this one is sufficient, here's why" — like the incomplete-news-list example in the repo's `web_research_reviewer` prompt. One concrete contrast outperforms three paragraphs of abstract criteria.
+
+Anti-patterns: a prompt that just restates the tool list ("You have tools to search and finish"); termination instructions buried mid-paragraph; criteria written for a human reader instead of as decisions the model must make; the same prompt pasted on both sides with the labels swapped.
+
+### Subagent connection checklist
+
+When the new agent is a child in a graph, creating the agent file is half the job. Verify the full wiring:
+
+- [ ] Child is `dual_ai` with `exposeAsTool: true` and a calling-model-grade `toolDescription`
+- [ ] Child has finite `maxSessionTurns`, and `sessionStop` + `sessionFail` bound on the side(s) that own those decisions
+- [ ] The session tools pass the [three-places check](#session-tools-must-exist-in-three-places)
+- [ ] The **parent prompt's `tools` array** has the subagent entry — an agent nobody references is unreachable. Choose `blocking` / `resumable` deliberately ([the four combinations](#subprompts-vs-subagents-vs-handoffs)), and map `initUserMessageProperty` (and `initAttachmentsProperty` for files) so the child starts with real context instead of an empty first turn
+- [ ] The **parent prompt text** says when to delegate to this child and, if resumable, explains `subagent_create` vs `subagent_message`
+- [ ] Side_b reviewers use a model from a *different provider* than side_a ([why](#session-boundary-discipline))
+- [ ] Run the dev server and check the composition view: the parent→child edge should be visible, and creating a test thread should show the child spawn and the completion payload arrive back
+
+### Worked example: a complete minimal agent
+
+This is the shape every new `dual_ai` agent should have on day one — identity, icon, labels, both session tools, wired prompts. (Compressed for space; real prompts should be longer per the rubric above.)
+
+```ts
+// agents/tools/complete_audit.ts
+export default defineTool({
+  description: 'Finish the audit session and return the findings to the requester.',
+  args: z.object({
+    findings: z.string().describe('Complete audit findings, ready for the requester.'),
+    discrepancy_count: z.number().describe('Number of discrepancies found.'),
+  }).strict(),
+  execute: async (_state, args) => ({ status: 'success' as const, result: args.findings }),
+});
+
+// agents/tools/fail_audit.ts — same shape, args: { failure_summary: z.string() }
+```
+
+```ts
+// agents/agents/invoice_audit_agent.ts
+export default defineAgent({
+  name: 'invoice_audit_agent',
+  type: 'dual_ai',
+  description: 'Audits uploaded invoices against purchase orders and reports discrepancies.',
+  icon: invoiceAuditIcon, // inline SVG data URI, see Icons above
+  maxSessionTurns: 16,
+  sideA: {
+    label: 'Auditor',
+    prompt: 'invoice_audit_worker',
+    sessionFail: { name: 'fail_audit', messageProperty: 'failure_summary' },
+    maxSteps: 8,
+  },
+  sideB: {
+    label: 'Controller',
+    prompt: 'invoice_audit_reviewer',
+    sessionStop: { name: 'complete_audit', messageProperty: 'findings' },
+    sessionFail: { name: 'fail_audit', messageProperty: 'failure_summary' },
+    maxSteps: 4,
+  },
+  exposeAsTool: true,
+  toolDescription:
+    'Audit one or more invoices against purchase orders; returns findings with a discrepancy count after an internal controller review. Pass invoice file paths in attachments.',
+});
+```
+
+Both prompts list their session tools in `tools` and the reviewer prompt instructs: *"Approve by calling `complete_audit` with the full findings in `findings` only after every line item has been checked; if documents are unreadable or POs are missing after one clarification round, call `fail_audit` and name exactly what the requester must provide."* The parent prompt adds `{ name: 'invoice_audit_agent', initUserMessageProperty: 'request', initAttachmentsProperty: 'invoice_files' }` to its `tools` and explains when to delegate.
+
+---
+
 ## Model selection
 
 **Rule: never write a model string the user did not request and `current-models` did not produce.**
@@ -552,20 +689,23 @@ AgentDefinition
   sideA             SideConfig                   AI side (or first AI in dual_ai)
   sideB             SideConfig                   second AI side; required for dual_ai
   exposeAsTool      boolean (default false)      enables this agent to be called as a tool by other prompts
-  toolDescription   string                       required if exposeAsTool: true
-  description       string                       brief human description for UIs
-  icon              string                       URL or absolute path
+  toolDescription   string                       required if exposeAsTool: true — write it for the calling model
+  description       string                       brief human description for UIs — always set on new agents
+  icon              string                       URL or inline SVG data URI — always set on new agents
   env               Record<string, string>       agent-level env values
   hooks             HookId[]                     agent-scoped hooks (when prompts don't specify their own)
 ```
 
-`SideConfig` is where you bind `defaultPrompt`, `defaultModel`, and the **session lifecycle bindings**:
+`SideConfig` is where you set the side's `label` and `prompt` and bind the **session lifecycle tools**:
 
-- `sessionStop` — name of the tool whose call ends the session with a result
-- `sessionFail` — name of the tool whose call ends the session with a failure
-- `sessionStatus` — optional, a tool used to update the session status mid-run
+- `label` — the role name shown in the UI and logs ("Researcher", "Reviewer") — always set on `dual_ai` sides
+- `prompt` — the prompt this side runs (references `agents/prompts/<name>`)
+- `sessionStop` — tool whose call ends the session with a result; prefer `{ name, messageProperty }` so the payload is explicit
+- `sessionFail` — tool whose call ends the session with a failure; same object form
+- `sessionStatus` — optional, a tool used to publish status updates mid-run without ending the session
+- `maxSteps` — per-side step cap within one turn
 
-These are the bindings the [Session boundary discipline](#session-boundary-discipline) section refers to. Every `dual_ai` agent must set them.
+These are the bindings the [Session boundary discipline](#session-boundary-discipline) section refers to. Every `dual_ai` agent must set them, and every session tool must pass the [three-places check](#session-tools-must-exist-in-three-places).
 
 Packaging fields (`packageName`, `version`, `author`, `license`) exist for the agent packing system; ignore them unless you're publishing.