docs: repository README, contributor rules, scenario template and authoring guide

README leads with the finding that motivated the repository -- pi emits the
skills section only when a tool named 'read' is active, so Curator's
--no-tools --skill combination made its policy unreachable -- with the measured
before/after table and instructions to reproduce it at zero token cost.

AGENTS.md sets seven rules for anyone changing this repository. The third is the
one that matters most: verify pi's behaviour with a probe rather than inferring it
from the docs. Three claims in the first draft of these documents were wrong and
were only corrected by running one.

The _template scenario carries the isolation defaults and inline warnings at the
places where mistakes have already cost time: --no-tools disabling the skills
mechanism, cwd anchoring .pi discovery, the read override being mandatory rather
than optional, and allowed-tools frontmatter not being enforced in 0.84.3.
This commit is contained in:
Kai
2026-08-26 23:19:19 -07:00
parent 07dd648b5f
commit f25082223e
8 changed files with 518 additions and 0 deletions
@@ -0,0 +1,24 @@
---
name: <skill-name>
description: <何时使用本 skill。只有 description 常驻上下文,正文按需由 read 加载,所以这句话决定它会不会被用到。>
---
# <Skill 名>
> 只有当某个流程**不是每轮都需要**时才做成 skill。description 写成"用于每一个
> 请求"的 skill 没有路由价值,那属于系统提示内容。
>
> `allowed-tools:` frontmatter 在 pi 0.84.3 **不被消费**,不要依赖它做约束;
> 真正的约束在 extension 的 ALLOWED_TOOLS。
## 支持的意图
## 前置条件
## 风险等级
## 成功核验条件
## 失败恢复
## 示例