Runtime Resources Setup Skill

1---
2name: agentclash-runtime-resources-setup
3description: Use when configuring AgentClash workspace secrets, provider accounts, model catalog entries, model aliases, runtime profiles, workspace tools, and readiness checks required before agent builds, deployments, evals, or runs.
4metadata:
5  agentclash.role: runtime-resources
6  agentclash.version: "1"
7  agentclash.requires_cli: "true"
8---
9
10# AgentClash Runtime Resources Setup
11
12## Purpose
13Prepare the workspace infrastructure chain that lets AgentClash turn a ready agent build version into a runnable deployment: secrets, provider accounts, model aliases, runtime profiles, optional workspace tools, and readiness checks.
14
15## Use When
16- A deployment cannot run because provider accounts, model aliases, workspace secrets, runtime profiles, or workspace tools are missing.
17- A user has a ready agent build/version but does not yet have the runtime resources needed to deploy it.
18- A challenge pack or deployment references a secret, tool, model alias, provider account, or runtime profile that does not exist in the selected workspace.
19- A coding agent needs a checklist before moving from CLI setup to agent build/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- The user is authoring challenge pack YAML fields; use challenge-pack skills after workspace resources are clear.
24- The user is creating the agent build itself; use `agentclash-agent-build-author`.
25- The user already has resource IDs and only needs to create/select a deployment; use `agentclash-agent-deployment-setup`.
26
27## Inputs Needed
28- Workspace ID and confirmation that `agentclash doctor` can reach it.
29- Provider key, such as `openai`, and the credential secret key name.
30- Desired model catalog entry ID or enough criteria to pick one from the model catalog.
31- Runtime profile requirements: execution target, trace mode, iteration/tool limits, timeouts, and sandbox/network policy.
32- Model alias key/display name and, when needed, the provider account it should bind to.
33- Optional workspace tool names, tool kinds, and JSON specs.
34- Whether the user wants to create resources now or only audit readiness.
35
36## Environment
37Use hosted production by default:
38
39```bash
40export AGENTCLASH_API_URL="https://api.agentclash.dev"
41```
42
43Commands that create or list workspace resources also need a resolved workspace:
44
45```bash
46agentclash doctor
47agentclash secret list
48```
49
50If workspace resolution fails, run the CLI setup skill first and do not create resources yet.
51
52## Resource Order
531. Verify CLI auth and workspace context.
542. Store provider credentials as workspace secrets.
553. Inspect the global model catalog and choose a model catalog entry.
564. Create a provider account that references a workspace secret.
575. Create a runtime profile with execution and sandbox limits.
586. Create a model alias that points at a catalog entry and optionally binds to a provider account.
597. Create optional workspace tools if deployments or packs expect reusable workspace tools.
608. List resources and record IDs for agent build/deployment setup.
61
62## Procedure
631. Run `agentclash doctor` and stop on auth or workspace warnings.
642. Run `agentclash secret list` to see which secret keys already exist. If a secret value is not already available in the user's shell, ask the user to set it themselves with `agentclash secret set <KEY>`; do not request or receive the value in chat.
653. Run `agentclash infra model-catalog list` and `get` the candidate model entry before creating aliases.
664. Create or select the provider account. Prefer `credential_reference: "workspace-secret://KEY"` over putting raw keys in JSON files.
675. Create or select a runtime profile. Keep limits explicit: iterations, tool calls, step timeout, run timeout, and sandbox/network policy.
686. Create or select a model alias that points to the model catalog entry and, when needed, the provider account.
697. Create workspace tools only when the deployment or product workflow needs reusable workspace tool resources. Keep these separate from pack-defined composed tools.
708. Re-list all resources and report the IDs downstream skills need.
71
72## Commands
73Verify setup and workspace:
74
75```bash
76export AGENTCLASH_API_URL="https://api.agentclash.dev"
77agentclash doctor
78```
79
80Store provider credentials as workspace secrets:
81
82```bash
83printf '%s' "$OPENAI_API_KEY" | agentclash secret set OPENAI_API_KEY
84agentclash secret list
85```
86
87Inspect the global model catalog:
88
89```bash
90agentclash infra model-catalog list
91agentclash infra model-catalog get <MODEL_CATALOG_ENTRY_ID>
92```
93
94Create a provider account from a JSON file:
95
96```json
97{
98  "provider_key": "openai",
99  "name": "OpenAI Workspace Account",
100  "credential_reference": "workspace-secret://OPENAI_API_KEY",
101  "limits_config": {
102    "rpm": 60
103  }
104}
105```
106
107```bash
108agentclash infra provider-account create --from-file provider-account.json
109agentclash infra provider-account list
110agentclash infra provider-account get <PROVIDER_ACCOUNT_ID>
111```
112
113Create a runtime profile:
114
115```json
116{
117  "name": "default-native",
118  "execution_target": "native",
119  "trace_mode": "full",
120  "max_iterations": 24,
121  "max_tool_calls": 32,
122  "step_timeout_seconds": 120,
123  "run_timeout_seconds": 1800,
124  "profile_config": {
125    "sandbox": {
126      "allow_shell": true,
127      "allow_network": false
128    }
129  }
130}
131```
132
133```bash
134agentclash infra runtime-profile create --from-file runtime-profile.json
135agentclash infra runtime-profile list
136agentclash infra runtime-profile get <RUNTIME_PROFILE_ID>
137```
138
139Create a model alias:
140
141```json
142{
143  "alias_key": "primary-chat",
144  "display_name": "Primary Chat Model",
145  "model_catalog_entry_id": "<MODEL_CATALOG_ENTRY_ID>",
146  "provider_account_id": "<PROVIDER_ACCOUNT_ID>"
147}
148```
149
150```bash
151agentclash infra model-alias create --from-file model-alias.json
152agentclash infra model-alias list
153agentclash infra model-alias get <MODEL_ALIAS_ID>
154```
155
156Optional workspace tools:
157
158`tool.json`:
159
160```json
161{
162  "name": "inventory-api",
163  "tool_kind": "http",
164  "capability_key": "inventory.lookup",
165  "definition": {}
166}
167```
168
169```bash
170agentclash infra tool list
171agentclash infra tool create --from-file tool.json
172agentclash infra tool get <TOOL_ID>
173```
174
175Archive or delete only with explicit user confirmation:
176
177```bash
178agentclash infra runtime-profile archive <RUNTIME_PROFILE_ID>
179agentclash infra model-alias delete <MODEL_ALIAS_ID>
180agentclash infra provider-account delete <PROVIDER_ACCOUNT_ID>
181agentclash secret delete <SECRET_KEY>
182```
183
184## Expected Output
185- `secret list` shows secret keys and timestamps, never secret values.
186- `model-catalog list` returns global model entries with provider, model, family, and lifecycle status.
187- `provider-account list` shows provider key, account name, status, and ID.
188- `runtime-profile list` shows execution target, max iterations, and ID.
189- `model-alias list` shows alias key, display name, status, and ID.
190- `infra tool list` shows workspace tool name, kind, lifecycle status, and ID.
191- The final handoff contains the provider account ID, runtime profile ID, model alias ID, relevant secret key names, and optional tool IDs.
192
193## Failure Modes
194- `no workspace specified`: run `agentclash link`, pass `--workspace`, set `AGENTCLASH_WORKSPACE`, or add project config with `agentclash init`.
195- Provider account creation fails because the secret is missing: run `agentclash secret list`, then set the expected key and use `workspace-secret://KEY`.
196- A raw `api_key` was passed and cannot be read back: expected behavior; the infrastructure manager stores it as a workspace secret named `PROVIDER_<PROVIDER_KEY>_API_KEY` and keeps only `workspace-secret://PROVIDER_<PROVIDER_KEY>_API_KEY` on the provider account. The provider key is uppercased and hyphens become underscores, so `x-ai` becomes `PROVIDER_X_AI_API_KEY`.
197- Model alias creation fails because the model catalog entry is wrong or unavailable: inspect with `agentclash infra model-catalog get <MODEL_CATALOG_ENTRY_ID>` and choose an active entry for the intended provider.
198- Deployment setup later fails because no runtime profile exists: create or select a runtime profile and pass its ID into deployment setup.
199- Runs fail because network, shell, timeout, or tool-call limits are too strict: review `profile_config`, `max_iterations`, `max_tool_calls`, `step_timeout_seconds`, and `run_timeout_seconds`.
200- Workspace tools are confused with pack-defined tools: workspace tools are `agentclash infra tool ...` resources; pack-defined tools live inside challenge pack YAML.
201
202## Safety Notes
203- Never print, paste, request, receive, or commit raw provider keys. Prefer stdin for `secret set`; if the value is not already in the user's shell, ask the user to run the command themselves.
204- Prefer `credential_reference: "workspace-secret://KEY"` in provider account specs.
205- Treat `delete` and `archive` commands as destructive enough to require explicit user confirmation.
206- Use `list` and `get` before `create`, `delete`, or `archive` to avoid duplicating or mutating the wrong workspace resource.
207- Keep local/self-hosted API URLs explicit; hosted examples should use `https://api.agentclash.dev`.
208
209## Report Back Format
210```text
211Workspace: <workspace-id>
212Secrets: <KEY present | KEY missing>
213Provider account: <id or action needed>
214Model catalog entry: <id and provider/model>
215Runtime profile: <id or action needed>
216Model alias: <id or action needed>
217Workspace tools: <ids or none>
218Readiness: <ready for deployment setup | blocked>
219Next skill: agentclash-agent-build-author | agentclash-agent-deployment-setup
220Notes: <credential, limit, sandbox, or tool caveats>
221```
222
223## Related Skills
224- `agentclash-cli-setup`
225- `agentclash-agent-build-author`
226- `agentclash-agent-deployment-setup`
227- `agentclash-challenge-pack-tools-sandbox`
228
229## Related Docs
230- `/docs-md/guides/configure-runtime-resources`
231- `/docs-md/concepts/agents-and-deployments`
232- `/docs-md/concepts/tools-network-and-secrets`
233- `/docs-md/reference/cli`
234- `/docs-md/reference/config`