Runtime Resources Setup Skill

1---
2name: agentclash-runtime-resources-setup
3description: Use when configuring AgentClash workspace secrets, provider accounts, provider models, 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, provider model IDs, runtime profiles, optional workspace tools, and readiness checks.
14
15## Use When
16- A deployment cannot run because provider accounts, provider model IDs, 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, provider model, provider account, or runtime profile that is unavailable 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 provider model ID, or enough criteria to select one from the account's live model list.
31- Runtime profile requirements: execution target, trace mode, iteration/tool limits, timeouts, and sandbox/network policy.
32- Optional workspace tool names, tool kinds, and JSON specs.
33- Whether the user wants to create resources now or only audit readiness.
34
35## Environment
36Use hosted production by default:
37
38```bash
39export AGENTCLASH_API_URL="https://api.agentclash.dev"
40```
41
42Commands that create or list workspace resources also need a resolved workspace:
43
44```bash
45agentclash doctor
46agentclash secret list
47```
48
49If workspace resolution fails, run the CLI setup skill first and do not create resources yet.
50
51## Resource Order
521. Verify CLI auth and workspace context.
532. Store provider credentials as workspace secrets.
543. Create a provider account that references a workspace secret.
554. List models available through that provider account and choose a provider model ID.
565. Create a runtime profile with execution and sandbox limits.
576. Create optional workspace tools if deployments or packs expect reusable workspace tools.
587. List resources and record IDs and the provider model ID for agent build/deployment setup.
59
60## Procedure
611. Run `agentclash doctor` and stop on auth or workspace warnings.
622. 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.
633. Create or select the provider account. Prefer `credential_reference: "workspace-secret://KEY"` over putting raw keys in JSON files.
644. Run `agentclash infra provider-account models <PROVIDER_ACCOUNT_ID>` and choose the exact provider model ID needed by the deployment. The list is live when the provider supports discovery and may include static pricing metadata.
655. Create or select a runtime profile. Keep limits explicit: iterations, tool calls, step timeout, run timeout, and sandbox/network policy.
666. Create workspace tools only when the deployment or product workflow needs reusable workspace tool resources. Keep these separate from pack-defined composed tools.
677. Re-list all resources and report the IDs and provider model ID downstream skills need.
68
69## Commands
70Verify setup and workspace:
71
72```bash
73export AGENTCLASH_API_URL="https://api.agentclash.dev"
74agentclash doctor
75```
76
77Store provider credentials as workspace secrets:
78
79```bash
80printf '%s' "$OPENAI_API_KEY" | agentclash secret set OPENAI_API_KEY
81agentclash secret list
82```
83
84Create a provider account from a JSON file:
85
86```json
87{
88  "provider_key": "openai",
89  "name": "OpenAI Workspace Account",
90  "credential_reference": "workspace-secret://OPENAI_API_KEY",
91  "limits_config": {
92    "rpm": 60
93  }
94}
95```
96
97```bash
98agentclash infra provider-account create --from-file provider-account.json
99agentclash infra provider-account list
100agentclash infra provider-account get <PROVIDER_ACCOUNT_ID>
101```
102
103List the models reachable through that account:
104
105```bash
106agentclash infra provider-account models <PROVIDER_ACCOUNT_ID>
107```
108
109Create a runtime profile:
110
111```json
112{
113  "name": "default-native",
114  "execution_target": "native",
115  "trace_mode": "full",
116  "max_iterations": 24,
117  "max_tool_calls": 32,
118  "step_timeout_seconds": 120,
119  "run_timeout_seconds": 1800,
120  "profile_config": {
121    "sandbox": {
122      "allow_shell": true,
123      "allow_network": false
124    }
125  }
126}
127```
128
129```bash
130agentclash infra runtime-profile create --from-file runtime-profile.json
131agentclash infra runtime-profile list
132agentclash infra runtime-profile get <RUNTIME_PROFILE_ID>
133```
134
135Optional workspace tools:
136
137`tool.json`:
138
139```json
140{
141  "name": "inventory-api",
142  "tool_kind": "http",
143  "capability_key": "inventory.lookup",
144  "definition": {}
145}
146```
147
148```bash
149agentclash infra tool list
150agentclash infra tool create --from-file tool.json
151agentclash infra tool get <TOOL_ID>
152```
153
154Archive or delete only with explicit user confirmation:
155
156```bash
157agentclash infra runtime-profile archive <RUNTIME_PROFILE_ID>
158agentclash infra provider-account delete <PROVIDER_ACCOUNT_ID>
159agentclash secret delete <SECRET_KEY>
160```
161
162## Expected Output
163- `secret list` shows secret keys and timestamps, never secret values.
164- `provider-account list` shows provider key, account name, status, and ID.
165- `provider-account models` returns provider model IDs, display names, and pricing metadata when available.
166- `runtime-profile list` shows execution target, max iterations, and ID.
167- `infra tool list` shows workspace tool name, kind, lifecycle status, and ID.
168- The final handoff contains the provider account ID, provider model ID, runtime profile ID, relevant secret key names, and optional tool IDs.
169
170## Failure Modes
171- `no workspace specified`: run `agentclash link`, pass `--workspace`, set `AGENTCLASH_WORKSPACE`, or add project config with `agentclash init`.
172- Provider account creation fails because the secret is missing: run `agentclash secret list`, then set the expected key and use `workspace-secret://KEY`.
173- 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`.
174- Model listing fails: run `agentclash infra provider-account test <PROVIDER_ACCOUNT_ID> --model <MODEL_ID>` to distinguish credential/connectivity failures, and verify the provider account is active.
175- Deployment setup later fails because no runtime profile exists: create or select a runtime profile and pass its ID into deployment setup.
176- 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`.
177- Workspace tools are confused with pack-defined tools: workspace tools are `agentclash infra tool ...` resources; pack-defined tools live inside challenge pack YAML.
178
179## Safety Notes
180- 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.
181- Prefer `credential_reference: "workspace-secret://KEY"` in provider account specs.
182- Treat `delete` and `archive` commands as destructive enough to require explicit user confirmation.
183- Use `list` and `get` before `create`, `delete`, or `archive` to avoid duplicating or mutating the wrong workspace resource.
184- Keep local/self-hosted API URLs explicit; hosted examples should use `https://api.agentclash.dev`.
185
186## Report Back Format
187```text
188Workspace: <workspace-id>
189Secrets: <KEY present | KEY missing>
190Provider account: <id or action needed>
191Provider model: <provider model ID>
192Runtime profile: <id or action needed>
193Workspace tools: <ids or none>
194Readiness: <ready for deployment setup | blocked>
195Next skill: agentclash-agent-build-author | agentclash-agent-deployment-setup
196Notes: <credential, limit, sandbox, or tool caveats>
197```
198
199## Related Skills
200- `agentclash-cli-setup`
201- `agentclash-agent-build-author`
202- `agentclash-agent-deployment-setup`
203- `agentclash-challenge-pack-tools-sandbox`
204
205## Related Docs
206- `/docs-md/guides/configure-runtime-resources`
207- `/docs-md/concepts/agents-and-deployments`
208- `/docs-md/concepts/tools-network-and-secrets`
209- `/docs-md/reference/cli`
210- `/docs-md/reference/config`