Org File as AI Skills System

一个 Claude Code Skill 本质上是一个目录，核心文件是 SKILL.md。文件顶部是 YAML frontmatter，用于声明元信息——name 会变成 /slash-command，description 用于让模型判断何时应该自动加载这个技能。正文部分是人类可读的指令，描述这个技能做什么、怎么做。

Claude Code 已经将「自定义斜杠命令」和「技能系统」合并。历史上 .claude/commands/review.md 和 .claude/skills/review/SKILL.md 都能生成 /review 命令，但现在两者统一为目录形式的 skills 结构。这种统一意味着，一个技能不再仅仅是一个被执行的命令，它是一个完整的、可复用的、可以携带资源的工作单元。

Progressive Disclosure（渐进式披露）是理解 Skills 设计理念的关键。它解决了一个根本问题：如何在有限的上下文窗口中加载大量技能，同时不导致信息爆炸。

Level 1 是元数据层，只在启动时加载 YAML 中的 name、description 等发现信息。这部分非常轻量，大约每个技能 100 tokens。这意味着可以安装几十甚至上百个技能，而不会把上下文撑爆。Level 1 的目的是让模型「知道」有哪些技能可用，但不加载它们的详细内容。

Level 2 是指令层，只有当技能被触发时才加载 SKILL.md 的正文。官方建议将正文控制在 5000 tokens 以内，并把大段的参考文档移到独立文件中。这一层是技能的「执行逻辑」，只有需要时才被读取。

Level 3 是资源和代码层。技能目录中的其他文件——更多的 Markdown、模板、脚本、Schema、示例——不会主动塞进上下文。模型需要时通过文件系统访问来使用它们。这相当于给技能配备了一个「几乎无限」的外部知识包，按需检索。

这种三层设计就是 Skills 被称为「下一代应用分发形态」的原因。分发的不只是提示词，而是一套能被 Agent 逐步展开的工作台和工具箱。

Claude Code 在 frontmatter 中提供了精细的调度控制能力。disable-model-invocation: true 禁止模型自动触发技能，只允许用户手动触发。这适合有副作用的工作流，比如部署代码或提交 git。user-invocable: false 则相反，只允许模型触发，不允许用户手动调用——这更像是「背景知识包」，在特定场景下自动加载。allowed-tools 可以限制技能激活时能使用哪些工具，从而实现「只读模式」或「安全模式」。这些配置赋予了技能系统企业级的可控性。

Claude Code 使用 YAML frontmatter 来声明元数据。Org Mode 提供了类似的机制，但更加强大——Properties drawer（属性抽屉）可以表达更复杂、更具层次的结构。

可以在一个 Org heading 下定义任意数量的属性：:SKILL_ID:、:EFFECT:、:INVOCATION:、:CONTEXT:、:DETERMINISM: 等等。这些属性可以被程序解析，也可以被 gptel 读取后插入到发送给模型的上下文中。更重要的是，Org 的 headline 层级天然适合将一个 Skill 拆分为「概览→流程→边界→例子→失败模式→检查清单」的结构，而不是在单个 Markdown 文件中写出一大坨内容。

这意味着，Org 文件本身就是一个「可编译的 Spec」。可以写一个.elisp 函数，将 Org 属性转换为 YAML frontmatter，将 Org 结构编译成 SKILL.md，同时保留源文件作为「唯一的真相来源」。这就是「可编译」的含义——Spec 不是一次性写死的文档，而是一个可以机器解析、人机协作编辑的源代码。

Claude Code 的 Level 3 强调「脚本应该是可执行的，并且不占用上下文」。Org Babel 完美地实现了这一点。

在 Org 文件中，可以用 #+BEGIN_SRC python、#+(shell)、#+(javascript) 等语法定义代码块。这些代码块在 Org 中是可阅读的——这是 literate programming 的精髓——但它们也可以被抽取为独立的脚本文件。一个 #+BEGIN_SRC python 块可以变成 scripts/analyze.py，一个 #+BEGIN_SRC shell 块可以变成 scripts/deploy.sh。

这意味着 Org Skill 既保留了「文档的可读性」，又具备了「代码的执行性」。当模型需要运行一个脚本时，它不需要在上下文中读取脚本内容，而是通过文件系统访问来执行。这与 Claude Code 的 Level 3 设计完全对齐。

定义在 Skill 文件中的函数调用与函数实现：

** Function Calls
#+BEGIN_SRC emacs-lisp
;; Function: search-web
;; Search the web using Search1API
;; @query: Search query string
;; @language_hint: Optional language hint
(org-ai-skills-search-web &key query language_hint)
#+END_SRC

** Function Definitions
#+BEGIN_SRC emacs-lisp
(defun org-ai-skills-search-web (&key query language_hint)
  "Skill function: search the web using Search1API."
  (let ((api-key (auth-source-pick-first-password :host "search1api")))
    (unless api-key
      (error "Search1API key not found in auth-source"))
    (request "https://api.search1api.com/search"
             :type "POST"
             :headers (cons (cons "Authorization"
                                  (format "Bearer %s" api-key))
                            (cons "Content-Type" "application/json"))
             :data (json-encode `(("query" . ,query)
                                 ("language_hint" . ,language_hint)))
             :parser 'json-read
             :sync t
             :error (cl-function
                     (lambda (&key error-thrown &allow-other-keys)
                       (signal 'org-ai-skills-function-call-error
                               (list error-thrown)))))))
#+END_SRC

Babel 代码块可以直接在 Org buffer 中执行（org-babel-execute-src-block），也可以导出为独立脚本文件。以下是一个完整的金融新闻 Skill 示例中的代码块定义：

* Skill: Daily Financial News Report
:PROPERTIES:
:SKILL_ID: daily-financial-news-report
:END:

#+EFFECT: external
#+INVOCATION: auto
#+CONTEXT: project
#+DETERMINISM: heuristic

** Function Definitions
#+BEGIN_SRC emacs-lisp
(defun org-ai-skills-search-financial-news (&key date limit)
  "Fetch financial news for given date using Search1API."
  (let* ((api-key (auth-source-pick-first-password :host "search1api"))
         (response (request "https://api.search1api.com/search"
                            :type "POST"
                            :headers (cons (cons "Authorization"
                                                 (format "Bearer %s" api-key))
                                          (cons "Content-Type" "application/json")))
                            :data (json-encode `(("query" . "finance stock market")
                                                ("date" . ,date)
                                                ("limit" . ,limit)))
                            :parser 'json-read
                            :sync t)))
    (cdadr (assoc 'results response))))
#+END_SRC

导出后的脚本文件示例（scripts/search-financial-news.el）：

#!/usr/bin/emacs --script
;;; scripts/search-financial-news.el --- Search financial news

(add-to-list 'load-path "/path/to/org-ai-skills/elisp")
(require 'org-ai-skills)

(let* ((date (or (car argv) (format-time-string "%Y-%m-%d")))
       (limit (string-to-number (or (cadr argv) "10"))))
  (org-ai-skills-search-financial-news :date date :limit limit))

对比 Claude Code 中需要将完整脚本塞入上下文的做法，Org Skill 的做法是：上下文中只传递函数签名的声明，函数实现通过 org-babel-load-library 动态加载，运行时通过文件系统执行脚本。这正是 Level 3 所倡导的「脚本外置」理念。

Skills 不是一次性的提示词，而是可复用的工作流。这意味着它们需要被追踪、需要积累执行历史、需要能够被迭代改进。

Org Mode 在这一方面拥有独一无二的原生能力。TODO 关键字可以标记任务的执行状态，CHECKLIST 可以表达步骤化的计划，LOGBOOK 可以记录执行过程中的关键事件和时间戳。这些不是外部插件，而是 Org Mode 与生俱来的数据结构。

用 Org 定义一个 Skill 时，checklist 不是「写死的步骤列表」，而是可以被实例化为 Run Ticket 的模板。每一次执行都可以生成一个新的 Org 子树，记录输入参数、执行的步骤、输出的结果、以及用户的反馈。这种「执行实例与 Skill 定义分离」的设计，保证了 Skill Spec 的纯净性，同时让每一次执行都有迹可循。

这也是 Org Skills 相对于 Claude Code Skills 的一个显著优势。Claude Code 的技能执行记录在外部文件中，而 Org Skills 的执行记录可以直接写在同一个 Org 文件中——或者更好，写在同一个目录结构下的 run/ 子目录中，保持 Spec 的纯粹性。

Run Ticket 实例（每次执行生成的新子树）：

* Run Ticket: gen-notes-2024-01-15-001
:PROPERTIES:
:RUN_ID: 20240115001
:SKILL_ID: gen-notes
:SOURCE_SUBTREE: "** 为什么 Org Mode 比 Markdown 更适合做 Skills"
:TIMESTAMP: 2024-01-15T10:30:00Z
:STATUS: completed
:END:

** Input Parameters
- Target file: ~/Workspace/org-ai-skills/README.org
- Target subtree: "** 为什么 Org Mode..."
- Custom instruction: "添加具体的 spec 例子"

** Execution Log
:LOGBOOK:
CLOCK: [2024-01-15T10:30:00]--[2024-01-15T10:35:00] = 5min
- Skill loaded: gen-notes
- Function calls activated: read-buffer
- gptel request dispatched with role: execution
CLOCK: [2024-01-15T10:35:00]--[2024-01-15T10:38:00] = 3min
- Candidate generated and auto-applied
:END:

** Output
:RESULTS:
- Transformed subtree with code examples added
- Tokens used: 8234
- Model: claude-3-sonnet
:END:

** User Feedback
- [ ] Approved
- [ ] Needs revision
- [ ] Discarded

Planner 生成的执行计划（自动实例化的 TODO 步骤）：

* Plan: Article Writing Workflow
:PROPERTIES:
:PLAN_ID: plan-001
:TASK: "Write article on Org Mode vs Markdown"
:STATUS: in-progress
:END:

** TODO Step 1: Outline from Source
:PROPERTIES:
:SKILL_ID: article-outline-from-source
:STATUS: completed
:END:

** TODO Step 2: Compose from Outline
:PROPERTIES:
:SKILL_ID: article-compose-from-outline
:STATUS: in-progress
:END:

** TODO Step 3: Repair Selected Subtree
:PROPERTIES:
:SKILL_ID: article-repair-subtree
:STATUS: pending
:END:

** TODO Step 4: Editorial Polish
:PROPERTIES:
:SKILL_ID: article-polish-editorial
:STATUS: pending
:END:

与 Claude Code 的 skill tracking 对比：

# Claude Code Skill Tracking (JSON)
# ~/.claude/skills/tracking/gen-notes-runs.json
[
  {
    "run_id": "20240115001",
    "skill_id": "gen-notes",
    "timestamp": "2024-01-15T10:30:00Z",
    "status": "completed",
    "input": {...},
    "output": "..."
  }
]

Org 的优势在于：Planner 和 Run Ticket 本质上都是 Org heading，可以通过 org-agenda、org-gtd 等已有工具进行可视化和操作。执行历史（LOGBOOK）直接内嵌在子树中，可以通过 org-log-note 机制自动记录。而 Claude Code 的追踪完全依赖外部 JSON 文件，需要额外的解析逻辑。

Org 太强大了，这既是优势也是陷阱。一个新手很容易把 Org Skill 写成「百科全书」——把所有相关知识都塞进一个文件，期待模型能理解并正确使用。这恰恰违背了 Progressive Disclosure 的初衷。

一个设计良好的 Org Skill 应该遵循以下原则：元信息要轻，只包含发现和调度所需的最少信息；正文要短，控制在 5000 tokens 以内；大段的参考内容要外置到独立的文件中，作为 Level 3 资源。Org 的丰富功能应该用来增强结构的可解析性和执行的可追踪性，而不是用来替代 Markdown 的简洁性。

此外，需要提前决定「可执行块的安全边界」。Babel 代码块导出后的脚本集合是什么？gptel 或其他 Agent 是否有权限自动执行这些脚本？这些问题对应着 Claude Code 中 disable-model-invocation 的理念，需要在设计阶段就明确。

设计良好的轻量级 Skill 示例（遵循 Progressive Disclosure）：

* Skill: Generate Structured Notes
:PROPERTIES:
:SKILL_ID: gen-notes
:END:

#+EFFECT: pure
#+INVOCATION: suggest
+CONTEXT: project
#+DETERMINISM: deterministic

** Description
Transform selected Org content into a concise, structured outline.

** Contracts
- output must be final Org artifact only
- preserve the original language of the selected section

** Requirements
- keep heading hierarchy valid and consistent with selected target level

** See Also
- [[file:skills/docs/gen-notes-detailed.org]] - Detailed specification (Level 3)
- [[file:skills/examples/gen-notes-example-input.org]] - Example inputs

Level 3 资源外置示例（gen-notes-detailed.org）：

* Gen-Notes Detailed Specification

This document contains the full technical specification for gen-notes skill.

** Algorithm
1. Parse source subtree content
2. Identify key concepts and their relationships
3. Generate hierarchical outline structure
4. Expand each node with substantive content

** Token Budget
- Input budget: 20000 chars
- Output budget: 5000 tokens

** Failure Modes
- Empty source: return error with "No content to transform"
- Ambiguous structure: preserve original structure, add [?] markers
...

安全边界配置示例（在 Skill 实现中声明）：

** Security Configuration
#+BEGIN_SRC emacs-lisp
;; Security boundary: no automatic script execution
;; Scripts must be exported and manually reviewed before running
(setq org-ai-skills-auto-execute-scripts nil)

;; Allowed script types for this skill
(setq org-ai-skills-allowed-script-types '(read-buffer read-file))

;; Read-only operations only (pure effect)
(setq org-ai-skills-effect-type 'pure)
#+END_SRC

这个场景展示了如何用 Org Skills 构建写作工作流：研究 → 提纲 → 创作 → 优化。可以结合现有 skills 和本篇内容的生成过程，说明这个过程是如何运作的。本篇文章就是用这个流程生成的。

这是更具野心的应用方向。想象一个独立企业主或自由职业者，需要管理客户谈判、报价策略、风险评估、合同审核、项目拆解等一系列复杂的决策。这些决策不是一次性的，而是需要系统性地积累经验、优化策略。

传统 SaaS 工具解决这个问题的方式是「割裂」——CRM 负责客户管理，财务工具负责报价，合同工具负责法务。但这些系统之间没有「跨系统的认知决策流」。无法让一个工具理解「这个客户的报价策略失败过，是因为当时现金流状态紧张」这样的上下文。

用 Org Skills 构建个人战略操作系统的方式是：定义一组核心技能——《客户谈判策略 Skill》《报价优化 Skill》《合同风险扫描 Skill》《项目拆解 Skill》——每一个都是 Org 文件，包含完整的决策流程、评估维度、历史案例。每个项目或客户可以生成一个 Run Ticket，记录当次决策的背景、AI 的建议、最终采取的行动、以及结果反馈。

这种系统的独特价值在于：随着 Run Ticket 的积累，系统可以分析「什么情况下报价策略容易失败」「哪种谈判风格对某类客户更有效」，并据此生成 Skill 改进提案。这不是传统工具能提供的——传统工具记录的是数据，而 Org Skills 记录的是「决策逻辑」本身。

第三类场景面向更复杂的推理任务：科研中的文献分析、制度设计、博弈分析、战略规划。这类场景的特点是：问题是非结构化的、推理路径是多叉的、决策需要多轮反证。

传统工具链——Word + Excel + 脑子——无法提供可执行的 Spec、多轮反证的结构化记录、决策演化的追踪。Org Skills 可以为每一种高维认知任务定义专门的 Skill：《制度模型构建 Skill》《博弈分析 Skill》《战略推演 Skill》。每个 Skill 包含目标定义、约束条件、历史对照、失败场景分析等模块。

在执行层面，每一次推理都生成一个 Run Ticket，记录推理路径、否决的方案、以及最终的结论。当系统发现某个推理模块在多次运行中表现不稳定时，它可以生成改进提案，调整 Skill 的结构和提示词。

这种「可推理、可追踪、可自举」的认知工作流，可能是 Org Skills 最具潜力的应用方向。

系统需要一个「Skill Registry」来管理所有可用的 Skills。

目录约定方面，全局 Skills 放在 ~/.emacs.d/skills/，项目级 Skills 放在 <repo>/.claude/skills/（与 Claude Code 保持兼容）。每个 Skill 目录包含一个 skill.org 源文件和编译产物（SKILL.md + resources/ + scripts/）。

扫描策略方面，在 Emacs 启动或打开项目时，系统遍历 Skills 目录，解析 Org 文件中的 Properties 和顶层 headline，提取 Skill ID、name、description、触发关键词、权限配置等元信息。这些信息构成 Level 1 的轻量缓存，用于模型判断「当前上下文应该加载哪些 Skills」。

Skill Compiler 是整个系统的核心转换层。它的任务是将 Org 源文件编译为 Claude Code 兼容的 SKILL.md 格式。

编译流程如下。从 Org Properties 生成 YAML frontmatter——:SKILL_ID: 变成 name，:PURPOSE: 变成 description，:EFFECT:、:INVOCATION: 等映射为 Claude Code 支持的字段。从 Org 标题层级生成 SKILL.md 正文——只导出概览、步骤、示例等核心内容（大段参考外置到 Level 3）。从 Babel 代码块抽取脚本——将 #+BEGIN_SRC 块输出为独立的脚本文件。

这样，Org 文件作为「源代码」，SKILL.md 作为「编译产物」，既保持了 Claude Code 的兼容性，又保留了 Org 的可编辑性和结构化优势。

最后是上下文注入机制——如何在 gptel 中模拟 Claude Code 的 Progressive Disclosure。

在 Level 1 层面，系统将 Registry 扫描得到的轻量元信息（Skill name + description + 关键词）注入到 gptel 的 system prompt 中，让模型知道有哪些 Skills 可用。

在 Level 2 层面，当模型判断需要加载某个 Skill 时，Context Injector 将对应的 SKILL.md 正文插入到本次对话的临时上下文中。这不是常驻的，而是按需加载，与 Claude Code 的行为一致。

手动触发层面，可以在 gptel buffer 中提供补全接口，让用户通过 /skill-name 命令显式调用 Skills，参数映射到 Skill 中定义的占位符。

系统持续收集 Skills 的运行数据。每次 Skill 执行后，Run Ticket 中记录了执行时间、输入参数、输出结果、是否出错、是否被用户修改等信息。Skill-Analyzer（一个专门的元 Skill）定期扫描这些数据，生成分析报告。

分析报告包含：常见的失败模式、冗余的步骤、较弱的提示词段落、缺失的验证步骤、潜在风险区域。关键在于：这个阶段只生成报告，不修改任何 Skill Spec。

当运行数据积累到一定程度——比如某个 Skill 失败率超过阈值，或者用户频繁修改某个 Skill 的输出——系统触发 Skill-Refactor 元 Skill。

Skill-Refactor 读取 Skill Spec 和分析报告，生成改进提案。提案包括：建议的修改内容、结构化的 diff、风险分类、预期收益。提案以 Org 子树的形式存储在 proposals/ 目录下，包含 TARGET_SKILL、RISK_LEVEL、BASED_ONRUNS 等属性，以及详细的修改说明和 diff。

提案生成后，进入治理评估阶段。Skill-Governance 元 Skill 根据软标签（EFFECT、RISK_LEVEL 等）判断提案的风险级别。

如果风险低（比如只是优化提示词表述），系统建议自动批准。如果风险中等（比如修改了调用权限或增加了新的副作用），系统提示人工确认。如果风险高（比如涉及不可逆的副作用或权限扩大），系统标记为必须人工审核。

Human-in-the-Loop 体现在：每个提案都需要人点击 Approve/Reject/Edit。批准后，系统生成 patch 并应用到 Skill Spec，同时生成 changelog，记录修改来源和批准人。

这种「观察→提案→治理→确认→提交」的自举循环，让 Org Skills 系统能够随着使用不断进化，同时通过治理关卡防止失控。

Org Mode 的核心优势可以归结为三点。第一，可编译的 Spec——Properties 和结构化元数据让 Skill 定义既是人类可读的文档，也是机器可解析的代码。第二，可执行的代码层——Babel 让脚本外置但不丢失可读性，与 Claude Code 的 Level 3 设计对齐。第三，可追踪的计划——TODO、CHECKLIST、LOGBOOK 让 Skills 的执行历史和演化过程得以沉淀，这是 Markdown 无法提供的能力。

但这些只是方法，不是目的。真正的目标是构建一个以 Emacs 为核心、流程可控的、Human-in-the-Loop 的知识生产体系。在这个体系中，AI 不是替代人类思考的工具，而是放大人类思考能力的协作伙伴。每一次 AI 输出都以提案的形式出现，每一份文档都有可追溯的创作轨迹，每一个 Skill 都在使用中不断进化。

最后，抛出一个开放性问题：真正重要的到底是什么？

很多人认为 AI 的未来是自动编程——让 AI 写出更好的代码。但 AI 的未来更可能是面向文档的。LLM 最擅长响应的是自然语言，是文本，是结构化的文档。代码只是一种形式化的内容，有表达的边界；而文本是思想的边界，是人类表达的极限。

更进一步，AI 要实现真正的自举能力，需要通过文档自举而不是代码自举。一个 Skill 产生的输出——提案、决策记录、运行分析——本身就是可以被 AI 读取、学习、改进的知识资产。当把 Skill 的定义、执行、演化全部沉淀为 Org 文档时，实际上在构建一个「AI 知识资产的操作系统」。

未来的 AI 应用，不会止步于「更好的代码补全」或「更快的任务执行」。它会是这样的形态：一个文档驱动的世界——所有的流程、知识、决策、演化都以结构化文档的形式存在，AI 和人类在同一个文档空间中协作、讨论、迭代。Emacs + Org，正是这个未来最早的践行者。

拥抱一切都文档化的未来，不是趋势，而是必然。