> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costcare.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Hardcore Mode
> Direct access to the raw YAML and Markdown files that define your agent — no visual designer.
Changes made in Hardcore Mode take effect **immediately** on the next incoming message. Edit with care.
Hardcore Mode gives you direct access to the raw files that define your agent's behavior. Instead of the visual designer, you edit YAML and Markdown files in a file tree.
## File structure
Every agent is a folder with the following layout:
```
agent/
workflows/
main.yaml # entry-point logic — runs on every message
skills/
{name}.md # config header + system prompt
```
`agent.yaml` and `flow.yaml` are system files managed by the platform — they are **not** available in Hardcore Mode. Never edit them.
All `.md` files under `skills/` use the same format: a YAML settings header and a system prompt body. The same file type covers agent prompts, sub-agent prompts, and skills — one consistent format for all three.
***
## workflows/
`main.yaml` is the **entry point** — the engine runs it for every incoming message. You can have multiple workflow files; additional ones are called via `run_workflow` actions from `main.yaml` or other workflows.
Each workflow file is a list of **steps** executed in order. Steps share a `WorkflowState` — a key-value store you can write to and read from across steps.
### Minimal example
```yaml theme={null}
steps:
- type: skill
id: answer
skill: answer_question
result_key: response
- type: action
id: send
action:
type: respond
value: "{response}"
```
### Step types
**Run an LLM** using the config and prompt defined in a skill file.
```yaml theme={null}
- type: skill
id: find_answer # unique ID within this file
skill: answer_question # name of skills/answer_question.md (no extension)
result_key: response # save the LLM's reply under this key (default: "response")
instruction: "Be concise" # optional: extra message injected before the LLM call
```
The LLM receives the system prompt from the skill file, the full conversation history, and any messages accumulated by earlier steps (e.g. previous tool results).
**Extract structured data** from the conversation and previous step outputs. No tools, no back-and-forth — one structured LLM call.
```yaml theme={null}
- type: evaluate
id: score_lead
model: claude-haiku-4-5-20251001
description: |
Determine whether the customer has a clear budget and timeline.
output:
- field: has_budget
type: boolean
- field: timeline
type: string_or_null # null when not mentioned
- field: score
type: int
```
**Field types:** `boolean`, `string`, `string_or_null`, `int`
**Branch on a condition** — checks a workflow state value and dispatches an action.
```yaml theme={null}
- type: if
id: route
branches:
- condition:
field: has_budget # key from workflow state
op: truthy # truthy | falsy | eq | neq
action:
type: respond
value: "Score: {score}, timeline: {timeline}"
- condition:
field: score
op: eq
value: 0
action:
type: do_nothing
else:
type: transfer_to_human
```
`{key}` placeholders in `respond.value` are replaced with the matching workflow state value.
**Direct action, no LLM** — immediately executes an action without calling a model.
```yaml theme={null}
- type: action
id: escalate
action:
type: transfer_to_human
```
### Actions
| Action | Stops execution | Description |
| ------------------- | :-------------: | --------------------------------------------------------------------- |
| `respond` | ✓ | Sends a reply. Supports `{key}` placeholders from workflow state. |
| `do_nothing` | ✓ | Stops silently — no reply is sent. |
| `transfer_to_human` | ✓ | Escalates the conversation to a human. |
| `run_workflow` | ✓ | Runs another workflow file as a sub-flow. |
| `set_value` | — | Writes `key: value` to workflow state and continues to the next step. |
```yaml theme={null}
action:
type: run_workflow
workflow: escalation.yaml # must exist under workflows/
```
```yaml theme={null}
action:
type: set_value
key: greeted
value: true
```
***
## skills/\{name}.md
A skill file has two parts separated by `---`:
Between `---` markers — configures the LLM, tools, and iteration limits.
Everything after the closing `---` — the instructions sent to the LLM.
### Full example
```markdown theme={null}
---
skill: answer_question
description: Search the knowledge base and answer customer questions
llm:
model: claude-haiku-4-5-20251001
tools: [search_qa]
max_iterations: 5
---
You are a helpful support agent. Use the search_qa tool to find answers.
Always reply in the same language the customer used.
If nothing is found, say you'll escalate to a human.
```
### Settings header fields
| Field | Required | Description |
| ---------------------- | :------: | ---------------------------------------------------------- |
| `skill` | ✓ | Must match the filename without `.md` |
| `description` | — | Short description shown in the file list |
| `llm.model` | ✓ | Model to use (see [Models](#models)) |
| `llm.thinking_budget` | — | Anthropic extended thinking budget in tokens (e.g. `8000`) |
| `llm.reasoning_effort` | — | OpenAI reasoning effort: `low` \| `medium` \| `high` |
| `tools` | — | List of tool names. Use `[]` for no tools. |
| `max_iterations` | — | Maximum tool-call loops before stopping (default: `10`) |
### Injecting workflow state into prompts
Use `{values.key}` anywhere in the system prompt body to inject a value from workflow state:
```markdown theme={null}
The customer's lead score is {values.score}.
Based on this, adjust your tone accordingly.
```
### Models
Recommended for most use cases.
| Model | Best for |
| --------------------------- | ------------------------------- |
| `claude-haiku-4-5-20251001` | Fast, cost-efficient tasks |
| `claude-sonnet-4-6` | Balanced performance |
| `claude-opus-4-6` | Most capable, complex reasoning |
Use `llm.thinking_budget` to enable extended thinking (tokens budget, e.g. `8000`).
| Model | Best for |
| -------------- | ---------------------------- |
| `gpt-5.5` | Flagship, highest capability |
| `gpt-5.4` | Balanced |
| `gpt-5.4-mini` | Affordable, lighter tasks |
Use `llm.reasoning_effort` (`low` / `medium` / `high`) instead of `thinking_budget`.
### Tools
| Tool | Description |
| ------------- | ---------------------------------------------------- |
| `search_qa` | Semantic search over this org's Q\&A knowledge base |
| `web_search` | Live web search |
| `list_files` | List files in this agent's directory |
| `read_file` | Read a file from this agent's directory |
| `write_file` | Create or overwrite a file in this agent's directory |
| `delete_file` | Delete a file from this agent's directory |
***
## Rules & gotchas
`workflows/main.yaml` is **required**. Without it the agent returns no response.
`id` values must be unique within a workflow file. Duplicate IDs cause unpredictable behavior.
`skill:` must exactly match `skills/{skill}.md` — the match is **case-sensitive**.
`respond`, `do_nothing`, `transfer_to_human`, and `run_workflow` stop execution immediately. Any steps listed after them in the workflow **do not run**.
Unlike other actions, `set_value` writes a value to workflow state and moves on to the **next step** — it never stops the workflow.
Fields produced by `evaluate` are stored in workflow state and can be read by any later `if` branch or `respond` placeholder.
These are system files managed by the platform. Editing them directly may break your agent in unexpected ways.