test(skills): preserve native Pi loading and session lifecycle

README.md

@@ -86,6 +86,10 @@ OpenPI 会把长期进程放到后台，把独立任务交给隔离 Context 的
 > `/plan` 是一个运行时安全例外：进入或恢复 Plan Mode 时会为当前 Session 自动加载 `search` 组，让只读调研直接使用结构化 Git 工具。
 > 在交互输入框中，保留词 `Subagent` / `Workflow`，以及已被识别的中文能力请求，会使用 Claude Code 风格的薰衣草紫显示；浅色终端自动使用更深的紫色以维持可读性。变色表示提交后会加载对应能力。因为英文名称本身就是授权词，讨论中写出它们也会开闸；条件句和否定句仍保持普通显示，Suggestion 幽灵文字也要在用户接受进输入框后才参与识别。
 
+Skill 使用 Pi 原生机制：模型根据名称、描述和路径按需用 `read` 读取；用户明确调用时，在输入开头使用 `/skill:code-review 审查这个 PR`（前提是 Pi 已加载该 Skill）。候选补全、正文展开和运行中追加输入均由 Pi 处理。OpenPI 不提供专门的 `$skill` 语法或独立的 Skill 加载通道。
+
+Skill 正文通过原生用户消息或工具结果进入正常 Session 历史，压缩也交给 Pi。OpenPI 不另存正文快照，不叠加隐藏正文，也不在压缩后自动补回。压缩后不保证全文仍在模型上下文中；需要时可重新读取或显式调用。普通 `read` 的输出限制和模型总上下文限制仍然适用。设计边界见 [Decision 0002](docs/decisions/0002-native-skill-lifecycle.md)。
+
 > [!IMPORTANT]
 > 默认安装是安静的：不改主题、不绑定 Provider 或模型、不开启下一步预测，也不执行 post-edit 命令。Capability discovery 默认 `explicit`；只有用户通过 `/openpi-setup` 选择 `adaptive` 后，模型才会常驻看到一个小型发现网关并可自主加载额外能力。
 

docs/decisions/0002-native-skill-lifecycle.md

@@ -0,0 +1,50 @@
+---
+decision-status: accepted
+created: 2026-08-31
+last-reviewed: 2026-08-31
+applies-to: Pi 0.84.1; OpenPI PR 322 revision e4731fcc90af172b0dbed3325220d42f13cfb81c and its native-only replacement
+owner: OpenPI maintainers
+related-issues: "#282, #316, #317"
+related-prs: "#321, #322"
+supersedes: none
+---
+
+# Decision 0002: Keep Skill loading and lifecycle native to Pi
+
+## Context
+
+[Issue #316](https://github.com/openpi-dev/openpi/issues/316) originally required inline `$skill` references with unchanged visible text and hidden model-visible bodies. [PR #322](https://github.com/openpi-dev/openpi/pull/322) implemented run-scoped snapshots and provider-context projections; the integrated candidate also added completion from [PR #321](https://github.com/openpi-dev/openpi/pull/321) and reattached snapshots after compaction. These features implemented the earlier requirement, not a contributor failure.
+
+After source research, the maintainer chose to use native Pi without an additional body lifecycle. The accepted direction is published in [Discussion #324](https://github.com/openpi-dev/openpi/discussions/324#discussioncomment-18217814). Earlier candidate recommendations and their evidence remain in that Discussion; they are not accepted Decisions superseded by this record.
+
+## Decision
+
+- Pi owns Skill discovery, source identity, trust, metadata, and loading.
+- Model-selected Skills use the native metadata catalogue and `read` tool. Explicit invocation uses `/skill:name` and Pi's existing expansion, including native queued input paths.
+- Pi owns completion, normal message persistence, compaction and Session reconstruction. OpenPI adds no Skill-specific body cache, provider-only projection, compaction reattachment, or guaranteed reload-marker retention.
+- Do not retain a separate `$skill` parser or autocomplete adapter. It would advertise a second invocation contract after its hidden-body execution path was removed. `$skill` remains ordinary text; a model may interpret it naturally, but OpenPI makes no automatic loading guarantee.
+- Do not replace the deleted extension with an alias, prompt router, configuration switch, or a new loading module.
+
+## Evidence boundary
+
+The source baseline is Pi 0.84.1 at [`53fa77cc`](https://github.com/earendil-works/pi/commit/53fa77ccd8a279eb87e92294ef3687b03ff80112): [metadata and native read instructions](https://github.com/earendil-works/pi/blob/53fa77ccd8a279eb87e92294ef3687b03ff80112/packages/coding-agent/src/core/skills.ts#L306-L337), [explicit and queued expansion](https://github.com/earendil-works/pi/blob/53fa77ccd8a279eb87e92294ef3687b03ff80112/packages/coding-agent/src/core/agent-session.ts#L1219-L1300), and [compaction-aware context reconstruction](https://github.com/earendil-works/pi/blob/53fa77ccd8a279eb87e92294ef3687b03ff80112/packages/coding-agent/src/core/session-manager.ts#L383-L439).
+
+The implementation regression suite is [native-skills.test.ts](../../tests/extensions/shared/native-skills.test.ts). It loads the package through Pi in an isolated fixture and exercises actual Session, read-tool, persistence and compaction paths with a deterministic faux provider. It does not prove model compliance, paid-provider behavior, terminal UI acceptance or released behavior. Command results belong in the implementation receipt, not in claims of model effectiveness.
+
+## Alternatives considered
+
+- Reference-only adaptation and native hidden-body injection were credible earlier candidates, but both would add an OpenPI invocation contract rather than reuse the native command as-is.
+- The candidate's immutable snapshots and compaction reattachment enforce a stronger body-visibility contract. That additional contract is intentionally retired, not replaced by weaker synchronization code.
+- Other agents' bounded body recovery and reload markers remain useful research. Their existence does not establish a requirement to implement them in OpenPI.
+
+## Consequences
+
+The candidate loses inline multi-Skill expansion and the promise of unchanged raw text plus hidden bodies. Native slash invocation instead expands a user message, which participates in normal persisted history. Native read results also participate in history. No OpenPI-owned stored body format needs migration: the retired snapshots were in-memory provider projections. Existing Session records must not be deleted or rewritten.
+
+Compaction may remove full instructions from the active context while preserving the underlying Session history. Neither automatic rereading nor exact instruction retention is guaranteed. Long reads remain bounded by Pi's read-tool output limits; explicit expansion remains bounded by model context capacity. These are accepted native limitations, not claims of zero risk.
+
+The original Issue acceptance criteria and PR description need alignment before the replacement is merged; this record does not silently change them or close the related Issues. No compatibility alias is promised for an unmerged candidate. A future recovery mechanism requires concrete failure evidence and a separately accepted scope.
+
+## Amendments
+
+None. Adoption records the maintainer's scope decision, not a merge, release or runtime-acceptance receipt.

docs/decisions/README.md

@@ -16,3 +16,4 @@ Start from [`TEMPLATE.md`](TEMPLATE.md).
 ## Records
 
 - [`0001-documentation-and-evidence-governance.md`](0001-documentation-and-evidence-governance.md) — repository knowledge categories, evidence states, and publication boundaries.
+- [`0002-native-skill-lifecycle.md`](0002-native-skill-lifecycle.md) — use Pi's native Skill loading and Session lifecycle without an OpenPI body-recovery layer.