diff --git a/AGENT.md b/AGENT.md
index fe604938..aeb9ea34 100644
--- a/AGENT.md
+++ b/AGENT.md
@@ -2,6 +2,8 @@
 
 本文件为 AI 编码助手在此仓库中工作时提供指引。
 
+> Lua 侧 API 见 [`skills/SKILL.md`](skills/SKILL.md)——只有模块索引与跨模块约定，签名一律以 `meta/*.lua` 为准，行为与示例看 `test/`。
+
 ## 项目简介
 
 **bee.lua** 是一个跨平台 Lua 扩展库，为 Lua 5.4 和 5.5 提供系统级原生绑定，封装了异步 I/O、网络、子进程管理、多线程、文件监控等操作系统 API，以统一的 Lua 接口对外暴露。
diff --git a/README.md b/README.md
index c1a127ee..67699095 100644
--- a/README.md
+++ b/README.md
@@ -35,3 +35,9 @@ Lua runtime and toolset
 * [fmtlib/fmt](https://github.com/fmtlib/fmt) Compatible with `std::format`(c++20) and `std::print`(c++23).
 * [gulrak/filesystem](https://github.com/gulrak/filesystem) Compatible with `std::filesystem`(c++17).
 * [actboy168/ltest](https://github.com/actboy168/ltest) Test framework.
+
+## Documentation
+
+Lua API: see [`meta/`](meta) (LuaLS annotations, authoritative for signatures) and [`test/`](test) (behavior contract).
+Usage guide and conventions: see [`skills/SKILL.md`](skills/SKILL.md). AI coding agents should read it before working on `require "bee.*"` code in this repo.
+
diff --git a/skills/SKILL.md b/skills/SKILL.md
new file mode 100644
index 00000000..4a39a4d9
--- /dev/null
+++ b/skills/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: bee-lua
+description: bee.lua 运行时库指南——Lua 5.4/5.5 上的跨平台系统级绑定（异步 I/O、网络、子进程、线程、文件系统、文件监控、崩溃 dump）。当需要在本项目里编写、修改或排查使用 `require "bee.*"` 的 Lua 代码，涉及 socket/select/epoll/async、thread/channel/serialization、subprocess、filesystem/filewatch、time/sys/crash/debugging/windows，或需要按平台差异处理行为时，使用本 skill。即使用户没有明确提到 bee.lua，只要上下文是在调用 `bee` 命名空间下的模块，也应使用。不要用于纯 Lua 语言/标准库问题、与 bee 无关的第三方 C 模块，或本项目 C++ 层 `bee/`、`binding/` 的实现细节（那些看源码）。
+---
+
+# bee.lua
+
+Lua 扩展库，为 Lua 5.4 / 5.5 提供系统级原生绑定。
+
+## API 参考来源
+
+**本 skill 不维护 bee 的 API 签名表**，以仓库里的文件为唯一权威来源：
+
+| 目的 | 来源 |
+|------|------|
+| 函数签名、参数/返回值类型、字段与常量 | `meta/<module>.lua`（LuaLS/EmmyLua 注解，带中文说明） |
+| 行为契约、错误文案、边界情况、可运行示例 | `test/test_<module>.lua` |
+| 构建与测试命令、测试规范 | `AGENT.md` |
+| C++ 层实现细节 | `bee/`、`binding/lua_<module>.cpp` |
+
+## 模块索引
+
+| 模块 | meta | 用途 |
+|------|------|------|
+| `bee.platform` | `meta/platform.lua` | 平台/编译器/架构信息（纯数据表） |
+| `bee.filesystem` | `meta/filesystem.lua` | 路径与文件系统操作 |
+| `bee.serialization` | `meta/serialization.lua` | 序列化（线程/通道的底层） |
+| `bee.time` | `meta/time.lua` | 墙钟 / 单调 / 线程 CPU 时间 |
+| `bee.sys` | `meta/sys.lua` | 可执行文件路径、文件锁 |
+| `bee.socket` | `meta/socket.lua` | TCP/UDP/Unix socket |
+| `bee.select` | `meta/select.lua` | select 风格多路复用 |
+| `bee.epoll` | `meta/epoll.lua` | epoll 风格多路复用（Windows 走 IOCP） |
+| `bee.async` | `meta/async.lua` | 异步 I/O（IOCP / io_uring / GCD） |
+| `bee.filewatch` | `meta/filewatch.lua` | 文件监控 |
+| `bee.thread` | `meta/thread.lua` | 线程 |
+| `bee.channel` | `meta/channel.lua` | 线程间通信 |
+| `bee.subprocess` | `meta/subprocess.lua` | 子进程与管道 |
+| `bee.windows` | `meta/windows.lua` | Windows 专有工具 |
+| `bee.crash` | `meta/crash.lua` | 崩溃 dump |
+| `bee.debugging` | `meta/debugging.lua` | 断点 / 调试器探测 |
+
+## 跨模块约定
+
+- 模块都在 `bee.*` 命名空间：`local socket = require "bee.socket"`。
+- **三态返回值**（socket / epoll / select 等非阻塞接口）：成功 → 值；`false` → 需等待（非错误）；`nil, errmsg` → 失败/对端关闭。参数校验错误才 `error()`。
+- 句柄类对象用 to-be-closed 管理：`local fd <close> = assert(socket.create "tcp")`。
+- 子进程管道是标准 `file*`，用 `:read "a"` / `:write` / `:close`。
+- 线程/通道传值经 `bee.serialization`，只支持 `nil/boolean/number/string/table/light C function`。
+- 平台上不可用的模块/接口在测试中跳过（`test/test_skip.lua`、`test/supported.lua`）。
+
+## 可选链（编译期 patch）
+
+`?.` / `?:` / `?[...]` / `f?(...)` 是 vendored Lua 的补丁语法，仅当 `luamake -optchain` 构建时可用（补丁机制见 `AGENT.md`）：
+
+- 只有 `nil` 短路，`false` 会照常报错；短路时参数/键不会被求值，接收者只求值一次。
+- 短路只覆盖链本身：`(nothing?.b).c`、`nothing?.b + 1` 仍报错。
+- 不可作为赋值目标。
+- 完整行为（含字节码布局）见 `test/test_optional_chain.lua`。