system-guide

Files (1)

• SKILL.md

SKILL.md (first lines)

# LINAR System Guide

Use this skill when the user asks how LINAR works, how to configure it, how to
extend it with skills or MCP servers, where a behavior comes from, or how to
troubleshoot runtime issues.

LINAR is an autonomous task execution system, not only a prompt wrapper. It
combines an LLM conversation loop, tool calling, a state-machine-oriented
orchestrator, Markdown skills, MCP tools, DAG planning, subagents, hooks, and
state-oriented memory.

## Operating Principles

- Prefer current source code over memory or old docs. This project changes quickly.
- Inspect the relevant code path before giving detailed implementation advice.
- When a user asks "how do I do X?", answer with the practical workflow first,
  then mention the internal files only when useful.
- When a user asks LINAR to install or configure something, treat that as an
  operational task: read the instructions, infer the required config, apply the
  smallest safe change, and verify.
- Never write API keys, tokens, passwords, or private credentials into tracked
  files or examples. Use environment variables such as `${TAVILY_API_KEY}`.
- Do not edit `agent/config.yaml` for a purely explanatory question. Edit it
  only when the user is clearly asking LINAR to configure the local runtime.

## Mental Model

At a high level:

```text
user request
  -> prompt + skill listing + memory/context
  -> LLM response
  -> tool calls
  -> tool results appended to history
  -> repeat until final response, interruption, or turn limit
```

For multi-step work, LINAR can create a DAG plan and run subagents in parallel.
For specialized behavior, LINAR loads a skill. For external capabilities, LINAR
can load MCP tools from configured or locally discovered MCP servers.

The intended state flow is:

```text
IDLE -> INGEST -> PROCESS -> COMPLETE -> IDLE
                  |
                  v
            SKILL_LOAD -> SKILL_EXEC -> SKILL_UNLOAD -> COMPLETE -> IDLE
```

## Configuration

LINAR reads local configuration from `agent/config.yaml`, creating it from
`agent/config.yaml.example` when missing. Treat `agent/config.yaml` as a local
runtime file that may contain machine-specific paths and secrets.

Use these rules:

- Put shareable defaults and commented examples in `agent/config.yaml.example`.
- Put local runtime choices in `agent/config.yaml`.
- Put secrets in environment variables and reference them as `${ENV_VAR}`.
- Do not commit `agent/config.yaml`.

Common configuration areas:

- model providers and model names
- enabled toolsets
- web search backend
- vision provider
- permission modes
- MCP server definitions
- memory settings
- prompt file order

## Skills

Skills are Markdown-defined behaviors under `skills/<name>/SKILL.md`.

Important behavior:

- Skills are discovered from `skills/*/SKILL.md`.
- LINAR dynamically tells the model which skills are available.
- The model invokes the generic `skill` tool by name.
- Loading a skill appends the skill instructions to LINAR's base prompt, so the
  identity, memory, and project rules remain available.
- `allowed-tools` narrows the visible tool set for that skill.
- Optional `skill.json` and `scripts/` can expose bundled helper scripts as
  skill-specific tools.

### Installing Or Updating Skills

When the user asks to install or create a skill:

1. Read the source material or installation instructions.
2. Create or update `skills/<skill-name>/SKILL.md`.
3. Add optional `skill.json` or `scripts/` only when the skill needs executable
   helpers.
4. Keep frontmatter concise: `name`, `description`, and `allowed-tools` are the
   most important fields.
5. Verify the skill loader can parse the skill.
6. Tell the user whether LINAR needs a restart for the new skill to appear.

Use `skill-writer` for detailed guidance on authoring skills.

## MCP Servers

MCP servers add external tools to LINAR. LINAR supports two MCP discovery paths:

- `mcp_servers:` entries in `agent/config.yaml`
- local auto-discovery under `agent/tool/mcp_tools/server/<name>/`

Configured MCP tools are exposed to the model as names like:

```text
mcp_<server_name>_<tool_name>
```

MCP startup is intentionally non-blocking in GUI/Web mode: native tools load

From lbz0000ff/LINAR, MIT.

More from lbz0000ff/LINAR