Agent Build Author Skill

1---
2name: agentclash-agent-build-author
3description: Use when creating, editing, validating, or readying AgentClash agent builds and build versions, including agent identity, spec JSON, prompts, model/runtime expectations, tool bindings, and version readiness.
4metadata:
5  agentclash.role: agent-builds
6  agentclash.version: "1"
7  agentclash.requires_cli: "true"
8---
9
10# AgentClash Agent Build Author
11
12## Purpose
13Create or update an AgentClash agent build and draft build version so it has a source-backed spec, a validation-clean prompt policy, and a ready build version ID that deployment setup can consume.
14
15## Use When
16- The user needs a new AgentClash agent build or a new version of an existing build.
17- A prompt, model expectation, output schema, tool binding, memory, workflow, reasoning, guardrail, or publication note should be captured in build-version JSON.
18- A deployment is blocked because the user has no ready `build_version_id`.
19- A coding agent needs to turn product behavior into an AgentClash build spec before deployment setup.
20
21## Do Not Use When
22- The CLI is not authenticated or no workspace is selected; use `agentclash-cli-setup` first.
23- Provider accounts, model aliases, runtime profiles, workspace tools, or secrets are missing; use `agentclash-runtime-resources-setup` first.
24- The build version is already ready and the user only needs a deployment; use `agentclash-agent-deployment-setup`.
25- The user is authoring challenge pack YAML; use the challenge-pack skills.
26
27## Inputs Needed
28- Workspace ID and confirmation that `agentclash doctor` can reach it.
29- Build name and optional description.
30- Whether to create a new build or add a version to an existing build ID.
31- Agent kind: `llm_agent`, `workflow_agent`, `programmatic_agent`, `multi_agent_system`, or `hosted_external`.
32- Prompt or policy instructions. Validation requires `policy_spec.instructions`.
33- Interface, reasoning, memory, workflow, guardrail, model, output schema, trace, and publication requirements.
34- Optional workspace tool IDs and knowledge source IDs to bind to the version.
35- Runtime assumptions handed off from `agentclash-runtime-resources-setup`, such as model alias, provider account, shell/network needs, and timeouts.
36
37## Environment
38Use hosted production by default:
39
40```bash
41export AGENTCLASH_API_URL="https://api.agentclash.dev"
42agentclash doctor
43```
44
45Build commands need a resolved workspace for list/create. Workspace resolution follows the normal CLI setup path, so prefer `agentclash workspace use <workspace-id>` or `AGENTCLASH_WORKSPACE` over hard-coding IDs into reusable notes.
46
47## Procedure
481. Verify CLI and workspace readiness with `agentclash doctor`.
492. Run `agentclash build list` and decide whether to create a new build or version an existing build.
503. Create the build when needed with `agentclash build create --name ... --description ...`.
514. Draft `version-spec.json` from the exact build-version fields below. Keep unknown or not-yet-used spec sections as JSON objects, not prose.
525. Create a draft build version with `agentclash build version create <BUILD_ID> --spec-file version-spec.json`.
536. Inspect the draft with `agentclash build version get <VERSION_ID> --json`.
547. Validate with `agentclash build version validate <VERSION_ID> --json` so a coding agent can inspect `valid` and `errors`. Fix any errors by editing the spec and running `agentclash build version update <VERSION_ID> --spec-file version-spec.json`.
558. Mark ready only after validation passes and the user confirms the draft is deployable: `agentclash build version ready <VERSION_ID>`.
569. Report the `agent_build_id`, `build_version_id`, `version_status`, agent kind, and deployment prerequisites.
57
58## Spec Fields
59Agent build creation accepts:
60
61```json
62{
63  "name": "Support Triage Agent",
64  "description": "Answers support benchmark cases with cited evidence."
65}
66```
67
68Build version creation and draft update accept:
69
70```json
71{
72  "agent_kind": "llm_agent",
73  "interface_spec": {
74    "input": "challenge case prompt plus attached artifacts",
75    "output": "JSON answer matching output_schema"
76  },
77  "policy_spec": {
78    "instructions": "Read the full case, inspect provided artifacts, cite evidence, and return only JSON."
79  },
80  "reasoning_spec": {
81    "strategy": "inspect evidence before answering"
82  },
83  "memory_spec": {},
84  "workflow_spec": {
85    "steps": ["read input", "inspect artifacts", "answer"]
86  },
87  "guardrail_spec": {
88    "refuse_if": ["missing required evidence"]
89  },
90  "model_spec": {
91    "preferred_model_alias": "primary-chat",
92    "temperature": 0.1
93  },
94  "output_schema": {
95    "type": "object",
96    "required": ["answer"],
97    "properties": {
98      "answer": { "type": "string" },
99      "evidence": {
100        "type": "array",
101        "items": { "type": "string" }
102      }
103    }
104  },
105  "trace_contract": {
106    "must_record": ["tool_calls", "final_answer"]
107  },
108  "publication_spec": {
109    "version_notes": "Initial support triage build."
110  },
111  "tools": [
112    {
113      "tool_id": "<WORKSPACE_TOOL_UUID>",
114      "binding_role": "evidence_lookup",
115      "binding_config": {}
116    }
117  ],
118  "knowledge_sources": [
119    {
120      "knowledge_source_id": "<KNOWLEDGE_SOURCE_UUID>",
121      "binding_role": "reference",
122      "binding_config": {}
123    }
124  ]
125}
126```
127
128Required readiness invariant: `policy_spec` must contain an `instructions` field. The current validation also checks that `agent_kind` is one of the supported enum values. Omitted JSON spec objects default to `{}`; omitted tool and knowledge-source bindings default to empty lists.
129
130## Commands
131Verify setup and inspect existing builds:
132
133```bash
134export AGENTCLASH_API_URL="https://api.agentclash.dev"
135agentclash doctor
136agentclash build list
137agentclash build get <BUILD_ID>
138```
139
140Create a build:
141
142```bash
143agentclash build create \
144  --name "Support Triage Agent" \
145  --description "Answers support benchmark cases with cited evidence."
146```
147
148Create, inspect, validate, update, and ready a build version:
149
150```bash
151agentclash build version create <BUILD_ID> --spec-file version-spec.json
152agentclash build version get <VERSION_ID> --json
153agentclash build version validate <VERSION_ID> --json
154agentclash build version update <VERSION_ID> --spec-file version-spec.json
155agentclash build version ready <VERSION_ID>
156```
157
158When only the agent kind needs to be set or overridden at creation time:
159
160```bash
161agentclash build version create <BUILD_ID> --agent-kind llm_agent --spec-file version-spec.json
162```
163
164## Expected Output
165- `build list` returns workspace build IDs, names, slugs, lifecycle status, and creation timestamps.
166- `build get <BUILD_ID>` returns build metadata plus version history.
167- `build create` returns a build ID and generated slug.
168- `build version create` returns a draft version ID and version number.
169- `build version get --json` returns `version_status`, `agent_kind`, all spec objects, tool bindings, knowledge-source bindings, and creation time.
170- `build version validate --json` returns `valid: true` when the agent kind is supported and `policy_spec.instructions` exists. Without `--json`, the CLI prints `Version is valid` or `Version has validation errors`.
171- `build version ready` changes `version_status` to `ready`; ready versions are the deployable handoff to deployment setup.
172
173## Failure Modes
174- `no workspace specified`: run `agentclash link`, pass `--workspace`, set `AGENTCLASH_WORKSPACE`, or add project config with `agentclash init`.
175- `name is required`: build creation needs `--name`.
176- `request body must be valid JSON`: `--spec-file` must point to valid JSON, not YAML or Markdown.
177- Validation fails on `agent_kind`: use one of `llm_agent`, `workflow_agent`, `programmatic_agent`, `multi_agent_system`, or `hosted_external`.
178- Validation fails on `policy_spec`: add `policy_spec.instructions` to the version spec.
179- Update fails because the version is not draft: ready versions are immutable for normal authoring; create a new build version instead.
180- Tool or knowledge-source binding fails validation: IDs must be UUIDs. Workspace tool creation belongs in `agentclash-runtime-resources-setup`.
181- Deployment later fails because the version is not ready: run validate, fix errors, then explicitly mark ready.
182
183## Safety Notes
184- Do not put provider API keys, tokens, or customer secrets in any build spec field. Use runtime resources and workspace secrets instead.
185- Treat `build version ready` as a publish-style action because it makes the version immutable and deployable; get explicit user confirmation first.
186- Keep model names and provider-account assumptions in `model_spec` as expectations or notes unless deployment setup has real runtime resource IDs.
187- Prefer `build version get --json` before update or ready so the agent does not overwrite a draft blindly.
188- Do not invent workspace tool or knowledge-source IDs. List or create the upstream resources first.
189
190## Report Back Format
191```text
192Workspace: <workspace-id>
193Build: <name> (<agent_build_id>)
194Version: v<version_number> (<build_version_id>)
195Status: <draft | ready>
196Agent kind: <agent_kind>
197Validation: <valid | errors>
198Runtime assumptions: <provider/model/runtime/tool notes>
199Next skill: agentclash-runtime-resources-setup | agentclash-agent-deployment-setup
200Notes: <version notes, immutable-ready caveats, or blockers>
201```
202
203## Related Skills
204- `agentclash-cli-setup`
205- `agentclash-runtime-resources-setup`
206- `agentclash-agent-deployment-setup`
207
208## Related Docs
209- `/docs-md/concepts/agents-and-deployments`
210- `/docs-md/guides/configure-runtime-resources`
211- `/docs-md/reference/cli`
212- `/docs-md/reference/config`