# pi-Automated-Skill-Forge

**Repository Path**: kk3541/pi-Automated-Skill-Forge

## Basic Information

- **Project Name**: pi-Automated-Skill-Forge
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!-- PROJECT SHIELDS -->
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![Version][version-shield]][version-url]

<!-- LANGUAGE SWITCHER -->
<div align="center">
  <strong>🌍 Language (语言):</strong>
  <a href="README.md">English</a> ·
  <a href="README.zh-CN.md">简体中文</a> ·
  <a href="README.es.md">Español</a> ·
  <a href="README.fr.md">Français</a> ·
  <a href="README.de.md">Deutsch</a> ·
  <a href="README.ja.md">日本語</a> ·
  <a href="README.ko.md">한국어</a>
</div>

<!-- PROJECT LOGO -->
<br />
<div align="center">
  <h1 align="center" style="font-size: 3em; font-weight: 800;">pi Automated Skill Forge</h1>

  <p align="center">
    自动提炼、整理、优化、演化 agent skill 的元层系统
    (Self-evolving skill factory for AI agents)
    <br />
    <a href="https://github.com/quick123-666/pi-Automated-Skill-Forge/releases/tag/v1.5.0">
      <img src="https://img.shields.io/badge/version-1.5.0-blue.svg" alt="Version 1.5.0">
    </a>
    <br />
    <a href="https://github.com/quick123-666/pi-Automated-Skill-Forge"><strong>Explore the docs »</strong></a>
    <br />
    <br />
    <a href="https://github.com/quick123-666/pi-Automated-Skill-Forge">View Demo (查看演示)</a>
    &middot;
    <a href="https://github.com/quick123-666/pi-Automated-Skill-Forge/issues/new?labels=bug">Report Bug (报告 Bug)</a>
    &middot;
    <a href="https://github.com/quick123-666/pi-Automated-Skill-Forge/issues/new?labels=enhancement">Request Feature (请求功能)</a>
  </p>
</div>

<!-- TABLE OF CONTENTS -->
<details>
  <summary>Table of Contents (目录)</summary>
  <ol>
    <li>
      <a href="#about-the-project">About The Project (项目介绍)</a>
      <ul>
        <li><a href="#built-with">Built With (技术栈)</a></li>
      </ul>
    </li>
    <li>
      <a href="#getting-started">Getting Started (快速开始)</a>
      <ul>
        <li><a href="#prerequisites">Prerequisites (前置条件)</a></li>
        <li><a href="#installation">Installation (安装)</a></li>
      </ul>
    </li>
    <li><a href="#usage">Usage (用法)</a></li>
    <li><a href="#roadmap">Roadmap (路线图)</a></li>
    <li><a href="#contributing">Contributing (贡献)</a></li>
    <li><a href="#license">License (许可)</a></li>
    <li><a href="#contact">Contact (联系)</a></li>
    <li><a href="#acknowledgments">Acknowledgments (致谢)</a></li>
  </ol>
</details>

<!-- ABOUT THE PROJECT -->
## About The Project (项目介绍)

**pi Automated Skill Forge** 是让 AI agent (pi) **自我演化技能**的元层系统 (meta-layer system for self-evolving skills)。

核心能力 (Core capabilities):

- **自动提炼 (Auto-mine)**: 从对话历史提取 candidate skills (`mine.py`)
- **自动验证 (Auto-verify)**: 6 task × 4 arm empirical harness (`harness.py`)
- **自动安装 (Auto-install)**: 4-format adapter (SKILL.md / npx / python / github_multi) (`skill-forge-install.py`)
- **自动演化 (Auto-evolve)**: rule_writer agent 自动加规则 + rules-enforcer skill 条件执行
- **条件驱动 (Conditional)**: pi 工作前按 scope 检查规则 (rules-enforcer)
- **自我纪律 (Self-discipline)**: RULES.md registry + check_decision/scope/doc_linter + git hooks

**为什么做这个? (Why?)**: LLM 有"完整、稳妥、防御"的扩张偏置 (expansion bias)。这个系统把"提炼 → 验证 → 安装 → 演化"变成自动化 pipeline,让 agent 的 skill 自己成长。

<p align="right">(<a href="#readme-top">back to top</a>)</p>

### Built With (技术栈)

* [![Python][Python.org]][Python-url] — 全部 stdlib-only, 零外部依赖
* [![Pi][Pi]][Pi-url] — Pi Coding Agent harness (pi extension integration)
* [![Git][Git]][Git-url] — version control + git hooks

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- TECHNICAL ARCHITECTURE -->
## Technical Architecture (技术架构)

### 系统架构 (System Architecture) — 3 层

```
┌──────────────────────────────────────────────────────┐
│ Layer 1: Skills (被动知识 Passive data)                │
│ 8 auto-created + 7 wrapped skills (SKILL.md)          │
│ 描述 WHAT to do (做什么)                              │
└──────────────────────────────────────────────────────┘
                          ↓ invoked by (被调用)
┌──────────────────────────────────────────────────────┐
│ Layer 2: Agent (调度器 Dispatcher)                    │
│ pi-extension/index.js — 15 slash commands             │
│ 描述 WHO to call (谁调用)                             │
└──────────────────────────────────────────────────────┘
                          ↓ calls (调用)
┌──────────────────────────────────────────────────────┐
│ Layer 3: Scripts (确定性逻辑 Deterministic logic)      │
│ 9+ Python scripts (stdlib-only, 零依赖)               │
│ 描述 HOW to do (怎么做)                               │
└──────────────────────────────────────────────────────┘
```

### 核心组件 (Core Components)

| 组件 (Component) | 作用 (Role) | 技术要点 (Technical note) |
|---|---|---|
| `mine.py` | 从对话历史提取候选技能 | imperative-sentence 提取 + error-fix pattern + Jaccard 聚类;输出 YAML frontmatter |
| `harness.py` | 实证验证 | 6 任务 × 4 臂 (no-skill/pony/existing-best/candidate);指标: LOC/pass/time/safety |
| `skill-forge-install.py` | 安装到 pi | 4 格式适配器: SKILL.md / npx / python / github_multi;原子写 + cleanup-on-failure |
| `state_machine.py` | 生命周期状态机 | 9-tag schema;状态: draft→installing→verified→active→debt/retracted;transition 校验 |
| `state_per_skill.py` | 跨调用记忆 | per-skill state.json: invocation_count / success_rate / last_failure |
| `skill_router.py` | 自动路由 | 3 法评分: exact-substring + Jaccard(query,trigger) + Jaccard(query,desc);词干归一化;阈值 0.20 |
| `invoke_skill.py` | 端到端调用 | route → execute wrapper → record state;error 永不 crash |
| `dedup.py` | 前置去重 | 调 deep-skill-finder API + 启发式相似度阈值 0.6 |
| `rule_writer.py` | 自动加规则 | 4 detectors (claim/count/state/why) → propose → validate → apply → auto-sync skill |
| `rules_to_skill.py` | RULES.md → SKILL.md | 按 scope 分组生成 rules-enforcer skill;--check 验证同步 |
| `auto_deprecate.py` | 自动废弃 | 4 标准 (unused>90d / rarely / high-failure / never-used) → active→debt |
| `pi-extension/index.js` | pi 集成 | 15 slash commands;body-only 或 script dispatch;never-crash |

### 数据流 (Data Flow)

```
对话历史 / 提交历史 / 用户反馈
        ↓
  [mine.py]          提取候选技能 (candidate skills)
        ↓
  [dedup.py]         与已有技能去重
        ↓
  [harness.py]       实证验证 (RED/GREEN gate)
        ↓
  [skill-forge-install.py]  安装到 pi skills/ (4 格式)
        ↓
  [state_machine.py] 生命周期跟踪 (draft→verified→active)
        ↓
  [invoke_skill.py]  实际调用 (route→execute)
        ↓
  [state_per_skill.py] 记录调用统计 (cross-invocation memory)
        ↓
  [auto_deprecate.py] 自动废弃长期未用 / 高失败率技能
        ↓
  [rule_writer.py]   从观察中自动提炼新规则 (闭环)
```

### 规则系统 (Rule System)

**RULES.md** 是规则唯一来源 (single source of truth), 25 条规则分 4 类:

| 类 (Class) | 前缀 (Prefix) | 数量 (Count) | 作用 (Role) |
|---|---|---|---|
| P-rules (pony 派生) | P1-P9 | 9 | 设计原则, code-only scope |
| C-rules (自定义) | C1-C18 | 18 | shorthand 检测 / 中文双语 / self-apply |
| B-rules (反泄漏) | B1-B4 | 4 | 防止 pony 规则泄漏到非代码域 |

**规则执行链 (Enforcement chain)**:

```
RULES.md (canonical)
    ↓ rules_to_skill.py
rules-enforcer SKILL.md (按 scope 分组)
    ↓ pi 加载
pi 工作前按 scope 检查条件 → 命中 apply / 未命中正常处理
```

### 状态机 (State Machine)

```
draft ──→ installing ──→ verified ──→ active ──→ debt ──→ retracted
   \         │              │           │  \                  ↑
    └────────┘              └───────────┘   └──→ failed ──────┘

合法转换 (valid transitions):
- draft → installing / verified / active / install-failed / retracted
- active → retracted / failed / verified / debt (auto-deprecate)
- debt → active / retracted / draft (可逆, 用户决定)
- retracted = 终态 (terminal)
```

### Harness 详情 (Harness Details)

**6 个任务 (tasks) × 4 个臂 (arms)**:

| Task | 类型 (Type) | 验证点 (Verification point) |
|---|---|---|
| `csv_sum` | external trust boundary | malformed row 不 crash |
| `safe_path` | external | path traversal 拦截 |
| `email_validation` | external | parseaddr trap 识别 |
| `debounce` | internal | setTimeout+clearTimeout 存在 |
| `date_picker` | internal (over-build trap) | native `<input type=date>` 优先 |
| `palindrome` | internal | 纯逻辑正确性 |

**4 个臂 (arms)**: `no_skill` (verbose baseline) / `pony` (minimal baseline) / `existing_best` (搜索最优) / `candidate` (mine 输出)

**指标 (Metrics)**: LOC (代码行数) / pass-rate (通过率) / wall-time (耗时) / safety (对抗性安全)

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- GETTING STARTED -->
## Getting Started (快速开始)

### Prerequisites (前置条件)

* Python 3.8+ (stdlib only, 无需虚拟环境)
  ```sh
  python --version
  ```

### Installation (安装)

> ⚠️ **重要 (IMPORTANT) — 第 1 步不是 clone, 是装 git hooks**
>
> Per Lesson #13 (单一副本顶层标准 = 单点故障): v1.3.0 引入的 `pre-push`
> hook 是第 4 层 recall-first 防御 (真阻塞 push 到 main / v* tag 前必须引用
> lesson/C-rule), 但 git hooks 不被 git track — clone 后不跑
> `install-hooks.sh` 就没 hook, **整个防御层形同虚设**。
>
> 在 pi-Automated-Skill Forge 项目里, 我们项目本身也是用这些 hook 来约束
> 发布的, 你 clone 这个 repo 后如果不装 hook, 等于绕过了项目自用的纪律。

1. **Install git hooks** (装 git 钩子 — **必须先做, 不可跳过**)
   ```sh
   bash tools/install-hooks.sh
   ```
   这会把 `tools/git-hooks/*` symlink 到 `.git/hooks/`, 启用:
   - `pre-commit`: check_decision shorthand 扫描
   - `commit-msg`: commit 长度警告 + publish-class commit lesson ref 检查
   - `pre-push`: publish guard (per Lesson #14 + C20), push 到 main / v* tag 前最近 5 commit 必须引用 lesson/C-rule, 否则阻塞

2. **Clone the repo** (克隆仓库)
   ```sh
   git clone https://github.com/quick123-666/pi-Automated-Skill-Forge.git
   cd pi-Automated-Skill-Forge
   ```

3. **Run harness 验证** (跑 harness 验证)
   ```sh
   python harness.py
   ```

4. **生成 rules-enforcer skill** (生成规则执行技能)
   ```sh
   python tools/rules_to_skill.py
   ```

> **为什么 hook 在 clone 之前** (per Lesson #14 + C14 self-apply):
> 一旦你 commit 了无 lesson ref 的 publish-class commit, 再装 hook 也会被
> 它拦下来 — 体验很糟糕。先装 hook, 然后 clone, 整个流程受保护。

### Reference repos (参考仓库)

本项目包含 1 个**第三方参考仓库** (已纳入 repo):

| 仓库 (Repo) | 用途 (Purpose) | 状态 (Status) |
|---|---|---|
| **deep-skill-finder** | 搜索 skill 的 API + 脚本 (用于 `invoke_skill.py` 和 `dedup.py`) | ✅ **已包含在本 repo** (`deep-skill-finder/`) |

> **说明 (Note)**: `deep-skill-finder` 已纳入项目, clone 后可直接使用搜索功能 (`python invoke_skill.py "find skill on web"`)。
> 其代码归原作者所有 (MIT 许可), 作为搜索功能依赖包含。

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- USAGE EXAMPLES -->
## Usage (用法)

### 1. Invoke skills (调用技能)

```sh
python invoke_skill.py "find skill on web"       # 自动路由到 deep-skill-finder
python invoke_skill.py "verify skill"             # 自动路由到 skill-forge-verify
python invoke_skill.py "I want to install skill"  # 自动路由到 skill-forge-install
```

### 2. Skill lifecycle (技能生命周期)

```sh
python mine.py conversation.txt --top 5            # mine candidates (提炼候选)
python harness.py --task csv_sum                   # verify single task (验证)
python skill-forge-install.py deep-skill-finder    # install to pi (安装)
python state_machine.py list                       # track status (跟踪状态)
python state_machine.py auto                       # auto-deprecate stale (自动废弃)
```

### 3. Rules (规则系统)

```sh
python agents/rule_writer.py --from-commits 20     # agent 提议新规则 (propose rules)
python tools/check_decision.py README.md           # shorthand 检测
python tools/check_scope.py AGENTS.md              # scope 泄漏检测
python tools/rules_to_skill.py --check             # 验证规则同步
```

_For more examples, please refer to the [AGENTS.md](AGENTS.md) (更多示例见 AGENTS.md)_

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- ROADMAP -->
## Roadmap (路线图)

- [x] v1.0.0: initial release — 9 scripts + 14 skills + harness
- [x] v1.1.0: pi extension + state files + rule_writer + rules-enforcer + auto-deprecate
- [x] v1.2.0: publish loop closed — skill-forge-publish + github-publish + C20 publish gates + skill-finder integration
- [x] v1.3.0: skill rating system + 4-layer recall-first defensive system + version reflection
- [ ] v1.4: live agent invocation + task set 12+ + LLM-as-judge
- [ ] v1.5: decision pattern synthesis + multi-runtime compile
- [ ] v2.0: agent spec factory (不只 skill, 还产生 tools / sub-agents)

See the [open issues](https://github.com/quick123-666/pi-Automated-Skill-Forge/issues) for a full list of proposed features (完整功能列表见 issues).

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- CONTRIBUTING -->
## Contributing (贡献)

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated** (任何贡献都**非常感谢**).

1. Fork the Project (Fork 项目)
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

**注意 (Note)**: 本项目有 git hooks 自动检查 commit message 的 shorthand 和长度,遵循 RULES.md。

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- LICENSE -->
## License (许可)

Distributed under the MIT License. See `LICENSE` for more information (MIT 许可,详见 LICENSE).

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- CONTACT -->
## Contact (联系)

Project Link: [https://github.com/quick123-666/pi-Automated-Skill-Forge](https://github.com/quick123-666/pi-Automated-Skill-Forge)

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- ACKNOWLEDGMENTS -->
## Acknowledgments (致谢)

* **[Ponytail](https://github.com/DietrichGebert/ponytail)** — 本项目的重要设计灵感来源。我们深度参考了 Ponytail 的 lazy senior dev 理念、8 项设计约束、多 SKILL 结构与 empirical harness 思路,并在此基础上构建了自动提炼与演化的元层系统。**特别感谢 Ponytail 的开创性工作。**
* [Best-README-Template](https://github.com/othneildrew/Best-README-Template) — README 模板来源
* [Agent Skills spec](https://agentskills.io) — skill 格式标准
* [液态神经网络标准] — 项目规范参考

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- MARKDOWN LINKS & IMAGES -->
[contributors-shield]: https://img.shields.io/github/contributors/quick123-666/pi-Automated-Skill-Forge.svg?style=for-the-badge
[contributors-url]: https://github.com/quick123-666/pi-Automated-Skill-Forge/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/quick123-666/pi-Automated-Skill-Forge.svg?style=for-the-badge
[forks-url]: https://github.com/quick123-666/pi-Automated-Skill-Forge/network/members
[stars-shield]: https://img.shields.io/github/stars/quick123-666/pi-Automated-Skill-Forge.svg?style=for-the-badge
[stars-url]: https://github.com/quick123-666/pi-Automated-Skill-Forge/stargazers
[issues-shield]: https://img.shields.io/github/issues/quick123-666/pi-Automated-Skill-Forge.svg?style=for-the-badge
[issues-url]: https://github.com/quick123-666/pi-Automated-Skill-Forge/issues
[license-shield]: https://img.shields.io/github/license/quick123-666/pi-Automated-Skill-Forge.svg?style=for-the-badge
[license-url]: https://github.com/quick123-666/pi-Automated-Skill-Forge/blob/master/LICENSE
[version-shield]: https://img.shields.io/badge/version-1.5.0-blue.svg
[version-url]: https://github.com/quick123-666/pi-Automated-Skill-Forge/releases/tag/v1.5.0
[product-screenshot]: images/screenshot.png
[Python.org]: https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white
[Python-url]: https://www.python.org/
[Pi]: https://img.shields.io/badge/PiCodingAgent-000000?style=for-the-badge&logo=terminal&logoColor=white
[Pi-url]: https://github.com/earendil-works/pi-coding-agent
[Git]: https://img.shields.io/badge/Git-F05032?style=for-the-badge&logo=git&logoColor=white
[Git-url]: https://git-scm.com/