diff --git a/README.md b/README.md
index 0be0869..62293ba 100644
--- a/README.md
+++ b/README.md
@@ -174,6 +174,15 @@ docker compose logs --tail=120 openstock-runner
 | `status` | string | 항상 `error`입니다. |
 | `message` | string | 실패 원인 메시지입니다. |
 
+## Agent CLI Skill
+
+에이전트는 별도 MCP 서버나 plugin wrapper 없이 `openstock` CLI를 직접 실행하는 전략을 사용합니다.
+
+| Document | Purpose |
+| --- | --- |
+| `skills/openstock-agent-cli/SKILL.md` | 에이전트가 따라야 할 실행 전략, 출력 해석 규칙, 주문 안전 규칙 |
+| `skills/openstock-agent-cli/references/commands/` | CLI depth별 명령 설명과 IO 계약 |
+
 ### Command Output Fields
 
 #### `version`
diff --git a/skills/openstock-agent-cli/SKILL.md b/skills/openstock-agent-cli/SKILL.md
new file mode 100644
index 0000000..2c4c39a
--- /dev/null
+++ b/skills/openstock-agent-cli/SKILL.md
@@ -0,0 +1,97 @@
+---
+name: openstock-agent-cli
+description: Use when operating OpenStock through its CLI for Korean stock search, KIS market/account/order commands, KIND universe scans, OpenDART disclosures, cache management, or agent-safe trading evidence workflows. This skill intentionally avoids MCP/plugin wrappers and relies on direct CLI execution.
+---
+
+# OpenStock Agent CLI Skill
+
+Use this skill when an agent needs Korean stock search, market data, KIS account/order access, KIND universe data, or OpenDART disclosure evidence from this repository.
+
+## Strategy
+
+Do not start an MCP server or create a plugin wrapper. Use the installed `openstock` CLI directly and treat its stdout/stderr JSON as the tool contract.
+
+The CLI is the single integration surface for humans and agents:
+
+```bash
+openstock search 삼성전자
+openstock market 005930
+openstock dart show 005930 --from 20260601 --to 20260609
+openstock account status
+```
+
+## Runtime Model
+
+- `openstock` is a normal process per command invocation.
+- It is not a daemon.
+- It does not open a port.
+- It reads config and cache from `~/.config/openstock`.
+- It prints one JSON object to stdout on success.
+- It prints one JSON object to stderr on failure.
+
+## Output Contract
+
+Every command returns explained JSON:
+
+```json
+{
+  "command": "logical command name",
+  "description": "human and agent readable result description",
+  "fields": [
+    {
+      "name": "field_name",
+      "description": "field meaning",
+      "value": "actual value"
+    }
+  ],
+  "raw": null
+}
+```
+
+Agent behavior:
+
+- Read `fields[].description` before interpreting `fields[].value`.
+- Prefer typed commands over `api call` when a typed command exists.
+- Use `raw` only when the command explicitly returns raw API data.
+- Preserve numeric strings from broker APIs; do not coerce them unless calculation is required.
+- Treat stderr JSON as a command failure even when it is parseable.
+
+## Safety Rules
+
+- `order buy` and `order sell` are live KIS orders.
+- Do not place orders unless the user explicitly requests a real order in the current task.
+- Before any order, check `account status`, target symbol evidence, quantity, order type, and price.
+- For evidence gathering, use read-only commands: `search`, `market`, `market history`, `dart`, `universe`, `account status`, `order status`.
+- Never infer that a missing cache means missing data; run the relevant `sync` command when appropriate.
+
+## Command Documentation
+
+Commands are documented by CLI depth under `references/commands`.
+
+| Command | Documentation |
+| --- | --- |
+| `openstock version` | `references/commands/version/guide.md` |
+| `openstock update` | `references/commands/update/guide.md` |
+| `openstock search` | `references/commands/search/guide.md` |
+| `openstock api *` | `references/commands/api/guide.md` |
+| `openstock account *` | `references/commands/account/guide.md` |
+| `openstock market *` | `references/commands/market/guide.md` |
+| `openstock universe *` | `references/commands/universe/guide.md` |
+| `openstock dart *` | `references/commands/dart/guide.md` |
+| `openstock order *` | `references/commands/order/guide.md` |
+| `openstock cache *` | `references/commands/cache/guide.md` |
+
+## Recommended Evidence Flow
+
+```bash
+openstock api login
+openstock universe sync
+openstock dart sync
+openstock search 삼성전자
+openstock market 005930
+openstock market history 005930 --from 20260101 --to 20260609
+openstock dart show 005930 --from 20260601 --to 20260609 --index 1
+openstock account status
+```
+
+This flow gathers evidence. It is not sufficient by itself for unattended trading.
diff --git a/skills/openstock-agent-cli/references/commands/account/guide.md b/skills/openstock-agent-cli/references/commands/account/guide.md
new file mode 100644
index 0000000..2b06452
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/account/guide.md
@@ -0,0 +1,41 @@
+# `openstock account`
+
+## Purpose
+
+Read KIS account state for the configured live account.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock account status` | Show balance and holdings. |
+
+## `account status`
+
+### Usage
+
+```bash
+openstock account status
+```
+
+### IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | `KIS_ACCESS_TOKEN`, `KIS_APPKEY`, `KIS_APPSECRET`, `KIS_ACCOUNT` |
+| External IO | KIS balance inquiry endpoint. |
+| File IO | `~/.config/openstock/.env` read. |
+| Side effect | none |
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker API used for inquiry. |
+| `account` | Queried account number. |
+| `balance` | Cash, total evaluated asset amount, profit/loss, and account summary values. |
+| `holdings` | Currently held stock list. |
+
+## Agent Notes
+
+Use this before any proposed trade to check cash, holdings, and orderable quantity context.
diff --git a/skills/openstock-agent-cli/references/commands/account/status/guide.md b/skills/openstock-agent-cli/references/commands/account/status/guide.md
new file mode 100644
index 0000000..268dc27
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/account/status/guide.md
@@ -0,0 +1,17 @@
+# `openstock account status`
+
+Purpose: query balance and holdings for the configured KIS account.
+
+Usage:
+
+```bash
+openstock account status
+```
+
+Reads: `KIS_ACCESS_TOKEN`, `KIS_APPKEY`, `KIS_APPSECRET`, `KIS_ACCOUNT`.
+
+External IO: KIS balance inquiry.
+
+Output fields: `broker`, `account`, `balance`, `holdings`.
+
+Agent rule: run before any trade recommendation or live order.
diff --git a/skills/openstock-agent-cli/references/commands/api/call/guide.md b/skills/openstock-agent-cli/references/commands/api/call/guide.md
new file mode 100644
index 0000000..e2dd1da
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/api/call/guide.md
@@ -0,0 +1,19 @@
+# `openstock api call`
+
+Purpose: directly call a KIS GET endpoint with access-token headers.
+
+Usage:
+
+```bash
+openstock api call /uapi/... --param tr_id=... --param KEY=VALUE
+```
+
+Inputs: `endpoint`, repeated `--param KEY=VALUE`.
+
+Reads: KIS credentials and access token from config/env.
+
+External IO: KIS endpoint GET.
+
+Output fields: `broker`, `endpoint`, `params`, `request_semantics`, `response`, `response_semantics`.
+
+Agent rule: prefer typed commands; use this only for endpoints not yet implemented as stable commands.
diff --git a/skills/openstock-agent-cli/references/commands/api/guide.md b/skills/openstock-agent-cli/references/commands/api/guide.md
new file mode 100644
index 0000000..4e2de8f
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/api/guide.md
@@ -0,0 +1,91 @@
+# `openstock api`
+
+## Purpose
+
+Manage broker API metadata, KIS login, and raw endpoint calls.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock api list` | Show registered broker APIs and their capabilities. |
+| `openstock api login [--appkey KEY] [--appsecret SECRET] [--force]` | Issue or reuse a KIS access token. |
+| `openstock api call <endpoint> --param KEY=VALUE` | Direct KIS GET endpoint call with token headers. |
+
+## `api list`
+
+### IO
+
+| Direction | Data |
+| --- | --- |
+| External IO | none |
+| File IO | none |
+| Side effect | none |
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `count` | Number of registered broker APIs. |
+| `apis` | Broker metadata, credential requirements, capability catalog, IO contract, and side effects. |
+
+## `api login`
+
+### Usage
+
+```bash
+openstock api login
+openstock api login --force
+```
+
+### IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | `KIS_APPKEY`, `KIS_APPSECRET`, `KIS_ACCESS_TOKEN`, `KIS_ACCESS_TOKEN_EXPIRED_AT` |
+| Config write | `~/.config/openstock/.env` auth state. |
+| External IO | KIS token endpoint only when token is missing, expired, or `--force` is used. |
+| Side effect | Writes auth token state. |
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker API used for login. |
+| `status` | Login result. |
+| `force` | Whether token refresh was forced. |
+| `credential_source` | Whether credentials came from CLI arguments or config. |
+| `token_storage` | Token storage path and env keys. |
+| `side_effect` | Auth-state write indicator. |
+
+## `api call`
+
+### Usage
+
+```bash
+openstock api call /uapi/... --param tr_id=... --param KEY=VALUE
+```
+
+### IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | `KIS_ACCESS_TOKEN`, `KIS_APPKEY`, `KIS_APPSECRET` |
+| External IO | KIS endpoint GET. |
+| File IO | `~/.config/openstock/.env` read. |
+| Side effect | Endpoint dependent. |
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker used for the direct call. |
+| `endpoint` | Requested endpoint. |
+| `params` | Request parameters. |
+| `request_semantics` | How params map to headers/query. |
+| `response` | Parsed API response. |
+| `response_semantics` | Explanation of response meaning. |
+
+## Agent Notes
+
+Prefer typed commands. Use `api call` only for inspection or endpoints not yet bound as typed commands.
diff --git a/skills/openstock-agent-cli/references/commands/api/list/guide.md b/skills/openstock-agent-cli/references/commands/api/list/guide.md
new file mode 100644
index 0000000..90d4210
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/api/list/guide.md
@@ -0,0 +1,15 @@
+# `openstock api list`
+
+Purpose: return registered broker APIs, credential requirements, capabilities, IO contracts, and side-effect metadata.
+
+Usage:
+
+```bash
+openstock api list
+```
+
+Inputs: none.
+
+Output fields: `count`, `apis`.
+
+Agent rule: use this to discover broker capability metadata; it performs no external IO.
diff --git a/skills/openstock-agent-cli/references/commands/api/login/guide.md b/skills/openstock-agent-cli/references/commands/api/login/guide.md
new file mode 100644
index 0000000..c3f976d
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/api/login/guide.md
@@ -0,0 +1,21 @@
+# `openstock api login`
+
+Purpose: issue or reuse a KIS live API access token.
+
+Usage:
+
+```bash
+openstock api login
+openstock api login --force
+openstock api login --appkey KEY --appsecret SECRET
+```
+
+Inputs: optional `--appkey`, `--appsecret`, `--force`.
+
+Reads: `KIS_APPKEY`, `KIS_APPSECRET`, existing token values.
+
+Writes: `~/.config/openstock/.env` token state.
+
+Output fields: `broker`, `status`, `force`, `credential_source`, `token_storage`, `side_effect`.
+
+Agent rule: do not force refresh unless the user asks or an API call fails because the token is invalid.
diff --git a/skills/openstock-agent-cli/references/commands/cache/guide.md b/skills/openstock-agent-cli/references/commands/cache/guide.md
new file mode 100644
index 0000000..1d63f6e
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/cache/guide.md
@@ -0,0 +1,39 @@
+# `openstock cache`
+
+## Purpose
+
+Inspect and prune local cache under `~/.config/openstock/cache`.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock cache status` | Show cache size and namespace summary. |
+| `openstock cache prune [--dry-run]` | Apply cache retention policy. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| File read | Cache directories. |
+| File delete | Old cache files unless `--dry-run` is used. |
+| External IO | none |
+| Side effect | `prune` deletes files unless dry-run. |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `root` | Cache root path. |
+| `exists` | Whether cache root exists. |
+| `total_files` | Number of cache files. |
+| `total_bytes` | Total cache size. |
+| `namespaces` | Cache namespace summaries. |
+| `dry_run` | Whether prune only reported actions. |
+| `deleted_files` | Number of deleted files. |
+| `deleted_bytes` | Bytes removed. |
+| `reports` | Prune reports by namespace. |
+
+## Agent Notes
+
+Run `cache prune --dry-run` before destructive pruning unless the user clearly asks to clean cache.
diff --git a/skills/openstock-agent-cli/references/commands/cache/prune/guide.md b/skills/openstock-agent-cli/references/commands/cache/prune/guide.md
new file mode 100644
index 0000000..9be1b98
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/cache/prune/guide.md
@@ -0,0 +1,18 @@
+# `openstock cache prune`
+
+Purpose: apply cache retention policy.
+
+Usage:
+
+```bash
+openstock cache prune --dry-run
+openstock cache prune
+```
+
+Reads: `~/.config/openstock/cache`.
+
+Deletes: old cache files unless `--dry-run` is set.
+
+Output fields: `dry_run`, `deleted_files`, `deleted_bytes`, `reports`.
+
+Agent rule: run `--dry-run` first unless the user explicitly requests cleanup.
diff --git a/skills/openstock-agent-cli/references/commands/cache/status/guide.md b/skills/openstock-agent-cli/references/commands/cache/status/guide.md
new file mode 100644
index 0000000..ea46a5c
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/cache/status/guide.md
@@ -0,0 +1,15 @@
+# `openstock cache status`
+
+Purpose: inspect local cache size and namespace summary.
+
+Usage:
+
+```bash
+openstock cache status
+```
+
+Reads: `~/.config/openstock/cache`.
+
+Output fields: `root`, `exists`, `total_files`, `total_bytes`, `namespaces`.
+
+Agent rule: use before cache cleanup or when diagnosing stale local data.
diff --git a/skills/openstock-agent-cli/references/commands/dart/corp/guide.md b/skills/openstock-agent-cli/references/commands/dart/corp/guide.md
new file mode 100644
index 0000000..4da9dbc
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/dart/corp/guide.md
@@ -0,0 +1,17 @@
+# `openstock dart corp`
+
+Purpose: resolve a KRX stock symbol to an OpenDART corp code.
+
+Usage:
+
+```bash
+openstock dart corp 005930
+```
+
+Input: `symbol`.
+
+Reads: OpenDART corp code cache; refreshes on miss when needed.
+
+Output fields: `stock_code`, `corp_code`, `corp_name`, `modify_date`.
+
+Agent rule: use when an OpenDART command needs an explicit corp code.
diff --git a/skills/openstock-agent-cli/references/commands/dart/disclosures/guide.md b/skills/openstock-agent-cli/references/commands/dart/disclosures/guide.md
new file mode 100644
index 0000000..37b0866
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/dart/disclosures/guide.md
@@ -0,0 +1,20 @@
+# `openstock dart disclosures`
+
+Purpose: query disclosure lists from OpenDART.
+
+Usage:
+
+```bash
+openstock dart disclosures 005930 --from 20260601 --to 20260609
+openstock dart disclosures --corp-code 00126380 --page-count 50
+```
+
+Inputs: optional `symbol`, `--corp-code`, `--from`, `--to`, `--corp-cls`, `--page-no`, `--page-count`.
+
+Reads: `OPENDART_API_KEY`; corp-code cache when resolving a symbol.
+
+External IO: OpenDART list API.
+
+Output fields: `query`, `resolved`, `disclosures`.
+
+Agent rule: use for disclosure evidence lists without fetching document text.
diff --git a/skills/openstock-agent-cli/references/commands/dart/document/guide.md b/skills/openstock-agent-cli/references/commands/dart/document/guide.md
new file mode 100644
index 0000000..8295305
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/dart/document/guide.md
@@ -0,0 +1,19 @@
+# `openstock dart document`
+
+Purpose: fetch and extract text from a DART disclosure document by receipt number.
+
+Usage:
+
+```bash
+openstock dart document 20260609000000 --max-chars 20000
+```
+
+Inputs: `rcept_no`, optional `--force`, `--max-chars`.
+
+Reads: `OPENDART_API_KEY`.
+
+Writes: document ZIP cache.
+
+Output fields: document metadata and extracted text.
+
+Agent rule: use `--max-chars` to cap large documents.
diff --git a/skills/openstock-agent-cli/references/commands/dart/guide.md b/skills/openstock-agent-cli/references/commands/dart/guide.md
new file mode 100644
index 0000000..5d76ad6
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/dart/guide.md
@@ -0,0 +1,43 @@
+# `openstock dart`
+
+## Purpose
+
+Query OpenDART listed-company mappings, disclosure lists, and disclosure documents.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock dart sync [--force]` | Refresh OpenDART corp code cache. |
+| `openstock dart status` | Show corp code cache status. |
+| `openstock dart corp <symbol>` | Resolve KRX symbol to DART corp code. |
+| `openstock dart disclosures [symbol] [--corp-code CODE] [--from YYYYMMDD] [--to YYYYMMDD] [--corp-cls Y|K|N|E] [--page-no N] [--page-count N]` | Query disclosure list. |
+| `openstock dart document <rcept_no> [--force] [--max-chars N]` | Fetch disclosure document text. |
+| `openstock dart show <symbol> [--from YYYYMMDD] [--to YYYYMMDD] [--index N] [--page-count N] [--force] [--max-chars N]` | Query disclosures for a symbol and fetch one selected document. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | `OPENDART_API_KEY` for OpenDART API calls. |
+| External IO | OpenDART corp code, list, and document endpoints. |
+| File read/write | `~/.config/openstock/cache/opendart`. |
+| Side effect | `sync`, `document`, and `show` can write cache. |
+
+## Important Fields
+
+| Field | Meaning |
+| --- | --- |
+| `stock_code` | KRX stock code. |
+| `corp_code` | OpenDART 8-digit company code. |
+| `corp_name` | OpenDART company name. |
+| `modify_date` | Corp code mapping modification date. |
+| `query` | Disclosure query sent to OpenDART. |
+| `resolved` | Symbol/corp code resolution details. |
+| `disclosures` | Disclosure list. |
+| `selected` | Disclosure selected by `--index`. |
+| `document` | Disclosure document metadata and extracted text. |
+
+## Agent Notes
+
+Use `dart show` for the common workflow: symbol to disclosures to selected document. Use `dart disclosures` when only the list is needed.
diff --git a/skills/openstock-agent-cli/references/commands/dart/show/guide.md b/skills/openstock-agent-cli/references/commands/dart/show/guide.md
new file mode 100644
index 0000000..1f1ae92
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/dart/show/guide.md
@@ -0,0 +1,19 @@
+# `openstock dart show`
+
+Purpose: query disclosures for a symbol and fetch the selected disclosure document.
+
+Usage:
+
+```bash
+openstock dart show 005930 --from 20260601 --to 20260609 --index 1
+```
+
+Inputs: `symbol`, optional `--from`, `--to`, `--index`, `--page-count`, `--force`, `--max-chars`.
+
+Reads: `OPENDART_API_KEY`; corp-code and document cache.
+
+External IO: OpenDART list and document APIs.
+
+Output fields: `query`, `resolved`, `disclosures`, `selected`, `document`.
+
+Agent rule: preferred command when the task asks for a specific stock's latest disclosure and contents.
diff --git a/skills/openstock-agent-cli/references/commands/dart/status/guide.md b/skills/openstock-agent-cli/references/commands/dart/status/guide.md
new file mode 100644
index 0000000..11aaa6e
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/dart/status/guide.md
@@ -0,0 +1,15 @@
+# `openstock dart status`
+
+Purpose: inspect OpenDART corp code cache status.
+
+Usage:
+
+```bash
+openstock dart status
+```
+
+Reads: OpenDART corp code cache.
+
+Output fields: source/cache metadata and corp count.
+
+Agent rule: if cache is missing, run `openstock dart sync`.
diff --git a/skills/openstock-agent-cli/references/commands/dart/sync/guide.md b/skills/openstock-agent-cli/references/commands/dart/sync/guide.md
new file mode 100644
index 0000000..d54a735
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/dart/sync/guide.md
@@ -0,0 +1,18 @@
+# `openstock dart sync`
+
+Purpose: refresh OpenDART listed-company corp code mapping cache.
+
+Usage:
+
+```bash
+openstock dart sync
+openstock dart sync --force
+```
+
+Reads: `OPENDART_API_KEY`.
+
+Writes: `~/.config/openstock/cache/opendart/corp_codes.json`.
+
+Output fields: source/cache metadata and corp count.
+
+Agent rule: run when corp-code cache is missing, stale, or explicitly requested.
diff --git a/skills/openstock-agent-cli/references/commands/guide.md b/skills/openstock-agent-cli/references/commands/guide.md
new file mode 100644
index 0000000..1e79308
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/guide.md
@@ -0,0 +1,30 @@
+# OpenStock CLI Command Map
+
+This directory mirrors the `openstock` CLI command depth for agent execution.
+
+| CLI Depth | Folder |
+| --- | --- |
+| `openstock version` | `version/` |
+| `openstock update` | `update/` |
+| `openstock search` | `search/` |
+| `openstock api ...` | `api/` |
+| `openstock account ...` | `account/` |
+| `openstock market ...` | `market/` |
+| `openstock universe ...` | `universe/` |
+| `openstock dart ...` | `dart/` |
+| `openstock order ...` | `order/` |
+| `openstock cache ...` | `cache/` |
+
+Subcommands also have leaf folders matching CLI depth, for example:
+
+| CLI Depth | Folder |
+| --- | --- |
+| `openstock api login` | `api/login/` |
+| `openstock account status` | `account/status/` |
+| `openstock market history` | `market/history/` |
+| `openstock universe chunks` | `universe/chunks/` |
+| `openstock dart show` | `dart/show/` |
+| `openstock order buy` | `order/buy/` |
+| `openstock cache prune` | `cache/prune/` |
+
+Agents should read `../../SKILL.md` first, then open the folder matching the command depth they intend to run.
diff --git a/skills/openstock-agent-cli/references/commands/market/guide.md b/skills/openstock-agent-cli/references/commands/market/guide.md
new file mode 100644
index 0000000..343ccf7
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/market/guide.md
@@ -0,0 +1,60 @@
+# `openstock market`
+
+## Purpose
+
+Read KIS market data for a stock symbol.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock market <symbol>` | Current price and company/basic information. |
+| `openstock market history <symbol> --from YYYYMMDD --to YYYYMMDD [--period D|W|M|Y] [--raw-price]` | OHLCV price history. |
+
+## `market <symbol>`
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker API used for data. |
+| `symbol` | Queried KRX symbol. |
+| `price` | Current price and market values. |
+| `company` | Stock/company basic information. |
+
+## `market history`
+
+### Input
+
+| Input | Meaning |
+| --- | --- |
+| `symbol` | KRX symbol. |
+| `--from` | Start date in `YYYYMMDD`. |
+| `--to` | End date in `YYYYMMDD`. |
+| `--period` | `D`, `W`, `M`, or `Y`; default `D`. |
+| `--raw-price` | Use original prices instead of adjusted prices. |
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker API used for data. |
+| `symbol` | Queried KRX symbol. |
+| `period` | Candle period. |
+| `date_range` | Requested date range. |
+| `adjusted` | Whether adjusted price was requested. |
+| `count` | Number of candles. |
+| `candles` | Date-ascending OHLCV values. Numeric values may be strings. |
+| `summary` | KIS summary data. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | KIS app credentials and access token. |
+| External IO | KIS domestic stock quote/history endpoints. |
+| Side effect | none |
+
+## Agent Notes
+
+Use `market` for current context and `market history` for price movement evidence. Always resolve ambiguous names with `search` first.
diff --git a/skills/openstock-agent-cli/references/commands/market/history/guide.md b/skills/openstock-agent-cli/references/commands/market/history/guide.md
new file mode 100644
index 0000000..c21ddc1
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/market/history/guide.md
@@ -0,0 +1,20 @@
+# `openstock market history`
+
+Purpose: query OHLCV price history for a stock.
+
+Usage:
+
+```bash
+openstock market history 005930 --from 20260101 --to 20260609
+openstock market history 005930 --from 20260101 --to 20260609 --period W
+```
+
+Inputs: `symbol`, `--from`, `--to`, optional `--period`, `--raw-price`.
+
+Reads: KIS credentials and access token.
+
+External IO: KIS price history endpoint.
+
+Output fields: `broker`, `symbol`, `period`, `date_range`, `adjusted`, `count`, `candles`, `summary`.
+
+Agent rule: use for price movement evidence; keep numeric strings intact unless calculating.
diff --git a/skills/openstock-agent-cli/references/commands/order/buy/guide.md b/skills/openstock-agent-cli/references/commands/order/buy/guide.md
new file mode 100644
index 0000000..fefff26
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/order/buy/guide.md
@@ -0,0 +1,20 @@
+# `openstock order buy`
+
+Purpose: place a live KIS domestic stock buy order.
+
+Usage:
+
+```bash
+openstock order buy 005930 --qty 1 --price 70000
+openstock order buy 005930 --qty 1 --market
+```
+
+Inputs: `symbol`, `--qty`, one of `--price` or `--market`.
+
+External IO: KIS live order endpoint.
+
+Side effect: live financial buy order.
+
+Output fields: `broker`, `side`, `symbol`, `qty`, `order_type`, `price`, `order`.
+
+Agent rule: only run after explicit current-user approval for a real order.
diff --git a/skills/openstock-agent-cli/references/commands/order/guide.md b/skills/openstock-agent-cli/references/commands/order/guide.md
new file mode 100644
index 0000000..52ec363
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/order/guide.md
@@ -0,0 +1,52 @@
+# `openstock order`
+
+## Purpose
+
+Place and query live KIS domestic stock orders.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock order buy <symbol> --qty QTY (--price PRICE|--market)` | Place a live buy order. |
+| `openstock order sell <symbol> --qty QTY (--price PRICE|--market)` | Place a live sell order. |
+| `openstock order status [order_no] [--from YYYYMMDD] [--to YYYYMMDD]` | Query order/execution status. |
+
+## Safety
+
+`buy` and `sell` are live financial orders. Do not run them unless the user explicitly asks for a real order in the current task.
+
+Before placing an order:
+
+1. Run `openstock account status`.
+2. Confirm the symbol with `search` or `market`.
+3. Confirm side, quantity, order type, and price.
+4. Prefer `order status` for verification after order placement.
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | `KIS_ACCESS_TOKEN`, `KIS_APPKEY`, `KIS_APPSECRET`, `KIS_ACCOUNT` |
+| External IO | KIS order and order inquiry endpoints. |
+| Side effect | `buy` and `sell` place live orders. `status` is read-only. |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker used for order. |
+| `side` | `buy` or `sell`. |
+| `symbol` | Ordered symbol. |
+| `qty` | Order quantity. |
+| `order_type` | `limit` or `market`. |
+| `price` | Limit price or market-order price representation. |
+| `order` | Broker order result. |
+| `account` | Account queried for status. |
+| `order_no` | Requested order number filter. |
+| `orders` | Order/execution list. |
+| `summary` | Broker summary values. |
+
+## Agent Notes
+
+For analysis-only tasks, never use `buy` or `sell`. Use `order status` only when order history is relevant.
diff --git a/skills/openstock-agent-cli/references/commands/order/sell/guide.md b/skills/openstock-agent-cli/references/commands/order/sell/guide.md
new file mode 100644
index 0000000..3712ea7
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/order/sell/guide.md
@@ -0,0 +1,20 @@
+# `openstock order sell`
+
+Purpose: place a live KIS domestic stock sell order.
+
+Usage:
+
+```bash
+openstock order sell 005930 --qty 1 --price 70000
+openstock order sell 005930 --qty 1 --market
+```
+
+Inputs: `symbol`, `--qty`, one of `--price` or `--market`.
+
+External IO: KIS live order endpoint.
+
+Side effect: live financial sell order.
+
+Output fields: `broker`, `side`, `symbol`, `qty`, `order_type`, `price`, `order`.
+
+Agent rule: only run after explicit current-user approval for a real order.
diff --git a/skills/openstock-agent-cli/references/commands/order/status/guide.md b/skills/openstock-agent-cli/references/commands/order/status/guide.md
new file mode 100644
index 0000000..9a2c475
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/order/status/guide.md
@@ -0,0 +1,18 @@
+# `openstock order status`
+
+Purpose: query KIS order and execution status.
+
+Usage:
+
+```bash
+openstock order status
+openstock order status 1234567890 --from 20260601 --to 20260609
+```
+
+Inputs: optional `order_no`, `--from`, `--to`.
+
+External IO: KIS order inquiry endpoint.
+
+Output fields: `broker`, `account`, `order_no`, `orders`, `summary`.
+
+Agent rule: read-only; use after order placement or when auditing order history.
diff --git a/skills/openstock-agent-cli/references/commands/search/guide.md b/skills/openstock-agent-cli/references/commands/search/guide.md
new file mode 100644
index 0000000..2553a13
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/search/guide.md
@@ -0,0 +1,38 @@
+# `openstock search`
+
+## Purpose
+
+Search stock candidates by name or symbol using Naver mobile stock search.
+
+## Usage
+
+```bash
+openstock search 삼성전자
+openstock search 005930
+```
+
+## Input
+
+| Input | Meaning |
+| --- | --- |
+| `query` | Stock name or stock code. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| External IO | `GET https://m.stock.naver.com/front-api/search/autoComplete` |
+| File IO | none |
+| Side effect | none |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `provider` | External data provider. |
+| `query` | Query submitted by the user/agent. |
+| `stocks` | Matching stock candidates. Items can include code, name, market, market code, nation code, category, Reuters code, and URL. |
+
+## Agent Notes
+
+Use this to resolve a human company name to a tradable symbol before calling `market`, `market history`, or `dart`.
diff --git a/skills/openstock-agent-cli/references/commands/universe/chunks/guide.md b/skills/openstock-agent-cli/references/commands/universe/chunks/guide.md
new file mode 100644
index 0000000..9ea17ca
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/universe/chunks/guide.md
@@ -0,0 +1,17 @@
+# `openstock universe chunks`
+
+Purpose: divide the stock universe into scan chunks.
+
+Usage:
+
+```bash
+openstock universe chunks --market KOSDAQ --kind common_stock --size 100
+```
+
+Inputs: optional `--market`, `--kind`, `--size`.
+
+Reads: universe cache.
+
+Output fields: `source`, `cache_date`, `filtered_count`, `chunk_size`, `chunk_count`, `chunks`.
+
+Agent rule: preferred for full-market scan planning.
diff --git a/skills/openstock-agent-cli/references/commands/universe/guide.md b/skills/openstock-agent-cli/references/commands/universe/guide.md
new file mode 100644
index 0000000..81d37d5
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/universe/guide.md
@@ -0,0 +1,46 @@
+# `openstock universe`
+
+## Purpose
+
+Build and query a local universe of listed Korean stocks from KIND.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock universe sync [--force]` | Refresh KIND universe cache. |
+| `openstock universe status` | Show local universe cache status. |
+| `openstock universe list [--market MARKET] [--kind KIND] [--offset N] [--limit N]` | Page through stocks. |
+| `openstock universe chunks [--market MARKET] [--kind KIND] [--size N]` | Build scan chunks. |
+| `openstock universe validate` | Validate expected size and representative symbols. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| External IO | KIND listed company download on sync/cache miss. |
+| File read/write | `~/.config/openstock/cache/universe/kind`. |
+| Side effect | `sync` writes cache and prunes old snapshots. Read commands can sync on cache miss. |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `source` | Data source. |
+| `cache_date` | Cache date. |
+| `refreshed_at` | Refresh timestamp. |
+| `refreshed` | Whether command refreshed data. |
+| `stock_count` | Number of stocks in snapshot. |
+| `counts_by_market` | Count by market. |
+| `total_count` | Total stocks before filtering. |
+| `filtered_count` | Stocks after filter. |
+| `offset` | Pagination offset. |
+| `limit` | Pagination limit. |
+| `stocks` | Normalized stock records. |
+| `chunk_size` | Requested chunk size. |
+| `chunk_count` | Number of chunks. |
+| `chunks` | Scan chunk list. |
+
+## Agent Notes
+
+Use `chunks` when scanning many stocks. Do not request the whole universe if a paged or chunked workflow is enough.
diff --git a/skills/openstock-agent-cli/references/commands/universe/list/guide.md b/skills/openstock-agent-cli/references/commands/universe/list/guide.md
new file mode 100644
index 0000000..97b7176
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/universe/list/guide.md
@@ -0,0 +1,17 @@
+# `openstock universe list`
+
+Purpose: page through normalized stock universe records.
+
+Usage:
+
+```bash
+openstock universe list --market KOSPI --kind common_stock --offset 0 --limit 100
+```
+
+Inputs: optional `--market`, `--kind`, `--offset`, `--limit`.
+
+Reads: universe cache; may refresh on cache miss.
+
+Output fields: `source`, `cache_date`, `total_count`, `filtered_count`, `offset`, `limit`, `stocks`.
+
+Agent rule: use pagination instead of loading the full universe when possible.
diff --git a/skills/openstock-agent-cli/references/commands/universe/status/guide.md b/skills/openstock-agent-cli/references/commands/universe/status/guide.md
new file mode 100644
index 0000000..f0fb622
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/universe/status/guide.md
@@ -0,0 +1,15 @@
+# `openstock universe status`
+
+Purpose: inspect local KIND universe cache status.
+
+Usage:
+
+```bash
+openstock universe status
+```
+
+Reads: universe cache.
+
+Output fields: `source`, `cache_date`, `refreshed_at`, `refreshed`, `stock_count`, `counts_by_market`.
+
+Agent rule: if cache is missing, run `openstock universe sync`.
diff --git a/skills/openstock-agent-cli/references/commands/universe/sync/guide.md b/skills/openstock-agent-cli/references/commands/universe/sync/guide.md
new file mode 100644
index 0000000..b060946
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/universe/sync/guide.md
@@ -0,0 +1,18 @@
+# `openstock universe sync`
+
+Purpose: refresh KIND listed stock universe cache.
+
+Usage:
+
+```bash
+openstock universe sync
+openstock universe sync --force
+```
+
+External IO: KIND listed company download.
+
+Writes: `~/.config/openstock/cache/universe/kind`.
+
+Output fields: `source`, `cache_date`, `refreshed_at`, `refreshed`, `stock_count`, `counts_by_market`.
+
+Agent rule: run before broad scans if the cache date matters.
diff --git a/skills/openstock-agent-cli/references/commands/universe/validate/guide.md b/skills/openstock-agent-cli/references/commands/universe/validate/guide.md
new file mode 100644
index 0000000..70e5f42
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/universe/validate/guide.md
@@ -0,0 +1,18 @@
+# `openstock universe validate`
+
+Purpose: validate universe size and representative stock expectations.
+
+Usage:
+
+```bash
+openstock universe validate
+openstock universe validate --expect 005930=삼성전자
+```
+
+Inputs: minimum count options and repeated `--expect SYMBOL=NAME`.
+
+Reads: universe cache.
+
+Output fields: validation checks and status.
+
+Agent rule: run after sync when verifying that the cached universe is usable.
diff --git a/skills/openstock-agent-cli/references/commands/update/guide.md b/skills/openstock-agent-cli/references/commands/update/guide.md
new file mode 100644
index 0000000..69cc44f
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/update/guide.md
@@ -0,0 +1,49 @@
+# `openstock update`
+
+## Purpose
+
+Update the installed `openstock` binary from the latest Gitea release asset.
+
+## Usage
+
+```bash
+openstock update
+openstock update --force
+```
+
+## Input
+
+| Input | Meaning |
+| --- | --- |
+| `--force` | Reinstall from the latest release asset even when the current version matches. |
+| `OPENSTOCK_INSTALL_DIR` | Optional install directory override. |
+| `OPENSTOCK_RELEASE_API_URL` | Optional release API URL override. |
+| `OPENSTOCK_RELEASE_ASSET_SUFFIX` | Optional asset suffix override. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| External IO | Gitea latest release API and selected release asset download. |
+| File write | Installed `openstock` binary. |
+| Side effect | Replaces the installed binary when newer or forced. |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `release_api_url` | Gitea release API endpoint used for update discovery. |
+| `current_version` | Version of the running binary. |
+| `latest_version` | Version parsed from latest release tag. |
+| `release_tag` | Latest release tag. |
+| `release_url` | Human-readable release page. |
+| `asset_name` | Release asset selected for installation. |
+| `asset_url` | Asset download URL. |
+| `install_dir` | Directory where the binary is installed. |
+| `status` | `updated` or `up_to_date`. |
+| `stdout` | Installer stdout. |
+| `stderr` | Installer stderr. |
+
+## Agent Notes
+
+Use `--force` only when the user asks to reinstall or when verifying release assets.
diff --git a/skills/openstock-agent-cli/references/commands/version/guide.md b/skills/openstock-agent-cli/references/commands/version/guide.md
new file mode 100644
index 0000000..1460615
--- /dev/null
+++ b/skills/openstock-agent-cli/references/commands/version/guide.md
@@ -0,0 +1,34 @@
+# `openstock version`
+
+## Purpose
+
+Return the installed `openstock` package name and version.
+
+## Usage
+
+```bash
+openstock version
+```
+
+## Input
+
+No arguments.
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| External IO | none |
+| File IO | none |
+| Side effect | none |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Cargo package/program name. |
+| `version` | Version of the running `openstock` binary. |
+
+## Agent Notes
+
+Use this before update checks or when reporting runtime provenance.