nanocode-cli 0.7.2__tar.gz → 0.8.0__tar.gz

{nanocode_cli-0.7.2/nanocode_cli.egg-info → nanocode_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nanocode-cli
-Version: 0.7.2
+Version: 0.8.0
 Summary: A small terminal coding agent written in Python
 Author-email: hit9 <hit9@icloud.com>
 License-Expression: BSD-3-Clause
@@ -131,6 +131,8 @@ Commands:
 
 - `/help`: show commands and tools.
 - `/status`: show runtime status, including the active session id.
+- `/context [PATH]`: show the model's context frame — environment, memory (goal, plan, known facts, check), and file state; `PATH` shows that file's current in-context lines.
+- `/skills`: list installed skills (load with `Skill(name)` or reference inline with `$name`).
 - `/config`: show active config.
 - `/api [auto|chat|anthropic]`: show or set provider API format.
 - `/debug [on|off]`: toggle model I/O debug traces.
@@ -140,6 +142,7 @@ Commands:
 - `/provider [NAME]`: show or set provider.
 - `/model [MODEL]`: show or set model.
 - `/reason`: choose reasoning effort.
+- `/strict`: toggle strict tool-call schemas (OpenAI / DeepSeek only).
 - `/set KEY VALUE`: set supported provider/runtime values for the current session.
 - `/yolo`: toggle tool confirmations.
 - `/exit`, `/quit`: exit.
@@ -156,6 +159,7 @@ Tools:
 - Working notes: `Note`.
 - Ask the user: `Question`.
 - MCP: `MCP`.
+- Skills: `Skill` loads a skill's full instructions on demand (offered whenever any skill exists — the built-in `nanocode-help` means it is normally always available).
 
 `Read`, `Search`, and `InspectCode` return line anchors where useful. `Edit` uses current `line:hash` anchors to reject stale edits.
 
@@ -170,12 +174,14 @@ Default config location:
 Main fields:
 
 - `[provider] active = "name"`
-- `[provider.<name>]`: `url`, `key`, `model`, `api`, `prompt_cache_key`, `available_models`, `reasoning`, `chat_reasoning`, `temperature`, `timeout`
+- `[provider.<name>]`: `url`, `key`, `model`, `api`, `prompt_cache_key`, `available_models`, `reasoning`, `chat_reasoning`, `temperature`, `max_tokens`, `strict_tools`, `timeout`
 - `[paths] data_dir`
-- `[runtime] shell_timeout`, `max_agent_steps`, `max_context_tokens`, `check_updates`, `update_check_interval_hours`, `session_retention_days`, `yolo`, `debug`
+- `[runtime] shell_timeout`, `max_agent_steps`, `max_context_tokens`, `max_parallel_tools`, `check_updates`, `update_check_interval_hours`, `session_retention_days`, `yolo`, `debug`, `tips`
 
 `api = "auto"` chooses between Chat Completions and Anthropic Messages using provider/model profiles. `prompt_cache_key = "auto"` derives a stable key from provider, model, workspace, and tool schema names.
 
+`strict_tools = true` (toggle with `/strict`) constrains tool-call arguments to each tool's JSON schema. It only takes effect on hosts that support it (OpenAI and DeepSeek) and on the Chat Completions path; it is a no-op elsewhere. For DeepSeek, enabling it routes requests to the `/beta` endpoint. Tools whose schemas can't be represented under strict function calling fall back to non-strict automatically.
+
 Runtime flags such as `--yolo`, `--debug`, and `--mcp` apply to resumed sessions too. Saved sessions do not carry their old runtime config forward.
 
 ## MCP
@@ -215,6 +221,37 @@ Manage servers at runtime:
 - `/mcp refresh [server]`: rediscover servers.
 - `/mcp login <server>` / `/mcp logout <server>`: OAuth login and logout.
 
+## Skills
+
+Skills are reusable instruction packs the agent can pull in on demand. Each skill is a folder with a `SKILL.md`:
+
+```text
+.nanocode/skills/                 # project skills (travel with the repo)
+  release-notes/
+    SKILL.md
+    scripts/
+      collect_commits.py
+~/.nanocode/skills/               # personal skills (all projects)
+```
+
+`SKILL.md` has `name`/`description` frontmatter and a Markdown body of instructions:
+
+```markdown
+---
+name: release-notes
+description: Draft a CHANGELOG entry from commits since the last release.
+---
+Run `python "{skill_dir}/scripts/collect_commits.py" <last-tag>` to gather commits,
+then group them by type and write entries in the house style.
+```
+
+- **Discovery**: `.nanocode/skills/` (project) and `~/.nanocode/skills/` (user). On a name clash the project skill wins.
+- **How the model sees them**: only a compact `SKILLS` index (name + description) sits in context; the full body is loaded on demand when the model calls `Skill(name)`. A repeated load of the same skill collapses to a pointer so the instructions are not re-billed. When no skills are installed, nothing is added to the prompt.
+- **Reference one inline**: type `$name` in your message (Tab-completes) to nudge the model to use that skill; its instructions are injected for that turn.
+- **Bundled scripts**: `{skill_dir}` (or `${SKILL_DIR}`) in the body expands to the skill's absolute folder path, so the model can run bundled scripts via `Bash` (subject to normal confirmation unless `/yolo`).
+- **Inspect**: `/skills` lists installed skills; the status bar and `/status` show the count.
+- **Built-in**: a `nanocode-help` skill ships by default and carries a self-contained manual — authored prose on how to use nanocode, its features, and common problems, plus command/tool/config lists assembled from nanocode's own `/help` text, tool descriptions, and config keys. So "how do I / what does X / why is Y" questions are answered from the manual without searching the source, and the lists can't drift from the running version. Drop a `nanocode-help` skill of your own to override it.
+
 ## Providers
 
 The following providers have been tested with nanocode:

{nanocode_cli-0.7.2 → nanocode_cli-0.8.0}/README.md

@@ -94,6 +94,8 @@ Commands:
 
 - `/help`: show commands and tools.
 - `/status`: show runtime status, including the active session id.
+- `/context [PATH]`: show the model's context frame — environment, memory (goal, plan, known facts, check), and file state; `PATH` shows that file's current in-context lines.
+- `/skills`: list installed skills (load with `Skill(name)` or reference inline with `$name`).
 - `/config`: show active config.
 - `/api [auto|chat|anthropic]`: show or set provider API format.
 - `/debug [on|off]`: toggle model I/O debug traces.
@@ -103,6 +105,7 @@ Commands:
 - `/provider [NAME]`: show or set provider.
 - `/model [MODEL]`: show or set model.
 - `/reason`: choose reasoning effort.
+- `/strict`: toggle strict tool-call schemas (OpenAI / DeepSeek only).
 - `/set KEY VALUE`: set supported provider/runtime values for the current session.
 - `/yolo`: toggle tool confirmations.
 - `/exit`, `/quit`: exit.
@@ -119,6 +122,7 @@ Tools:
 - Working notes: `Note`.
 - Ask the user: `Question`.
 - MCP: `MCP`.
+- Skills: `Skill` loads a skill's full instructions on demand (offered whenever any skill exists — the built-in `nanocode-help` means it is normally always available).
 
 `Read`, `Search`, and `InspectCode` return line anchors where useful. `Edit` uses current `line:hash` anchors to reject stale edits.
 
@@ -133,12 +137,14 @@ Default config location:
 Main fields:
 
 - `[provider] active = "name"`
-- `[provider.<name>]`: `url`, `key`, `model`, `api`, `prompt_cache_key`, `available_models`, `reasoning`, `chat_reasoning`, `temperature`, `timeout`
+- `[provider.<name>]`: `url`, `key`, `model`, `api`, `prompt_cache_key`, `available_models`, `reasoning`, `chat_reasoning`, `temperature`, `max_tokens`, `strict_tools`, `timeout`
 - `[paths] data_dir`
-- `[runtime] shell_timeout`, `max_agent_steps`, `max_context_tokens`, `check_updates`, `update_check_interval_hours`, `session_retention_days`, `yolo`, `debug`
+- `[runtime] shell_timeout`, `max_agent_steps`, `max_context_tokens`, `max_parallel_tools`, `check_updates`, `update_check_interval_hours`, `session_retention_days`, `yolo`, `debug`, `tips`
 
 `api = "auto"` chooses between Chat Completions and Anthropic Messages using provider/model profiles. `prompt_cache_key = "auto"` derives a stable key from provider, model, workspace, and tool schema names.
 
+`strict_tools = true` (toggle with `/strict`) constrains tool-call arguments to each tool's JSON schema. It only takes effect on hosts that support it (OpenAI and DeepSeek) and on the Chat Completions path; it is a no-op elsewhere. For DeepSeek, enabling it routes requests to the `/beta` endpoint. Tools whose schemas can't be represented under strict function calling fall back to non-strict automatically.
+
 Runtime flags such as `--yolo`, `--debug`, and `--mcp` apply to resumed sessions too. Saved sessions do not carry their old runtime config forward.
 
 ## MCP
@@ -178,6 +184,37 @@ Manage servers at runtime:
 - `/mcp refresh [server]`: rediscover servers.
 - `/mcp login <server>` / `/mcp logout <server>`: OAuth login and logout.
 
+## Skills
+
+Skills are reusable instruction packs the agent can pull in on demand. Each skill is a folder with a `SKILL.md`:
+
+```text
+.nanocode/skills/                 # project skills (travel with the repo)
+  release-notes/
+    SKILL.md
+    scripts/
+      collect_commits.py
+~/.nanocode/skills/               # personal skills (all projects)
+```
+
+`SKILL.md` has `name`/`description` frontmatter and a Markdown body of instructions:
+
+```markdown
+---
+name: release-notes
+description: Draft a CHANGELOG entry from commits since the last release.
+---
+Run `python "{skill_dir}/scripts/collect_commits.py" <last-tag>` to gather commits,
+then group them by type and write entries in the house style.
+```
+
+- **Discovery**: `.nanocode/skills/` (project) and `~/.nanocode/skills/` (user). On a name clash the project skill wins.
+- **How the model sees them**: only a compact `SKILLS` index (name + description) sits in context; the full body is loaded on demand when the model calls `Skill(name)`. A repeated load of the same skill collapses to a pointer so the instructions are not re-billed. When no skills are installed, nothing is added to the prompt.
+- **Reference one inline**: type `$name` in your message (Tab-completes) to nudge the model to use that skill; its instructions are injected for that turn.
+- **Bundled scripts**: `{skill_dir}` (or `${SKILL_DIR}`) in the body expands to the skill's absolute folder path, so the model can run bundled scripts via `Bash` (subject to normal confirmation unless `/yolo`).
+- **Inspect**: `/skills` lists installed skills; the status bar and `/status` show the count.
+- **Built-in**: a `nanocode-help` skill ships by default and carries a self-contained manual — authored prose on how to use nanocode, its features, and common problems, plus command/tool/config lists assembled from nanocode's own `/help` text, tool descriptions, and config keys. So "how do I / what does X / why is Y" questions are answered from the manual without searching the source, and the lists can't drift from the running version. Drop a `nanocode-help` skill of your own to override it.
+
 ## Providers
 
 The following providers have been tested with nanocode:

{nanocode_cli-0.7.2 → nanocode_cli-0.8.0}/README.zh-CN.md

@@ -94,6 +94,8 @@ nanocode --resume last
 
 - `/help`：显示命令和工具。
 - `/status`：显示运行状态，包括当前 session id。
+- `/context [PATH]`：显示模型的上下文帧——环境、记忆（goal、plan、known facts、check）和文件状态；`PATH` 显示该文件当前在上下文中的行。
+- `/skills`：列出已安装的 skills（用 `Skill(name)` 加载，或在消息中用 `$name` 引用）。
 - `/config`：显示当前配置。
 - `/api [auto|chat|anthropic]`：显示或设置 provider API 格式。
 - `/debug [on|off]`：切换模型 I/O debug trace。
@@ -103,6 +105,7 @@ nanocode --resume last
 - `/provider [NAME]`：显示或设置 provider。
 - `/model [MODEL]`：显示或设置模型。
 - `/reason`：选择 reasoning effort。
+- `/strict`：切换严格工具调用 schema（仅 OpenAI / DeepSeek）。
 - `/set KEY VALUE`：设置当前 session 支持的 provider/runtime 值。
 - `/yolo`：切换工具确认。
 - `/exit`, `/quit`：退出。
@@ -119,6 +122,7 @@ nanocode --resume last
 - 工作笔记：`Note`。
 - 询问用户：`Question`。
 - MCP：`MCP`。
+- Skills：`Skill` 按需加载某个 skill 的完整说明（只要存在任一 skill 即提供——内置的 `nanocode-help` 意味着它通常始终可用）。
 
 `Read`、`Search` 和 `InspectCode` 会在合适时返回行锚点。`Edit` 使用当前 `line:hash` 锚点拒绝过期编辑。
 
@@ -133,12 +137,14 @@ nanocode --resume last
 主要字段：
 
 - `[provider] active = "name"`
-- `[provider.<name>]`：`url`, `key`, `model`, `api`, `prompt_cache_key`, `available_models`, `reasoning`, `chat_reasoning`, `temperature`, `timeout`
+- `[provider.<name>]`：`url`, `key`, `model`, `api`, `prompt_cache_key`, `available_models`, `reasoning`, `chat_reasoning`, `temperature`, `max_tokens`, `strict_tools`, `timeout`
 - `[paths] data_dir`
-- `[runtime] shell_timeout`, `max_agent_steps`, `max_context_tokens`, `check_updates`, `update_check_interval_hours`, `session_retention_days`, `yolo`, `debug`
+- `[runtime] shell_timeout`, `max_agent_steps`, `max_context_tokens`, `max_parallel_tools`, `check_updates`, `update_check_interval_hours`, `session_retention_days`, `yolo`, `debug`, `tips`
 
 `api = "auto"` 会根据 provider/model profile 在 Chat Completions 和 Anthropic Messages 之间选择。`prompt_cache_key = "auto"` 会根据 provider、model、workspace 和工具 schema 名称生成稳定 key。
 
+`strict_tools = true`（用 `/strict` 切换）会将工具调用参数约束到每个工具的 JSON schema。它仅在支持该特性的 host（OpenAI 和 DeepSeek）以及 Chat Completions 路径上生效，其他情况下为空操作。对 DeepSeek，启用后请求会路由到 `/beta` 端点。无法在严格函数调用下表示的工具 schema 会自动回退到非严格模式。
+
 `--yolo`、`--debug` 和 `--mcp` 等 runtime flags 对恢复的 session 同样生效。保存的 session 不会携带旧 runtime config。
 
 ## MCP
@@ -178,6 +184,37 @@ HTTP 鉴权选项（`auth`、`bearer_token_env_var`、`env_http_headers`）只
 - `/mcp refresh [server]`：重新发现服务器。
 - `/mcp login <server>` / `/mcp logout <server>`：OAuth 登录和登出。
 
+## Skills
+
+Skills 是可复用的指令包，agent 可按需加载。每个 skill 是一个包含 `SKILL.md` 的文件夹：
+
+```text
+.nanocode/skills/                 # 项目 skills（随仓库一起提交）
+  release-notes/
+    SKILL.md
+    scripts/
+      collect_commits.py
+~/.nanocode/skills/               # 个人 skills（对所有项目生效）
+```
+
+`SKILL.md` 带有 `name`/`description` 前置元数据，正文是 Markdown 指令：
+
+```markdown
+---
+name: release-notes
+description: Draft a CHANGELOG entry from commits since the last release.
+---
+运行 `python "{skill_dir}/scripts/collect_commits.py" <last-tag>` 收集提交，
+再按类型分组并以项目既有风格撰写条目。
+```
+
+- **发现路径**：`.nanocode/skills/`（项目）和 `~/.nanocode/skills/`（用户）。同名时项目 skill 优先。
+- **模型如何看到**：上下文中只放一个精简的 `SKILLS` 索引（name + description）；完整正文仅在模型调用 `Skill(name)` 时按需加载。对同一 skill 的重复加载会折叠为一行指针，避免重复计费。未安装任何 skill 时不会向 prompt 添加内容。
+- **内联引用**：在消息中输入 `$name`（支持 Tab 补全）以提示模型使用该 skill；其指令会为该轮注入。
+- **随附脚本**：正文中的 `{skill_dir}`（或 `${SKILL_DIR}`）会展开为该 skill 的绝对目录路径，模型可通过 `Bash` 运行随附脚本（除非 `/yolo`，否则仍需正常确认）。
+- **查看**：`/skills` 列出已安装的 skills；状态栏和 `/status` 会显示数量。
+- **内置**：默认自带 `nanocode-help` skill，其正文是一份自包含手册——包含关于如何使用 nanocode、其功能和常见问题的成文说明，外加由 nanocode 自身的 `/help` 文本、工具描述和配置项在加载时拼装而成的命令/工具/配置清单。因此“怎么用 / X 是什么 / 为什么 Y”这类问题可直接从手册回答，无需检索源码，且清单不会与运行版本脱节。放置同名 `nanocode-help` skill 即可覆盖它。
+
 ## Providers
 
 以下 provider 已在 nanocode 中测试通过：

{nanocode_cli-0.7.2 → nanocode_cli-0.8.0}/nanocode.py

@@ -45,7 +45,7 @@ from prompt_toolkit.buffer import Buffer
 from prompt_toolkit.completion import CompleteEvent, Completer, Completion
 from prompt_toolkit.document import Document
 from prompt_toolkit.filters import Condition, has_completions, is_done
-from prompt_toolkit.formatted_text import ANSI, FormattedText
+from prompt_toolkit.formatted_text import ANSI, FormattedText, to_formatted_text
 from prompt_toolkit.history import FileHistory
 from prompt_toolkit.key_binding import KeyBindings
 from prompt_toolkit.keys import Keys
@@ -63,7 +63,7 @@ from rich.console import Console
 from rich.markdown import Markdown
 from rich.rule import Rule
 
-__version__ = "0.7.2"
+__version__ = "0.8.0"
 
 Json = dict[str, Any]
 HTTP_USER_AGENT = "nanocode/" + __version__
@@ -538,6 +538,9 @@ class AgentState:
     current_model_call_started_at: float = 0.0
     manual_model_retry_requested: bool = False
     model_retry_count: int = 0
+    compaction_count: int = 0
+    prefix_fingerprint: str = ""
+    prefix_fingerprints: list[str] = field(default_factory=list)
 
     def __post_init__(self) -> None:
         self.plan = self.plan_items(self.plan)
@@ -854,6 +857,9 @@ class SessionSnapshotCodec:
             "known": state.known,
             "check": state.check,
             "summary": state.summary,
+            "compaction_count": state.compaction_count,
+            "prefix_fingerprint": state.prefix_fingerprint,
+            "prefix_fingerprints": state.prefix_fingerprints,
         }
 
     @staticmethod
@@ -1100,6 +1106,200 @@ class SessionSnapshotStore:
         return os.path.abspath(os.path.join(os.path.expanduser(data_dir), *parts))
 
 
+@dataclass
+class Skill:
+    name: str
+    description: str
+    body: str
+    dir: str
+    source: str  # "project" or "user"
+
+
+class SkillLibrary:
+    """Skills discovered from `.nanocode/skills/<name>/SKILL.md` (project) and the user data dir.
+
+    Each skill is a Markdown file with `name`/`description` frontmatter; the index (name + description)
+    rides the cache-stable prefix so the model knows what exists, and the full body is pulled into the
+    conversation only when the model calls Skill(name) or the user references it with `$name`."""
+
+    FRONTMATTER = re.compile(r"^---\n(.*?)\n---\n?(.*)$", re.DOTALL)
+    META_LINE = re.compile(r"^([A-Za-z0-9_-]+):[ \t]*(.*)$", re.MULTILINE)
+    MENTION_PATTERN = re.compile(r"(?<![A-Za-z0-9_])\$([A-Za-z0-9_-]+)")
+
+    # Authored manual behind the built-in `nanocode-help` skill. Explains concepts, workflows, and
+    # common problems — the prose a "how do I / why does" question needs, which the auto-generated
+    # command/tool/key lists (appended in builtins) cannot supply. Kept broader than `/help`.
+    MANUAL = """\
+# nanocode manual
+
+nanocode is a concise, single-file terminal coding agent. You describe a task; it plans, calls
+tools in a loop (read files, search, edit, run commands), and returns a short answer. Assistant
+text is user-visible markdown in your language.
+
+## Getting started
+- Config lives at `~/.nanocode/config.toml`. At minimum set `provider.url`, `provider.key`, and
+  `provider.model`. `/status` and startup warn when these are missing.
+- View config with `/config`; change most values for the session with `/set KEY VALUE`.
+- Pick provider/model/effort at runtime with `/provider`, `/model`, `/reason`.
+
+## How the agent works
+- It acts when the task is clear and keeps using tools until done or blocked, up to
+  `runtime.max_agent_steps`. It does not repeat a failed call unchanged; tool errors come back as
+  results so it can self-correct.
+- Read-only tools in one batch run concurrently (`runtime.max_parallel_tools`); edits and shell run
+  serially. It keeps working notes (goal/plan/known/check) via the `Note` tool, shown in `/context`.
+- It answers concisely by default and notes which files changed and which checks it ran (or did not).
+
+## Context model
+Each request is a cache-stable prefix (system prompt, environment, the SKILLS index, the MCP tools
+index, and tool schemas) followed by the conversation, then the `Memory` and `FILE STATE` sections.
+`Read`/`Edit` refresh `FILE STATE`. Prompt caching depends on that prefix staying byte-identical;
+`/status` shows context %, cache hit rate, a `prefix churn` warning if the prefix mutated mid-session
+(inspect with `--debug`, label `cache-prefix-drift`), and a compaction count. Long conversations are
+compacted automatically; `/compact` forces it. Inspect the whole frame with `/context` (tabbed:
+Environment / Memory / File State); `/context <path>` shows a file's current in-context lines.
+
+## Sessions
+Sessions auto-save. Resume the latest with `--resume` (or `--resume <UID>` for a specific one).
+
+## Providers, models, reasoning
+Configure `provider.*` per provider. `/reason` sets reasoning effort; `provider.max_tokens`,
+`provider.temperature`, and `provider.api` (auto/chat/anthropic) tune requests. `/strict` (or
+`provider.strict_tools`) constrains tool-call arguments to each tool's schema on hosts that support
+it (OpenAI, DeepSeek). Native thinking modes (DeepSeek/Qwen) drop `temperature` automatically.
+
+## MCP
+Configure external tools under `[mcp.<name>]` (either `url` or `command`). Manage with `/mcp`,
+`/mcp tools`, `/mcp refresh`, `/mcp login|logout`. Reference a server/tool inline with `@server.tool`
+to pull its schema into the turn. The `MCP` tool invokes them.
+
+## Skills
+Skills are reusable instruction packs under `.nanocode/skills/<name>/SKILL.md` (project) and
+`~/.nanocode/skills/<name>/SKILL.md` (user; project wins on name clash). The model loads one with
+`Skill(name)`; you can reference one inline with `$name` to load it for a turn. A skill-directory
+placeholder in the body expands to the skill's absolute folder so bundled scripts run via `Bash`.
+`/skills` lists them;
+the status bar and `/status` show the count. This manual is the built-in `nanocode-help` skill.
+
+## Safety
+Mutating actions (`Edit`, `Bash`, writing `Git`) ask for confirmation unless `/yolo` is on. nanocode
+will not switch, create, or delete git branches unless asked, and checks the branch before committing.
+
+## Troubleshooting
+- "missing config": set `provider.url`/`key`/`model` via `/set` or `config.toml`.
+- Slow or costly turns / low cache hit rate: check `/status`; a `prefix churn` warning means the
+  cached prefix changed mid-session — see the `--debug` cache-prefix-drift diff.
+- InspectCode unavailable or stale symbols: run `/index` to sync or rebuild the code index.
+- Context filling up: it compacts automatically; `/compact` forces it now.
+- A command typed while the agent works is refused unless it is read-only (`/help`, `/status`,
+  `/context`, `/skills`, read-only `/mcp`) or `/yolo`; press Ctrl-C to run others."""
+
+    def __init__(self, skills: dict[str, Skill]):
+        self.skills = skills
+
+    @classmethod
+    def load(cls, session: "Session") -> "SkillLibrary":
+        # Built-ins seed the library first; a user/project skill of the same name overrides them.
+        skills: dict[str, Skill] = {skill.name: skill for skill in cls.builtins()}
+        # User skills load before project skills so a project skill of the same name overrides them.
+        for root, source in ((session.data_path("skills"), "user"), (os.path.join(session.cwd, ".nanocode", "skills"), "project")):
+            if not os.path.isdir(root):
+                continue
+            for entry in sorted(os.listdir(root)):
+                skill = cls.parse(os.path.join(root, entry, "SKILL.md"), entry, source)
+                if skill is not None:
+                    skills[skill.name] = skill
+        return cls(skills)
+
+    @classmethod
+    def builtins(cls) -> list[Skill]:
+        """Skills shipped with nanocode itself. `nanocode-help` carries a self-contained reference so
+        the model answers questions about nanocode instantly, without searching the source. The body is
+        assembled at load time from the same in-code constants the app uses (`/help` text, tool
+        DESCRIPTIONs, settable keys), so it is fast to read yet cannot drift from the running version;
+        the raw source is named only as a fallback for anything the reference does not cover."""
+        source = os.path.abspath(__file__)
+        root = os.path.dirname(source)
+        tool_lines = [f"- {tool.NAME}: {tool.DESCRIPTION}" for tool in TOOLS]
+        sections = [
+            "Self-contained manual for answering questions about nanocode itself — how to use it, its",
+            "features, and common problems. Answer from the sections below; only fall back to reading the",
+            "source for details they do not cover. Cite exact command names, flags, and config keys.",
+            "",
+            cls.MANUAL,
+            "",
+            "## Commands, mentions, CLI, tools (verbatim /help)",
+            CommandLoop.HELP.strip(),
+            "",
+            "## Tool details",
+            *tool_lines,
+            "",
+            "## Settable config keys (/set KEY VALUE)",
+            ", ".join(CommandCompleter.SET_KEYS),
+        ]
+        if os.path.isfile(source):
+            sections += ["", "## Source (last-resort fallback)", f"For anything the manual does not cover, read `{source}` (README/CHANGELOG in `{root}` if present)."]
+        description = "Answer questions about nanocode itself — how to use it, its features, config, and common problems — from a bundled manual."
+        return [Skill("nanocode-help", description, "\n".join(sections), root, "builtin")]
+
+    @classmethod
+    def parse(cls, path: str, folder: str, source: str) -> "Skill | None":
+        try:
+            with open(path, encoding="utf-8") as handle:
+                text = handle.read()
+        except OSError:
+            return None
+        # Normalize BOM and CRLF/CR so the frontmatter regex (which keys on "\n") matches files
+        # authored on any platform; we only read two simple scalars, so this stays regex-light.
+        text = text.lstrip("").replace("\r\n", "\n").replace("\r", "\n")
+        match = cls.FRONTMATTER.match(text)
+        meta, body = (match.group(1), match.group(2)) if match else ("", text)
+        fields = {key: cls.scalar(value) for key, value in cls.META_LINE.findall(meta)}
+        name = fields.get("name") or folder.strip()
+        if not name:
+            return None
+        return Skill(name, fields.get("description", ""), body.strip(), os.path.dirname(path), source)
+
+    @staticmethod
+    def scalar(value: str) -> str:
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        return value.strip()
+
+    def all(self) -> list[Skill]:
+        return sorted(self.skills.values(), key=lambda skill: skill.name)
+
+    def get(self, name: str) -> "Skill | None":
+        if name in self.skills:
+            return self.skills[name]
+        resolved = {key.lower(): key for key in self.skills}.get(name.lower())
+        return self.skills.get(resolved) if resolved else None
+
+    def expand(self, skill: Skill) -> str:
+        return skill.body.replace("{skill_dir}", skill.dir).replace("${SKILL_DIR}", skill.dir)
+
+    def index(self) -> str:
+        if not self.skills:
+            return ""
+        rows = [f"- {skill.name}: {skill.description or '(no description)'}" for skill in self.all()]
+        return "\n".join(["--- SKILLS ---", "Use Skill(name) to load a skill's full instructions when its description fits the task.", "", *rows])
+
+    def resolve_mentions(self, text: str) -> str:
+        seen: set[str] = set()
+        blocks: list[str] = []
+        for raw in self.MENTION_PATTERN.findall(text):
+            skill = self.get(raw)
+            if skill is None or skill.name in seen:
+                continue
+            seen.add(skill.name)
+            blocks.append(f"[{skill.name}] {skill.description}\n{self.expand(skill)}")
+        if not blocks:
+            return ""
+        header = ["--- SKILL MENTIONS ---", "The user explicitly referenced these skills; follow their instructions unless clearly irrelevant.", ""]
+        return "\n".join(header + blocks).strip()
+
+
 @dataclass
 class Session:
     cwd: str = field(default_factory=os.getcwd)
@@ -1117,10 +1317,12 @@ class Session:
     usage: ModelUsage = field(default_factory=ModelUsage)
     update: UpdateStatus = field(default_factory=UpdateStatus)
     mcp: MCPManager | None = None
+    skills: SkillLibrary | None = None
     _gitignore_cache: dict[str, tuple[int, list[str]]] = field(default_factory=dict)
     uid: str = ""
     resumed: bool = False
     _snapshot_saved: dict = field(default_factory=dict)
+    _cache_prefix_text: str | None = None
 
     def __post_init__(self) -> None:
         if not self.uid:
@@ -1131,6 +1333,8 @@ class Session:
             self.expected_git_branch = self.git_branch(self.cwd)
         if self.mcp is None:
             self.mcp = MCPManager(self)
+        if self.skills is None:
+            self.skills = SkillLibrary.load(self)
 
     @classmethod
     def from_config_file(cls, *, path: str | None = None, yolo: bool = False, debug: bool = False, mcp_selector: str = "") -> "Session":
@@ -3235,8 +3439,38 @@ class MCPTool(Tool):
         )
 
 
+class SkillTool(Tool):
+    NAME = "Skill"
+    DESCRIPTION = "Load a skill's full instructions by name (skills are listed in the SKILLS section). Follow the returned steps, running any bundled scripts it references via Bash."
+    SIGNATURE = "Skill(name)"
+    EXAMPLE = ('Load a skill. Example: {"name":"release-notes"}',)
+
+    @classmethod
+    def params_schema(cls) -> Json:
+        return {
+            "type": "object",
+            "properties": {"name": {"type": "string", "description": "Skill name from the SKILLS section"}},
+            "required": ["name"],
+            "additionalProperties": False,
+        }
+
+    @classmethod
+    def payload_args(cls, payload: Json) -> list[Any]:
+        return [payload.get("name", "")]
+
+    def call(self) -> str:
+        (name,) = self.strings(min_count=1, max_count=1)
+        library = self.session.skills
+        skill = library.get(name) if library else None
+        if skill is None:
+            available = ", ".join(item.name for item in library.all()) if library else ""
+            raise ToolError(f"unknown skill {name!r}" + (f"; available: {available}" if available else "; no skills are installed"))
+        return f"<Skill name={json.dumps(skill.name)}>\n{library.expand(skill)}\n</Skill>"
+
+
 TOOLS: tuple[type[Tool], ...] = (
     MCPTool,
+    SkillTool,
     ReadTool,
     LineCountTool,
     ListTool,
@@ -3267,6 +3501,7 @@ class ContextManager:
     COMPACT_TITLE: ClassVar[str] = "--- Prior Conversation Summary (compacted) ---"
     COMPACT_RECENT_MESSAGES: ClassVar[int] = 8
     MCP_DESCRIBE_BLOCK: ClassVar[re.Pattern] = re.compile(r"<MCPDescribe server=(\".*?\") tool=(\".*?\")>.*?</MCPDescribe>", re.DOTALL)
+    SKILL_BLOCK: ClassVar[re.Pattern] = re.compile(r"<Skill name=(\".*?\")>.*?</Skill>", re.DOTALL)
     CODE_EXTENSIONS: ClassVar[set[str]] = set(
         ".c .cc .cpp .cxx .css .go .h .hpp .html .java .js .json .jsx .kt .lua .php .py .rb .rs .scss .sh .sql .swift .toml .ts .tsx .vue .yaml .yml".split()
     )
@@ -3291,6 +3526,7 @@ class ContextManager:
 
     def model_messages(self, base_system: str, turn_messages: list[Json] | None = None) -> list[Json]:
         file_context = self.file_context() or "(empty)"
+        skills_index = self.skills_context()
         mcp_tools = self.mcp_tools_context()
 
         messages: list[Json] = [
@@ -3298,10 +3534,12 @@ class ContextManager:
             {"role": "user", "content": "--- Environment ---\n" + (self.environment() or "(empty)")},
         ]
 
+        if skills_index:
+            messages.append({"role": "user", "content": skills_index})
         if mcp_tools:
             messages.append({"role": "user", "content": mcp_tools})
 
-        messages.extend(self.dedup_mcp_describes([*self.session.messages, *(turn_messages or [])]))
+        messages.extend(self.dedup_skill_loads(self.dedup_mcp_describes([*self.session.messages, *(turn_messages or [])])))
         messages.append({"role": "user", "content": "--- Memory ---\n" + (self.memory_context(with_date=True) or "(empty)")})
         messages.append({"role": "user", "content": "--- FILE STATE ---\n" + file_context})
         return Text.value(messages)
@@ -3341,11 +3579,90 @@ class ContextManager:
             result.append({**message, "content": self.MCP_DESCRIBE_BLOCK.sub(lambda _: marker, content)})
         return result
 
+    def dedup_skill_loads(self, messages: list[Json]) -> list[Json]:
+        """Collapse repeated Skill(name) loads to a pointer, keeping the first full body per skill.
+
+        Same send-time transform as dedup_mcp_describes: a re-load of an already-shown skill shrinks to
+        a one-line marker so the instructions are not re-billed, while the first (cached) copy is left
+        untouched. If that first copy is later compacted away, the next occurrence stands on its own."""
+        seen: dict[str, str] = {}
+        result: list[Json] = []
+        for message in messages:
+            content = message.get("content")
+            if message.get("role") != "tool" or not isinstance(content, str):
+                result.append(message)
+                continue
+            match = self.SKILL_BLOCK.search(content)
+            if match is None:
+                result.append(message)
+                continue
+            try:
+                name = str(json.loads(match.group(1)))
+            except (json.JSONDecodeError, ValueError):
+                result.append(message)
+                continue
+            first_key = seen.get(name)
+            if first_key is None:
+                key = re.search(r"\btr\.\d+\b", content)
+                seen[name] = key.group(0) if key else "above"
+                result.append(message)
+                continue
+            marker = f"(repeat load of skill {name}; instructions shown earlier at {first_key}, unchanged)"
+            result.append({**message, "content": self.SKILL_BLOCK.sub(lambda _: marker, content)})
+        return result
+
     def mcp_tools_context(self) -> str:
         if self.session.mcp is None:
             return ""
         return self.session.mcp.render_tools_index()
 
+    def skills_context(self) -> str:
+        return self.session.skills.index() if self.session.skills else ""
+
+    def has_skills(self) -> bool:
+        return bool(self.session.skills and self.session.skills.skills)
+
+    def cache_prefix(self, base_system: str, tools: list[Json] | None) -> str:
+        # Canonical text of the bytes a provider can cache: the stable head of every request.
+        # Mirrors the leading blocks model_messages() emits (system + environment + mcp index)
+        # plus the tool schemas. Everything mutable (history, memory, FILE STATE) sits after it.
+        return "\x00".join(
+            [
+                base_system.strip(),
+                "--- Environment ---\n" + (self.environment() or "(empty)"),
+                self.skills_context(),
+                self.mcp_tools_context() or "",
+                json.dumps(tools or [], ensure_ascii=False, sort_keys=True, separators=(",", ":")),
+            ]
+        )
+
+    def tool_schemas(self) -> list[Json]:
+        strict = self.session.config.provider.resolved_strict_tools()
+        # The Skill tool only appears when at least one skill is installed, so a skill-free session
+        # keeps a byte-identical prefix to before skills existed.
+        return [tool.schema(strict) for tool in TOOL_REGISTRY.values() if tool is not SkillTool or self.has_skills()]
+
+    def check_cache_prefix(self, base_system: str) -> None:
+        # Tripwire for silent cache breakage: fingerprint the stable prefix and flag drift.
+        # A healthy session keeps one fingerprint start to finish; a second one means the prefix
+        # mutated mid-session and every token from the change onward is a cache miss.
+        text = self.cache_prefix(base_system, self.tool_schemas())
+        fingerprint = hashlib.sha256(text.encode("utf-8")).hexdigest()
+        state = self.session.state
+        if fingerprint in state.prefix_fingerprints:
+            self.session._cache_prefix_text = text
+            return
+        previous = self.session._cache_prefix_text
+        if state.prefix_fingerprint and previous is not None:
+            diff = "\n".join(
+                list(difflib.unified_diff(previous.splitlines(), text.splitlines(), "cached-prefix", "current-prefix", lineterm=""))[:40]
+            )
+            DebugTrace.cache_drift(self.session, expected=state.prefix_fingerprint, actual=fingerprint, diff=diff)
+        if not state.prefix_fingerprint:
+            state.prefix_fingerprint = fingerprint
+        state.prefix_fingerprints.append(fingerprint)
+        self.session._cache_prefix_text = text
+
     def update_percent(self, messages: list[Json]) -> int:
         tokens = self.estimated_tokens(messages)
         self.session.state.context_percent = min(100, tokens * 100 // self.session.settings.max_context_tokens)
@@ -3402,6 +3719,106 @@ class ContextManager:
         lines_by_path, omitted = self.active_file_lines()
         return self.render_file_lines(lines_by_path, omitted)
 
+    def context_overview(self) -> str:
+        """Markdown view of the synthesized context frame the model receives each turn:
+        the Environment, Memory, and File State sections (the live transcript is excluded)."""
+        lines_by_path, omitted = self.active_file_lines()
+        paths = sorted(path for path in lines_by_path if lines_by_path[path])
+        total_lines = sum(len(lines_by_path[path]) for path in paths)
+        header = f"### Context  ·  ctx `{self.session.state.context_percent}%` · {len(paths)} files · {total_lines} lines"
+        return "\n\n".join([header, self.environment_md(), self.memory_md(), self.files_overview((lines_by_path, omitted))])
+
+    @staticmethod
+    def md_table(headers: list[str], rows: list[tuple]) -> str:
+        def cell(value: object) -> str:
+            return Text.clean(str(value)).replace("\n", " ").replace("|", "\\|")
+
+        return "\n".join(
+            [
+                "| " + " | ".join(headers) + " |",
+                "| " + " | ".join("---" for _ in headers) + " |",
+                *("| " + " | ".join(cell(value) for value in row) + " |" for row in rows),
+            ]
+        )
+
+    def environment_md(self) -> str:
+        info = self.session.system_info
+        rows = [
+            ("cwd", "`" + info.cwd + "`"),
+            ("os", f"{info.os} · {info.arch}"),
+            ("shell timeout", f"{self.session.settings.shell_timeout}s"),
+            ("commands", ", ".join(info.commands) or "(none)"),
+        ]
+        if branch := self.session.git_branch(self.session.cwd):
+            rows.append(("git", "`" + branch + "`"))
+        return "#### Environment\n" + self.md_table(["key", "value"], rows)
+
+    def memory_md(self) -> str:
+        state = self.session.state
+        index_status = state.code_index_status or "missing"
+        index_usable = "yes" if index_status in {"synced", "ready", "stale"} else "no"
+        rows = [
+            ("goal", state.goal or "(empty)"),
+            ("check", state.check or "(empty)"),
+            ("index", f"{index_status} (usable: {index_usable})"),
+        ]
+        known = "\n".join("- " + item for item in state.known) or "- (empty)"
+        return "\n\n".join(
+            [
+                "#### Memory\n" + self.md_table(["field", "value"], rows),
+                "**Plan**\n" + "\n".join(AgentState.plan_rows_for(state.plan, status=True, style="symbol")),
+                "**Known**\n" + known,
+            ]
+        )
+
+    def files_overview(self, precomputed: tuple[dict, dict] | None = None) -> str:
+        """Markdown summary of the FILE STATE section: which files/ranges are current, recent
+        events, and omissions, without dumping the full anchored content."""
+        lines_by_path, omitted = precomputed if precomputed is not None else self.active_file_lines()
+        paths = sorted(path for path in lines_by_path if lines_by_path[path])
+        state = self.session.state
+        focus = state.focus_text(state.plan)
+        actions, code_edits, errors = self.recent_file_actions(), self.recent_code_edits(), self.recent_tool_errors()
+        check_status = self.check_status(code_edits)
+        if not (paths or omitted or focus or actions or code_edits or check_status or errors):
+            return "#### File State\n(no files in context)"
+        chunks = ["#### File State" + (f"  ·  focus: {focus}" if focus else "")]
+        if paths:
+            rows = [
+                (f"`{path}`", ", ".join(f"{start}:{end}" for start, end in self.coverage(lines_by_path[path])), len(lines_by_path[path]), self.latest_source(lines_by_path[path]))
+                for path in paths
+            ]
+            chunks.append(self.md_table(["file", "ranges", "lines", "source"], rows))
+        for label, items in (("Recent events", actions), ("Recent code edits", code_edits), ("Check status", check_status), ("Recent tool errors", errors)):
+            if items:
+                chunks.append(f"**{label}**\n" + "\n".join(items))
+        if omitted:
+            omit_rows = [f"- `{path}` source={source} lines={count}" for path in sorted(omitted) for source, count in sorted(omitted[path].items())]
+            chunks.append("**Omitted** (stale/superseded)\n" + "\n".join(omit_rows))
+        return "\n\n".join(chunks)
+
+    @staticmethod
+    def latest_source(numbered: dict[int, tuple[str, str, str]]) -> str:
+        source, tool, _line = max(numbered.values(), key=lambda value: int(value[0][3:]) if value[0].startswith("tr.") and value[0][3:].isdigit() else -1)
+        return f"{source} {tool}".strip()
+
+    def file_detail(self, path: str) -> str:
+        """Full current anchored content for one in-context file, exactly as the model sees it,
+        wrapped in a fenced block so it renders monospace and unwrapped."""
+        lines_by_path, _ = self.active_file_lines()
+        available = sorted(candidate for candidate in lines_by_path if lines_by_path[candidate])
+        matches = [candidate for candidate in available if candidate == path or os.path.basename(candidate) == path or candidate.endswith("/" + path)]
+        match = matches[0] if len(matches) == 1 else (path if path in available else None)
+        if match is None:
+            listing = "\n".join("- `" + candidate + "`" for candidate in available) or "(none)"
+            return f"No in-context content for `{path}`.\n\n**Files in context**\n{listing}"
+        numbered = lines_by_path[match]
+        body: list[str] = []
+        for start, end, source, tool, segment_lines in self.segments(numbered):
+            body.append(f"@@ {start}:{end}  {source} {tool}")
+            body.extend(segment_lines)
+        return f"**{match}** — current, {len(numbered)} lines\n\n```\n" + "\n".join(body) + "\n```"
+
     def active_file_lines(self) -> tuple[dict[str, dict[int, tuple[str, str, str]]], dict[str, dict[str, int]]]:
         lines_by_path: dict[str, dict[int, tuple[str, str, str]]] = {}
         omitted: dict[str, dict[str, int]] = {}
@@ -3616,18 +4033,21 @@ class ContextManager:
         return "\n\n".join(f"{message.get('role', 'message')}:\n{message.get('content') or ''}" for message in messages) or "(empty)"
 
     def apply_compaction(self, data: Json, keep: list[Json], tool_messages: list[Json] | None = None) -> None:
+        self.session.state.compaction_count += 1
         self.session.state.apply(data)
         summary = self.session.state.summary
         self.session.messages = ([{"role": "user", "content": self.COMPACT_TITLE + "\n" + summary}] if summary else []) + keep
         self.prune_tool_records([*self.session.messages, *(tool_messages or [])])
 
     def apply_compaction_fallback(self, keep: list[Json], tool_messages: list[Json] | None = None) -> None:
+        self.session.state.compaction_count += 1
         self.session.state.summary = (self.session.state.summary + "\nPrevious context was deterministically trimmed.").strip()
         summary = self.session.state.summary
         self.session.messages = ([{"role": "user", "content": self.COMPACT_TITLE + "\n" + summary}] if summary else []) + keep
         self.prune_tool_records([*keep, *(tool_messages or [])])
 
     def apply_turn_compaction(self, data: Json, keep: list[Json], turn_messages: list[Json]) -> None:
+        self.session.state.compaction_count += 1
         self.session.state.apply(data)
         summary = self.session.state.summary
         index = self.latest_user_index(keep)
@@ -5390,6 +5810,10 @@ class DebugTrace:
         payload = {"api": api, "model": model, "error": str(error), "param_keys": sorted(params), "params": cls.filtered_params(params)}
         cls.write(session, activity=activity, label="model-error", payload=payload)
 
+    @classmethod
+    def cache_drift(cls, session: Session, *, expected: str, actual: str, diff: str) -> None:
+        cls.write(session, activity="agent", label="cache-prefix-drift", payload={"expected": expected, "actual": actual, "diff": diff})
+
     @staticmethod
     def filtered_params(params: Json) -> Json:
         return {key: value for key, value in params.items() if key not in {"messages", "tools"}}
@@ -5406,11 +5830,18 @@ class ModelClient:
     def __init__(self, session: Session):
         self.session = session
 
+    def tool_schemas(self) -> list[Json]:
+        provider = self.session.config.provider
+        # Keep in lockstep with ContextManager.tool_schemas: the Skill tool is only offered when a
+        # skill is installed, so the sent tools match the cache-prefix fingerprint.
+        has_skills = bool(self.session.skills and self.session.skills.skills)
+        return [tool.schema(provider.resolved_strict_tools()) for tool in TOOL_REGISTRY.values() if tool is not SkillTool or has_skills]
+
     def request(self, messages: list[Json]) -> tuple[Json, list[ToolCall], str]:
         provider = self.session.config.provider
         if missing := self.session.missing_config():
             raise ModelError("missing config: " + ", ".join(missing))
-        tools = [tool.schema(provider.resolved_strict_tools()) for tool in TOOL_REGISTRY.values()]
+        tools = self.tool_schemas()
         for attempt in range(MODEL_REQUEST_RETRIES + 1):
             self.session.state.current_model_call_started_at = time.monotonic()
             try:
@@ -5825,6 +6256,10 @@ FINAL:
             mentions = self.session.mcp.resolve_mentions(user_input)
             if mentions:
                 turn_messages.append({"role": "user", "content": mentions})
+        if self.session.skills is not None:
+            skill_mentions = self.session.skills.resolve_mentions(user_input)
+            if skill_mentions:
+                turn_messages.append({"role": "user", "content": skill_mentions})
         for step in range(self.session.settings.max_steps):
             self.session.state.turn_step = step + 1
             while True:
@@ -5859,6 +6294,7 @@ FINAL:
         self.session.state.turn_messages = len(request_turn)
         self.context.maybe_compact(self.model, self.SYSTEM_PROMPT, request_turn)
         messages = self.context.model_messages(self.SYSTEM_PROMPT, request_turn)
+        self.context.check_cache_prefix(self.SYSTEM_PROMPT)
         self.context.update_percent(messages)
         return messages, pending
 
@@ -5891,7 +6327,8 @@ class CommandCompleter(Completer):
     COMMANDS = (
         "/help",
         "/status",
-        "/memory",
+        "/context",
+        "/skills",
         "/config",
         "/api",
         "/debug",
@@ -5946,12 +6383,14 @@ class CommandCompleter(Completer):
         mcp_servers: Callable[[], tuple[str, ...]] = tuple,
         mcp_oauth_servers: Callable[[], tuple[str, ...]] = tuple,
         mcp_tools: Callable[[str], tuple[str, ...]] = lambda _server: (),
+        skills: Callable[[], tuple[str, ...]] = tuple,
     ):
         self.providers = providers
         self.models = models
         self.mcp_servers = mcp_servers
         self.mcp_oauth_servers = mcp_oauth_servers
         self.mcp_tools = mcp_tools
+        self.skills = skills
 
     def get_completions(self, document, complete_event):
         text = document.text_before_cursor
@@ -5995,6 +6434,11 @@ class CommandCompleter(Completer):
                 yield from self.matches(self.mcp_servers(), server_part)
             return
 
+        skill_match = re.search(r"(?<![A-Za-z0-9_])\$([A-Za-z0-9_-]*)$", text)
+        if skill_match:
+            yield from self.matches(self.skills(), skill_match.group(1))
+            return
+
         if text.startswith("/") and " " not in text:
             yield from self.matches(self.COMMANDS, text)
 
@@ -6450,6 +6894,9 @@ class StatusBar:
         mcp_status = self.mcp_status()
         if mcp_status:
             parts.append((mcp_status, "mcp"))
+        skill_count = len(self.session.skills.skills) if self.session.skills else 0
+        if skill_count:
+            parts.append((f"skills {skill_count}", "mcp"))
         parts.append(("ctx " + str(self.session.state.context_percent) + "%", "ctx"))
         if self.session.settings.debug and self.session.usage.cached_prompt_tokens:
             parts.append(("cache " + str(self.session.usage.cached_prompt_tokens), "debug"))
@@ -6549,7 +6996,7 @@ class StatusBar:
 class CommandLoop:
     # Commands safe to run from the background queue-input thread while the agent works: read-only
     # views plus /yolo, whose single atomic flag flip the agent simply reads at the next approval.
-    QUEUE_RUN_COMMANDS: ClassVar[frozenset[str]] = frozenset({"/help", "/status", "/memory", "/mcp", "/yolo"})
+    QUEUE_RUN_COMMANDS: ClassVar[frozenset[str]] = frozenset({"/help", "/status", "/context", "/skills", "/mcp", "/yolo"})
     MODEL_CONFIGURED_LABEL = "---- Configured models ----"
     MODEL_DISCOVERED_LABEL = "---- Discovered models ----"
     MODEL_LABELS = frozenset((MODEL_CONFIGURED_LABEL, MODEL_DISCOVERED_LABEL))
@@ -6570,7 +7017,7 @@ class CommandLoop:
         (ALWAYS, "Tab completes commands, file paths, and mentions."),
         # Context & memory
         (ALWAYS, "`/compact` summarizes a long conversation to reclaim context."),
-        (ALWAYS, "`/memory` shows the agent's current goal, plan, and known facts."),
+        (ALWAYS, "`/context` shows the model's context frame: environment, memory (goal/plan/known), and file state."),
         (ALWAYS, "`/status` shows token usage, context %, and prompt-cache hit rate."),
         (ALWAYS, "Stable context is kept early so the prompt cache is reused — cheaper, faster turns."),
         # Model & reasoning
@@ -6604,7 +7051,8 @@ class CommandLoop:
     HELP = """Commands:
   /help              Show this help.
   /status            Show runtime status.
-  /memory            Show durable agent memory.
+  /context [PATH]    Show the model's context frame (environment, memory, file state); PATH shows that file's current lines.
+  /skills            List installed skills (load with Skill(name) or reference inline with $name).
   /config            Show active config.
   /api [NAME]        Show or set provider API format: auto, chat, anthropic.
   /debug [on|off]    Toggle model I/O debug traces.
@@ -6624,11 +7072,13 @@ class CommandLoop:
   /exit, /quit       Exit.
 Mentions:
   @server[.tool]     Point the agent at an MCP server/tool in your message (tab-completes).
+  $skill             Reference a skill in your message to load its instructions for that turn (tab-completes).
 CLI:
   --mcp "orion*,!orionEval"  Select MCP servers by name glob; use all or none.
   --resume [UID]             Resume a saved session; defaults to latest (last also works).
 Tools:
-  Read, LineCount, List, Find, InspectCode, Search, Edit, Bash, Git, Recall, Note, Question, MCP.
+  Read, LineCount, List, Find, InspectCode, Search, Edit, Bash, Git, Recall, Note, Question, MCP, Skill.
+  Skill(name) loads a skill's full instructions on demand (see the SKILLS section / $skill).
 """
 
     def __init__(self, agent: Agent, input_fn=input, output_fn=print):
@@ -6659,6 +7109,7 @@ Tools:
             mcp_servers=lambda: tuple(config.name for config in self.session.mcp.parse_configs() if config.enabled),
             mcp_oauth_servers=lambda: tuple(config.name for config in self.session.mcp.parse_configs() if config.enabled and config.auth == "oauth"),
             mcp_tools=lambda server: self.session.mcp.server_tool_names(server),
+            skills=lambda: tuple(skill.name for skill in self.session.skills.all()) if self.session.skills else (),
         )
         self.agent.output_fn = self.agent_output
         self.agent.tools.output_fn = self.tool_output
@@ -6998,6 +7449,8 @@ Tools:
                 "choice.selected": "reverse",
                 "choice.disabled": "ansibrightblack",
                 "choice.preview": "ansigreen italic",
+                "tab.active": "bold reverse ansicyan",
+                "tab.inactive": "ansicyan",
                 "completion-menu": "noreverse bg:default",
                 "completion-menu.completion": "noreverse bg:default fg:ansiwhite",
                 "completion-menu.completion.current": "noreverse bg:default fg:ansicyan bold",
@@ -7301,7 +7754,8 @@ Tools:
         handlers = {
             "/help": self.help,
             "/status": self.status,
-            "/memory": self.memory,
+            "/context": self.context_view,
+            "/skills": self.skills_command,
             "/config": self.config,
             "/api": self.api,
             "/debug": self.debug,
@@ -7317,7 +7771,9 @@ Tools:
         }
         handler = handlers.get(name)
         output = handler(args.strip()) if handler else f"Unknown command: {name}"
-        (self.ui.emit_answer if name in {"/status", "/mcp"} else self.emit)(output)
+        # A None result means the handler already rendered its own UI (e.g. /context's tab viewer).
+        if output is not None:
+            (self.ui.emit_answer if name in {"/status", "/mcp", "/context", "/skills"} else self.emit)(output)
         return True, False
 
     def mcp_command(self, args: str) -> str:
@@ -7630,12 +8086,13 @@ Tools:
             ),
             (
                 "context",
-                f"ctx `{self.session.state.context_percent}%`; history `{len(self.session.messages)}`; turn `{self.session.state.turn_messages}`; tools `{len(self.session.tool_results)}`; files `{self.agent.context.file_count()}`; known `{len(self.session.state.known)}`",
+                f"ctx `{self.session.state.context_percent}%`; history `{len(self.session.messages)}`; turn `{self.session.state.turn_messages}`; tools `{len(self.session.tool_results)}`; files `{self.agent.context.file_count()}`; skills `{len(self.session.skills.skills) if self.session.skills else 0}`; known `{len(self.session.state.known)}`; compactions `{self.session.state.compaction_count}`",
             ),
             ("goal", self.session.state.goal or "(empty)"),
             (
                 "usage",
-                f"calls `{usage.calls}`; total `{usage.total_tokens}`; cached `{usage.cached_prompt_tokens}/{usage.prompt_tokens}` (`{cache_ratio:.1f}%`); last `{usage.last_cached_prompt_tokens}/{usage.last_prompt_tokens}` (`{last_cache_ratio:.1f}%`)",
+                f"calls `{usage.calls}`; total `{usage.total_tokens}`; cached `{usage.cached_prompt_tokens}/{usage.prompt_tokens}` (`{cache_ratio:.1f}%`); last `{usage.last_cached_prompt_tokens}/{usage.last_prompt_tokens}` (`{last_cache_ratio:.1f}%`)"
+                + (f"; ⚠ prefix churn `{len(set(self.session.state.prefix_fingerprints))}` (cache broken; see debug cache-prefix-drift)" if len(set(self.session.state.prefix_fingerprints)) > 1 else ""),
             ),
             (
                 "runtime",
@@ -7652,20 +8109,116 @@ Tools:
             ]
         )
 
-    def memory(self, args: str) -> str:
-        state = self.session.state
-        known = ["- " + item for item in state.known] or ["- (empty)"]
-        return "\n".join(
-            [
-                "goal: " + (state.goal or "(empty)"),
-                "summary:",
-                state.summary or "(empty)",
-                "plan:",
-                *AgentState.plan_rows_for(state.plan, status=True, style="symbol"),
-                "known:",
-                *known,
-            ]
+    def skills_command(self, args: str) -> str:
+        library = self.session.skills
+        skills = library.all() if library else []
+        if not skills:
+            return "No skills installed. Add `<name>/SKILL.md` under `.nanocode/skills/` (project) or `~/.nanocode/skills/` (user)."
+        table = ContextManager.md_table(
+            ["skill", "source", "description"],
+            [(f"`{skill.name}`", skill.source, skill.description or "(no description)") for skill in skills],
         )
+        return "\n".join([f"### Skills · {len(skills)}", "", "Load with `Skill(name)` or reference inline with `$name`.", "", table])
+
+    def context_view(self, args: str) -> str | None:
+        context = self.agent.context
+        if args:
+            return context.file_detail(args)
+        context.update_percent(context.model_messages(self.agent.SYSTEM_PROMPT))
+        # At the idle prompt on a real terminal, open the interactive tabbed viewer; while the agent
+        # is working (queue path sets capture_ansi) or without a TTY, fall back to the static dump.
+        if self.interactive_input and self.ui.color and not self.ui.capture_ansi:
+            self.context_tabs(context)
+            return None
+        return context.context_overview()
+
+    CONTEXT_TABS: ClassVar[tuple[tuple[str, str], ...]] = (("Environment", "environment_md"), ("Memory", "memory_md"), ("File State", "files_overview"))
+
+    def context_tabs(self, context: "ContextManager") -> None:
+        """Interactive tabbed viewer for the context frame: ←/→ switch tabs, ↑/↓ scroll, Esc close.
+        Renders a static snapshot; the transcript continues below once closed."""
+        width = max(20, shutil.get_terminal_size().columns - 2)
+        pages = [self.render_markdown_lines(getattr(context, method)(), width) for _, method in self.CONTEXT_TABS]
+        state = self.context_tab_state = {"tab": 0, "scroll": 0}
+
+        def viewport() -> int:
+            return max(3, shutil.get_terminal_size().lines - 5)
+
+        def fragments():
+            # Blank line separates the viewer from the `nano> /context` input line above it.
+            parts: list[tuple[str, str]] = [("", "\n")]
+            for index, (name, _) in enumerate(self.CONTEXT_TABS):
+                active = index == state["tab"]
+                parts.append(("class:tab.active" if active else "class:tab.inactive", f" {name} "))
+                if index < len(self.CONTEXT_TABS) - 1:
+                    parts.append(("class:choice.disabled", " │ "))
+            lines = pages[state["tab"]]
+            height = viewport()
+            scrollable = len(lines) > height
+            state["scroll"] = min(max(0, int(state["scroll"])), max(0, len(lines) - height))
+            visible = lines[state["scroll"] : state["scroll"] + height]
+            parts.append(("", "\n"))
+            scroll_hint = "↑/↓ scroll" if scrollable else "↑/↓ scroll (fits)"
+            parts.append(("class:choice.disabled", f"  ←/→ switch · {scroll_hint} · Esc close  [{state['scroll'] + 1}-{state['scroll'] + len(visible)}/{len(lines)}]\n"))
+            for line in visible:
+                parts.extend(line)
+                parts.append(("", "\n"))
+            return parts
+
+        def scroll(event, delta: int) -> None:
+            state["scroll"] = max(0, int(state["scroll"]) + delta)
+            event.app.invalidate()
+
+        def switch(event, delta: int) -> None:
+            state["tab"] = (int(state["tab"]) + delta) % len(self.CONTEXT_TABS)
+            state["scroll"] = 0
+            event.app.invalidate()
+
+        bindings = KeyBindings()
+        bindings.add("right", eager=True)(lambda event: switch(event, 1))
+        bindings.add("l", eager=True)(lambda event: switch(event, 1))
+        bindings.add("left", eager=True)(lambda event: switch(event, -1))
+        bindings.add("h", eager=True)(lambda event: switch(event, -1))
+        bindings.add("tab", eager=True)(lambda event: switch(event, 1))
+        bindings.add("down", eager=True)(lambda event: scroll(event, 1))
+        bindings.add("j", eager=True)(lambda event: scroll(event, 1))
+        bindings.add("up", eager=True)(lambda event: scroll(event, -1))
+        bindings.add("k", eager=True)(lambda event: scroll(event, -1))
+        bindings.add("pagedown", eager=True)(lambda event: scroll(event, viewport()))
+        bindings.add("pageup", eager=True)(lambda event: scroll(event, -viewport()))
+
+        for number in range(1, len(self.CONTEXT_TABS) + 1):
+
+            @bindings.add(str(number), eager=True)
+            def _jump(event, number=number):
+                state["tab"] = number - 1
+                state["scroll"] = 0
+                event.app.invalidate()
+
+        @bindings.add("escape", eager=True)
+        @bindings.add("q", eager=True)
+        @bindings.add("c-c", eager=True)
+        @bindings.add("<sigint>", eager=True)
+        def _close(event):
+            event.app.exit(result=None)
+
+        content = FormattedTextControl(fragments, focusable=True)
+        window = Window(content, dont_extend_height=True, wrap_lines=False)
+        app = self._make_app(Layout(HSplit([window, self.status_window()]), focused_element=window), bindings)
+        try:
+            self.run_input_app(app)
+        except KeyboardInterrupt:
+            pass
+
+    def render_markdown_lines(self, markdown: str, width: int) -> list[Any]:
+        """Render Markdown to per-line prompt_toolkit fragments via Rich, so the tab body keeps its
+        table/heading styling inside the interactive viewer."""
+        if not self.ui.color:
+            return [[("", line)] for line in markdown.splitlines()]
+        console = Console(force_terminal=True, width=width)
+        with console.capture() as capture:
+            console.print(Markdown(markdown))
+        return [to_formatted_text(ANSI(line)) for line in capture.get().splitlines()]
 
     def config(self, args: str) -> str:
         provider = self.session.config.provider

{nanocode_cli-0.7.2 → nanocode_cli-0.8.0/nanocode_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nanocode-cli
-Version: 0.7.2
+Version: 0.8.0
 Summary: A small terminal coding agent written in Python
 Author-email: hit9 <hit9@icloud.com>
 License-Expression: BSD-3-Clause
@@ -131,6 +131,8 @@ Commands:
 
 - `/help`: show commands and tools.
 - `/status`: show runtime status, including the active session id.
+- `/context [PATH]`: show the model's context frame — environment, memory (goal, plan, known facts, check), and file state; `PATH` shows that file's current in-context lines.
+- `/skills`: list installed skills (load with `Skill(name)` or reference inline with `$name`).
 - `/config`: show active config.
 - `/api [auto|chat|anthropic]`: show or set provider API format.
 - `/debug [on|off]`: toggle model I/O debug traces.
@@ -140,6 +142,7 @@ Commands:
 - `/provider [NAME]`: show or set provider.
 - `/model [MODEL]`: show or set model.
 - `/reason`: choose reasoning effort.
+- `/strict`: toggle strict tool-call schemas (OpenAI / DeepSeek only).
 - `/set KEY VALUE`: set supported provider/runtime values for the current session.
 - `/yolo`: toggle tool confirmations.
 - `/exit`, `/quit`: exit.
@@ -156,6 +159,7 @@ Tools:
 - Working notes: `Note`.
 - Ask the user: `Question`.
 - MCP: `MCP`.
+- Skills: `Skill` loads a skill's full instructions on demand (offered whenever any skill exists — the built-in `nanocode-help` means it is normally always available).
 
 `Read`, `Search`, and `InspectCode` return line anchors where useful. `Edit` uses current `line:hash` anchors to reject stale edits.
 
@@ -170,12 +174,14 @@ Default config location:
 Main fields:
 
 - `[provider] active = "name"`
-- `[provider.<name>]`: `url`, `key`, `model`, `api`, `prompt_cache_key`, `available_models`, `reasoning`, `chat_reasoning`, `temperature`, `timeout`
+- `[provider.<name>]`: `url`, `key`, `model`, `api`, `prompt_cache_key`, `available_models`, `reasoning`, `chat_reasoning`, `temperature`, `max_tokens`, `strict_tools`, `timeout`
 - `[paths] data_dir`
-- `[runtime] shell_timeout`, `max_agent_steps`, `max_context_tokens`, `check_updates`, `update_check_interval_hours`, `session_retention_days`, `yolo`, `debug`
+- `[runtime] shell_timeout`, `max_agent_steps`, `max_context_tokens`, `max_parallel_tools`, `check_updates`, `update_check_interval_hours`, `session_retention_days`, `yolo`, `debug`, `tips`
 
 `api = "auto"` chooses between Chat Completions and Anthropic Messages using provider/model profiles. `prompt_cache_key = "auto"` derives a stable key from provider, model, workspace, and tool schema names.
 
+`strict_tools = true` (toggle with `/strict`) constrains tool-call arguments to each tool's JSON schema. It only takes effect on hosts that support it (OpenAI and DeepSeek) and on the Chat Completions path; it is a no-op elsewhere. For DeepSeek, enabling it routes requests to the `/beta` endpoint. Tools whose schemas can't be represented under strict function calling fall back to non-strict automatically.
+
 Runtime flags such as `--yolo`, `--debug`, and `--mcp` apply to resumed sessions too. Saved sessions do not carry their old runtime config forward.
 
 ## MCP
@@ -215,6 +221,37 @@ Manage servers at runtime:
 - `/mcp refresh [server]`: rediscover servers.
 - `/mcp login <server>` / `/mcp logout <server>`: OAuth login and logout.
 
+## Skills
+
+Skills are reusable instruction packs the agent can pull in on demand. Each skill is a folder with a `SKILL.md`:
+
+```text
+.nanocode/skills/                 # project skills (travel with the repo)
+  release-notes/
+    SKILL.md
+    scripts/
+      collect_commits.py
+~/.nanocode/skills/               # personal skills (all projects)
+```
+
+`SKILL.md` has `name`/`description` frontmatter and a Markdown body of instructions:
+
+```markdown
+---
+name: release-notes
+description: Draft a CHANGELOG entry from commits since the last release.
+---
+Run `python "{skill_dir}/scripts/collect_commits.py" <last-tag>` to gather commits,
+then group them by type and write entries in the house style.
+```
+
+- **Discovery**: `.nanocode/skills/` (project) and `~/.nanocode/skills/` (user). On a name clash the project skill wins.
+- **How the model sees them**: only a compact `SKILLS` index (name + description) sits in context; the full body is loaded on demand when the model calls `Skill(name)`. A repeated load of the same skill collapses to a pointer so the instructions are not re-billed. When no skills are installed, nothing is added to the prompt.
+- **Reference one inline**: type `$name` in your message (Tab-completes) to nudge the model to use that skill; its instructions are injected for that turn.
+- **Bundled scripts**: `{skill_dir}` (or `${SKILL_DIR}`) in the body expands to the skill's absolute folder path, so the model can run bundled scripts via `Bash` (subject to normal confirmation unless `/yolo`).
+- **Inspect**: `/skills` lists installed skills; the status bar and `/status` show the count.
+- **Built-in**: a `nanocode-help` skill ships by default and carries a self-contained manual — authored prose on how to use nanocode, its features, and common problems, plus command/tool/config lists assembled from nanocode's own `/help` text, tool descriptions, and config keys. So "how do I / what does X / why is Y" questions are answered from the manual without searching the source, and the lists can't drift from the running version. Drop a `nanocode-help` skill of your own to override it.
+
 ## Providers
 
 The following providers have been tested with nanocode:

{nanocode_cli-0.7.2 → nanocode_cli-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nanocode-cli"
-version = "0.7.2"
+version = "0.8.0"
 description = "A small terminal coding agent written in Python"
 readme = "README.md"
 requires-python = ">=3.11"