agentclash-challenge-pack-tools-sandbox

Files (1)

• SKILL.md

SKILL.md (first lines)

# AgentClash Challenge Pack Tools And Sandbox

## Purpose
Define the native execution surface a challenge pack needs: pack-defined custom tools, broad tool policy, sandbox network/package/env settings, and safe secret references.

Use this skill only when a pack truly needs native files, tools, network, packages, or sandbox behavior. Keep the runtime surface narrow enough that failures are attributable to the agent, not to an over-broad environment.

## Use When
- A challenge pack needs top-level `tools.custom`.
- The pack needs `version.tool_policy.allowed_tool_kinds`.
- The pack needs `version.sandbox` for network access, CIDR allowlists, environment variables, apt packages, or a sandbox template.
- A coding agent needs exact source-backed YAML shapes without reading the AgentClash source repo.
- A reviewer needs to check that no raw secrets or unsupported tool kinds are being introduced.

## Do Not Use When
- The pack is `prompt_eval` and only needs prompt/final-output evaluation.
- The task is workspace infrastructure setup with `agentclash infra tool ...`; use `agentclash-runtime-resources-setup`.
- The task is artifact declaration, scoring validators, LLM judges, validation/publish, or eval running; use the focused downstream skills.

## Environment
Use hosted production for CLI examples unless the user intentionally targets a local or self-hosted backend.

```bash
export AGENTCLASH_API_URL="https://api.agentclash.dev"
```

## Validation Commands
Validate after adding or changing tools, tool policy, or sandbox settings.

```bash
agentclash challenge-pack validate path/to/pack.yaml
agentclash challenge-pack validate path/to/pack.yaml --json
```

Human output prints `Challenge pack is valid` or `Challenge pack has errors`. Use `--json` for structured `valid` and `errors` fields.

## Execution Mode Rules
`prompt_eval` packs cannot use challenge-pack tools or sandbox settings.

Do not include these in `prompt_eval`:
- top-level `tools`
- `version.tool_policy`
- `version.sandbox`

Use `native` when the task needs files, tool calls, network policy, extra packages, sandbox templates, file validators, directory checks, or code execution.

```yaml
version:
  number: 1
  execution_mode: native
```

## Tool Policy
`version.tool_policy.allowed_tool_kinds` accepts only these broad kinds:

```yaml
version:
  tool_policy:
    allowed_tool_kinds:
      - browser
      - build
      - data
      - file
      - network
```

Supported values are exactly `browser`, `build`, `data`, `file`, and `network`. Do not use `shell`; the current validator rejects it.

Use the narrowest set possible:
- `file` for reading/writing workspace files.
- `build` for build/test style operations.
- `network` for outbound HTTP or API access.
- `browser` for browser interaction.
- `data` for structured data access tools.

## Pack-Defined Custom Tools
Challenge-pack custom tools live at top-level `tools.custom`, not under `version`.

```yaml
tools:
  custom:
    - name: check_inventory
      description: Check inventory for a SKU.
      parameters:
        type: object
        properties:
          sku:
            type: string
        required:
          - sku
      implementation:
        primitive: http_request
        args:
          method: GET
          url: "https://api.example.com/inventory/${sku}"
          headers:
            Authorization: "Bearer ${secrets.INVENTORY_API_KEY}"
```

Source-backed fields:
- `tools.custom[]` entries are the supported pack-defined tool shape.
- `name` should be stable and unique in the pack.
- `parameters` must be valid JSON Schema when provided. If omitted, validation defaults to an empty object schema, but authoring explicit parameters is clearer.
- `implementation` is required.
- Non-`mock` implementations require `implementation.primitive`.
- Non-`mock` implementations require `implementation.args`, and `args` must be a JSON/YAML object.
- `implementation.primitive` cannot equal the tool's own `name`.
- Tool delegation cycles are rejected, and delegation depth greater than 8 is rejected.

Mock tools are the only exception to primitive/args validation:

```yaml
tools:
  custom:
    - name: fake_lookup
      parameters:
        type: object
      implementation:
        type: mock

From agentclash/agentclash, MIT.

More from agentclash/agentclash