# Agent Skills

Copyable AgentClash skills for coding agents, exposed as docs pages and markdown exports.

Source: https://www.agentclash.dev/docs/agent-skills
Markdown export: https://www.agentclash.dev/md/docs/agent-skills

AgentClash ships portable Agent Skills for coding agents that understand the `SKILL.md` folder format. The canonical source lives in `web/content/agent-skills/.../SKILL.md`; docs pages and markdown exports are generated from that source.

## Install Targets

- Codex: copy a skill folder into `.agents/skills/<skill>/SKILL.md` or point Codex at the markdown export.
- Claude Code: copy a skill folder into `.claude/skills/<skill>/SKILL.md`; if the repo already uses `AGENTS.md`, add a `CLAUDE.md` import for `@AGENTS.md`.
- Cursor: use these pages as agent-requested rule references, or add thin `.cursor/rules/*.mdc` stubs that link to the matching markdown export.
- Generic agents: fetch `/llms.txt`, `/llms-full.txt`, or the individual `/docs-md/agent-skills/<skill>` pages.

## Core Operating Skills

- [agentclash-agent-harness-setup](https://www.agentclash.dev/md/docs/agent-skills/agentclash-agent-harness-setup) - harness: Use when creating, running, or ranking Agent Harness coding-agent tasks via the CLI, including harness specs, E2B runner kinds, suite task banks, executions, failure review, and promote-to-task flows.
- [agentclash-ci-release-gate](https://www.agentclash.dev/md/docs/agent-skills/agentclash-ci-release-gate) - ci: Use when wiring AgentClash manifest-based CI gates, deciding whether a PR should run AgentClash, resolving baselines, running `agentclash ci run`, interpreting gate exit codes, collecting CI artifacts, or configuring regression promotion policy in GitHub Actions.
- [agentclash-cli-setup](https://www.agentclash.dev/md/docs/agent-skills/agentclash-cli-setup) - setup: Use when configuring the AgentClash CLI, authenticating with device login or tokens, selecting a workspace, saving default config with link, creating project config with init, resolving API URL precedence, or diagnosing CLI access against production, local, or self-hosted backends.
- [agentclash-compare-and-triage](https://www.agentclash.dev/md/docs/agent-skills/agentclash-compare-and-triage) - comparison: Use when comparing baseline vs candidate AgentClash runs, evaluating release gates, managing workspace baseline bookmarks, or building a replay triage envelope after an eval completes.
- [agentclash-dataset-workflows](https://www.agentclash.dev/md/docs/agent-skills/agentclash-dataset-workflows) - dataset: Use when managing AgentClash datasets via CLI — create versions, import/export examples, run evals, CI gates, synthetic generation, trace import, candidate review, and regression suite sync.
- [agentclash-eval-runner](https://www.agentclash.dev/md/docs/agent-skills/agentclash-eval-runner) - running: Use when starting, following, inspecting, or reporting AgentClash eval runs with the CLI, especially eval start, run create, deployment selection, input set selection, suite-only scopes, repetitions, events, rankings, failures, and scorecards.
- [agentclash-hub](https://www.agentclash.dev/md/docs/agent-skills/agentclash-hub) - hub: Use when starting any AgentClash eval, CLI, or challenge-pack task. Load this skill first for the full workflow map, skill dependency order, product UI links, hosted defaults, and pointers to every other AgentClash skill.
- [agentclash-multi-turn-operator](https://www.agentclash.dev/md/docs/agent-skills/agentclash-multi-turn-operator) - multi-turn: Use when a multi_turn challenge pack run agent is awaiting human input and you need to check turn status or submit an operator message with agentclash run turn.
- [agentclash-prompt-eval-playground](https://www.agentclash.dev/md/docs/agent-skills/agentclash-prompt-eval-playground) - prompt-eval: Use when scaffolding, validating, or running prompt eval YAML configs and managing playground experiments, test cases, and prompt variants via the AgentClash CLI.
- [agentclash-quickstart](https://www.agentclash.dev/md/docs/agent-skills/agentclash-quickstart) - onboarding: Use when checking whether a workspace is ready to run AgentClash evals, interpreting quickstart readiness checks, or choosing the next CLI command after auth and workspace selection.
- [agentclash-regression-flywheel](https://www.agentclash.dev/md/docs/agent-skills/agentclash-regression-flywheel) - regression: Use when inspecting AgentClash run failure-review items, promoting useful failures into regression suites, editing regression suites or cases, and verifying suite-only reruns.
- [agentclash-scorecard-reader](https://www.agentclash.dev/md/docs/agent-skills/agentclash-scorecard-reader) - reviewing: Use when interpreting AgentClash rankings, scorecards, replay timelines, artifacts, LLM judge results, or failure-review evidence into source-backed findings and next actions.
- [agentclash-security-evaluation](https://www.agentclash.dev/md/docs/agent-skills/agentclash-security-evaluation) - security: Use when running client-side security stress harnesses against security challenge packs, measuring leak posture, Agent Vault routing, or HashiCorp Vault runtime leaks with agentclash security commands.
- [agentclash-workspace-admin](https://www.agentclash.dev/md/docs/agent-skills/agentclash-workspace-admin) - admin: Use when creating or administering AgentClash organizations and workspaces, inviting members, updating roles, or binding default workspace context beyond basic CLI login.

## Challenge Pack Skills

Focused skills for planning, authoring, scoring, judging, tooling, artifacts, validation, and publishing challenge packs.

- [agentclash-challenge-pack-artifacts](https://www.agentclash.dev/md/docs/agent-skills/challenge-pack-skills/agentclash-challenge-pack-artifacts) - challenge-pack-artifacts: Use when specifying AgentClash challenge pack assets, artifact references, produced file captures, evidence references, artifact upload/download expectations, and review-only evidence.
- [agentclash-challenge-pack-input-sets](https://www.agentclash.dev/md/docs/agent-skills/challenge-pack-skills/agentclash-challenge-pack-input-sets) - challenge-pack-inputs: Use when designing AgentClash challenge pack cases and input sets for smoke, full benchmark, regression, edge-case, or CI suite-only coverage.
- [agentclash-challenge-pack-llm-judges](https://www.agentclash.dev/md/docs/agent-skills/challenge-pack-skills/agentclash-challenge-pack-llm-judges) - challenge-pack-judging: Use when configuring AgentClash LLM-as-judge scoring, judge prompts, rubrics, assertion/reference/n-wise modes, evidence inputs, scorecard dimensions, abstention behavior, and judge result interpretation.
- [agentclash-challenge-pack-planner](https://www.agentclash.dev/md/docs/agent-skills/challenge-pack-skills/agentclash-challenge-pack-planner) - challenge-pack-planning: Use when turning a vague AgentClash evaluation idea into a source-backed challenge pack plan with task boundaries, target agents, cases, input sets, scoring strategy, tools, artifacts, runtime policy, validation criteria, and handoff steps.
- [agentclash-challenge-pack-scoring-validators](https://www.agentclash.dev/md/docs/agent-skills/challenge-pack-skills/agentclash-challenge-pack-scoring-validators) - challenge-pack-scoring: Use when defining deterministic AgentClash scoring validators, scorecard dimensions, evidence sources, pass/fail rules, numeric metrics, file checks, and validator result interpretation.
- [agentclash-challenge-pack-tools-sandbox](https://www.agentclash.dev/md/docs/agent-skills/challenge-pack-skills/agentclash-challenge-pack-tools-sandbox) - challenge-pack-tools: Use when defining AgentClash challenge pack tool access, sandbox runtime needs, filesystem expectations, network policy, command execution, and secret references.
- [agentclash-challenge-pack-validation-publish](https://www.agentclash.dev/md/docs/agent-skills/challenge-pack-skills/agentclash-challenge-pack-validation-publish) - challenge-pack-publication: Use when validating AgentClash challenge pack YAML, fixing schema/scoring/tool/asset errors, publishing runnable pack versions, recording returned IDs, and preparing next eval commands.
- [agentclash-challenge-pack-yaml-author](https://www.agentclash.dev/md/docs/agent-skills/challenge-pack-skills/agentclash-challenge-pack-yaml-author) - challenge-pack-authoring: Use when writing or editing AgentClash challenge pack YAML, including pack/version metadata, execution mode, challenges, cases, input sets, scoring blocks, tools, sandbox settings, assets, and validation handoff.

## Agent Build Skills

Focused skills for agent build specs, deployments, runtime resources, provider accounts, model aliases, and secrets.

- [agentclash-agent-build-author](https://www.agentclash.dev/md/docs/agent-skills/agent-build-skills/agentclash-agent-build-author) - agent-builds: 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.
- [agentclash-agent-deployment-setup](https://www.agentclash.dev/md/docs/agent-skills/agent-build-skills/agentclash-agent-deployment-setup) - agent-deployments: Use when creating, selecting, or diagnosing AgentClash agent deployments for runs, including ready build versions, runtime profiles, provider/model wiring, deployment IDs, workspace context, and run compatibility.
- [agentclash-runtime-resources-setup](https://www.agentclash.dev/md/docs/agent-skills/agent-build-skills/agentclash-runtime-resources-setup) - runtime-resources: 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.

## Canonical Layout

```text
web/content/agent-skills/<category-or-skill>/.../SKILL.md
```

Each skill keeps the main instructions focused and uses trigger-oriented frontmatter so agents can discover the right workflow before loading the full body.

## Catalog Contract

The root catalog skill is the authoring and review contract for all AgentClash skills.

````markdown
---
name: agentclash-skill-catalog
description: Use when creating, reviewing, or updating AgentClash agent-skill folders so the catalog taxonomy, frontmatter, generated docs, markdown exports, and llms.txt surfaces stay consistent.
metadata:
  agentclash.role: catalog
  agentclash.version: "1"
  agentclash.requires_cli: "false"
---

# AgentClash Skill Catalog

## Purpose
Define the folder taxonomy and publishing contract for AgentClash Agent Skills. Use this skill before adding or changing any `web/content/agent-skills/**/SKILL.md` file.

## Use When
- A user asks to add a new AgentClash skill.
- A user asks to update the skill catalog, taxonomy, metadata, generated docs, markdown exports, or `llms.txt` coverage.
- A reviewer needs to check whether a skill can be copied into Codex, Claude Code, Cursor, or another coding-agent workflow.

## Do Not Use When
- The task is only to run an eval, read a scorecard, configure the CLI, or author a challenge pack.
- The task changes product docs outside the Agent Skills catalog and does not affect skill discovery.

## Inputs Needed
- Feature area and intended user workflow.
- The upstream skill dependencies that must be read first.
- Source-backed command names, field names, examples, and failure modes.
- Whether the workflow targets hosted production, local development, or a self-hosted backend.

## Canonical Folder Taxonomy
The canonical source is always a `SKILL.md` file under `web/content/agent-skills`.

```text
web/content/agent-skills/SKILL.md
web/content/agent-skills/<top-level-skill>/SKILL.md
web/content/agent-skills/agent-build-skills/<skill>/SKILL.md
web/content/agent-skills/challenge-pack-skills/<skill>/SKILL.md
```

Use top-level folders for cross-cutting workflows such as CLI setup, eval running, scorecard reading, regression, and CI gates. Use `agent-build-skills/` for agent build specs, runtime resources, deployments, providers, secrets, and model aliases. Use `challenge-pack-skills/` for challenge pack planning, YAML authoring, inputs, tools, artifacts, scoring, judges, validation, and publish workflows.

## Required Frontmatter
Every skill must start with YAML frontmatter that the docs generator can parse with `gray-matter`.

```yaml
---
name: agentclash-example-skill
description: Use when the trigger is specific enough that an agent can choose this skill before reading the body.
metadata:
  agentclash.role: example
  agentclash.version: "1"
  agentclash.requires_cli: "true"
---
```

Field rules:
- `name`: stable kebab-case skill identifier, usually matching the folder name.
- `description`: trigger-oriented sentence that starts with "Use when" and names the workflow, not a generic summary.
- `metadata.agentclash.role`: short role label shown in the catalog list.
- `metadata.agentclash.version`: string version for the skill contract.
- `metadata.agentclash.requires_cli`: string `"true"` or `"false"` so installers and reviewers can spot CLI-dependent skills.

## Required Body Sections
Each skill should be useful without reading the AgentClash source code. Include these sections unless the section is not applicable and explicitly say why.

- `Purpose`: one paragraph describing the workflow outcome.
- `Use When`: concrete triggers that should load the skill.
- `Do Not Use When`: nearby workflows that should choose a different skill.
- `Inputs Needed`: information the agent should collect before acting.
- `Environment`: backend defaults, credentials, workspace, and local/self-hosted differences.
- `Procedure`: ordered operating steps.
- `Commands`: copyable commands with placeholders.
- `Expected Output`: what success looks like.
- `Failure Modes`: common errors and recovery steps.
- `Safety Notes`: secrets, destructive actions, cost, publish, or production cautions.
- `Report Back Format`: concise format the agent should use when done.
- `Related Docs`: `/docs-md/...` links that support the workflow.

## Generated Docs Contract
The web docs generator discovers skill files from `web/content/agent-skills/**/SKILL.md`.

- `/docs/agent-skills` and `/docs-md/agent-skills` render the catalog index and this catalog contract.
- `/docs/agent-skills/<skill>` and `/docs-md/agent-skills/<skill>` render individual top-level skills.
- `/docs/agent-skills/<category>/<skill>` and `/docs-md/agent-skills/<category>/<skill>` render nested category skills.
- `/llms.txt` includes the Agent Skills entry and every discovered skill page.
- `/llms-full.txt` includes the Agent Skills catalog, category pages, and full skill bodies.

When adding a new category, update the docs navigation and category map in `web/src/lib/docs.ts` so the category page, markdown path, and bundle order are explicit.

## Hosted Backend Examples
Use hosted production by default:

```bash
export AGENTCLASH_API_URL="https://api.agentclash.dev"
agentclash auth login --device
agentclash workspace list
agentclash workspace use <workspace-id>
```

Only use local or self-hosted URLs when the skill is explicitly about local development or deployment:

```bash
agentclash --api-url http://localhost:8080 doctor
```

## Authoring Procedure
1. Pick the folder from the taxonomy.
2. Read the related upstream skills in dependency order.
3. Verify command names, config names, YAML fields, and API behavior from source-backed docs or code.
4. Write trigger-oriented frontmatter and the required body sections.
5. Prefer production hosted examples unless the workflow is local or self-hosted.
6. Add or update docs-generation tests when a new path, category, or export behavior is introduced.
7. Run the docs tests and lint before opening a PR.

## Validation Commands
```bash
cd web
npm test -- docs.test.ts
npm run lint
```

For CLI packaging-related skill changes, also validate from `cli/`:

```bash
go build ./...
go test -short -race -count=1 ./...
```

## Failure Modes
- Missing frontmatter: the generated page may have an empty name or description.
- Vague description: agents may not discover the skill at the right time.
- New category without generator updates: `/docs-md/agent-skills/<category>` may not exist.
- Examples that default to localhost: users may accidentally run against the wrong backend.
- Claims not tied to current docs or code: downstream skills will repeat incorrect fields or commands.

## Safety Notes
- Do not include tokens, workspace secrets, or customer data in examples.
- Do not tell agents to publish, delete, or mutate production resources without an explicit confirmation step.
- Prefer read-only discovery commands before write commands.
- Keep skill instructions portable; avoid relying on a single agent product unless the section is explicitly install-target guidance.

## Dependency Order
Read related skills in this order so downstream workflows do not redefine upstream concepts:

1. `agentclash-hub`
2. `agentclash-cli-setup`
3. `agentclash-quickstart`
4. `agentclash-runtime-resources-setup`
5. `agentclash-agent-build-author`
6. `agentclash-agent-deployment-setup`
7. `agentclash-challenge-pack-planner`
8. `agentclash-challenge-pack-yaml-author`
9. `agentclash-challenge-pack-input-sets`
10. `agentclash-challenge-pack-tools-sandbox`
11. `agentclash-challenge-pack-artifacts`
12. `agentclash-challenge-pack-scoring-validators`
13. `agentclash-challenge-pack-llm-judges`
14. `agentclash-challenge-pack-validation-publish`
15. `agentclash-eval-runner`
16. `agentclash-scorecard-reader`
17. `agentclash-compare-and-triage`
18. `agentclash-regression-flywheel`
19. `agentclash-ci-release-gate`
20. `agentclash-agent-harness-setup`
21. `agentclash-multi-turn-operator`
22. `agentclash-dataset-workflows`
23. `agentclash-prompt-eval-playground`
24. `agentclash-workspace-admin`
25. `agentclash-security-evaluation`

## Review Checklist
- The folder path matches the taxonomy.
- Frontmatter includes `name`, trigger-oriented `description`, and the three `metadata.agentclash.*` fields.
- Commands and examples use `https://api.agentclash.dev` unless local or self-hosted behavior is explicit.
- The body includes inputs, exact fields or commands, expected outputs, failure modes, safety notes, and report-back format.
- Related docs use `/docs-md/...` links.
- Generated docs, markdown exports, `llms.txt`, and `llms-full.txt` include the updated content.

## Report Back Format
```text
Skill: <name>
Path: web/content/agent-skills/<path>/SKILL.md
Category: <core | agent-build-skills | challenge-pack-skills>
Docs: /docs-md/agent-skills/<path>
Validation: <commands run and result>
Notes: <source-backed caveats or follow-ups>
```

## Related Docs
- `/docs-md/agent-skills`
- `/docs-md/guides/use-with-ai-tools`
- `/docs-md/reference/cli`
- `/docs-md/reference/config`
````