skill-typst-implementation（Typst文档实现技能）Skill 是什么？怎么安装使用？

Typst文档实现技能（skill-typst-implementation）：把 Typst 排版任务一键委托给子代理，编译、归档、提交全自动收尾

核心结论速览

这个技能是一个「薄包装器」：它本身不写排版逻辑，而是把 Typst 文档实现任务完整委托给专用的 typst-implementation-agent 子代理，自己负责前置状态更新与后置收尾。
它的触发条件非常明确：任务语言为 typst，或对某个 Typst 任务执行 /implement 命令。
它最大的差异化在于「技能内部后处理模式」：子代理返回后，状态更新、工件链接、Git 提交都在技能内部一次跑完，避免编排器与技能之间反复出现「继续」提示。
它内置了完整的工程化闭环：预飞行状态更新（PLANNED → IMPLEMENTING）、元数据文件交换、实现结果分级（implemented / partial / failed / blocked）、以及失败可续跑。
它适合已经在使用「任务—计划—实现」工作流的文档项目，尤其是需要定理环境、交叉引用、样式规范约束的学术或技术排版场景。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

技能基本信息

项目	内容
中文名	Typst文档实现技能
英文名	skill-typst-implementation
技能ID	12882
技能类型	薄包装器（委托型技能）
目标子代理	typst-implementation-agent
允许工具	Task、Bash、Edit、Read、Write

它解决什么问题

用 Typst 写论文、技术文档或书籍章节时，真正麻烦的往往不是某一句话怎么排，而是整条链路：先按计划逐阶段写 .typ 文件、遵守项目的样式指南与记号约定、处理定理环境与交叉引用、再执行 typst compile 验证能否干净编译、最后还要回写任务状态、登记产出工件、提交 Git。

这个技能的价值就是把这整条链路「打包托管」：你把一个已计划的 Typst 任务交给它，它负责调度子代理干活，并在子代理返回后自动完成所有后处理，让整个流程在编排器看来就是一次干净的调用。

一键安装思路与步骤

AI 技能提升开发效率的核心逻辑是「一次安装、长期复用」——把领域知识（Typst 样式规范、模板、编译指南）预先沉淀成技能与上下文档，之后每次任务都不用重新交代背景。

确认运行环境：需要一个支持技能（skills）与子代理（agents）机制的 AI 编程环境，本技能的触发方式与目录约定均基于 .claude/skills/ 与 .claude/agents/ 体系。具体客户端版本要求以官方说明为准。
放置技能文件：将技能定义（含 name: skill-typst-implementation、description、allowed-tools 的 frontmatter 与正文说明）放入技能目录中。安装命令或市场入口以官方说明为准。
准备子代理：确认 typst-implementation-agent 已存在于 .claude/agents/。这一点很关键——技能通过 Task 工具调用子代理，而不是 Skill(子代理名)；后者只能调用技能目录中的技能，会直接失败。
准备项目上下文文件：技能原始上下文依赖一系列 Typst 专属文件，包括项目 README、typst-style-guide.md、notation-conventions.md、document-structure.md、theorem-environments.md、cross-references.md、chapter-template.md、compilation-guide.md 等。缺少这些文件虽然不一定导致失败，但子代理的排版一致性会明显下降。
本地安装 Typst 编译器：子代理会执行 typst compile、typst watch 一类命令来验证产物，因此机器上需可用 Typst CLI（安装方式以官方说明为准）。
准备任务数据：specs/state.json 中需存在该任务，且 language 字段为 typst，状态允许实现（planned / implementing / partial）。

如何验证是否生效

对某个 Typst 任务执行 /implement <任务号>，观察 specs/state.json 中该任务状态是否从 planned 变为 implementing。
观察 TODO.md 中的状态标记是否由 [PLANNED] 变为 [IMPLEMENTING]，完成后是否变为 [COMPLETED]。
观察项目目录下是否生成 .postflight-pending 标记文件，结束后是否生成并清理 .return-meta.json。
完成后检查是否出现 .typ 源文件、编译产物（PDF）与实现摘要三类工件，以及是否有对应的 Git 提交记录。

该技能的主要功能和特点

薄包装器 + 子代理委托：技能本身不承载排版细节，只负责状态管理与委托调度，把 Typst 专业知识集中在子代理侧，职责边界清晰。
技能内部后处理模式：子代理返回后，状态更新、工件链接、Git 提交全部在技能内部完成再返回，消除了「技能返回—编排器再催促继续」的往返问题。
三阶段预飞行准备：委托前先完成状态更新（implementing、last_updated、session_id、started）、TODO 标记切换、计划文件 Status 字段更新，并创建后处理标记文件。
严格的输入验证：校验任务号是否存在、语言是否为 typst、状态是否已 completed（已完成的直接报错拒绝），避免误覆盖已完成工作。
元数据文件交换：子代理把结果写入 .return-meta.json，技能从中读取 status、artifacts、phases_completed、completion_data 等字段，而不是靠解析控制台文本。
v1/v2 返回格式兼容：如果子代理误把 JSON 打到控制台而非写入文件，技能会记录警告但不中断流程，实现优雅降级。
分级结果处理：implemented 更新为 completed 并登记摘要工件；partial 保留 implementing 并写入 resume_phase 恢复点；failed 则不执行后处理以便重试。
上下文按需加载：上下文参考采用「引用而不急切加载」策略，由子代理按需读取样式指南、模式文档与编译指南，减少无关上下文占用。
收尾清理闭环：后处理完成后删除 .postflight-pending、.postflight-loop-guard、.return-meta.json，避免残留标记影响下一次运行。

和普通排版工具比，它强在「流程」而非「语法」：普通工具只负责把 .typ 编译成 PDF，而它把状态流转、工件登记、版本提交一并纳入。

如何使用该技能？

第 1 步：确认触发条件

两种方式触发：任务的语言字段为 typst；或对某个 Typst 任务执行 /implement 命令。二者满足其一即可。

第 2 步：准备输入

必需输入是 task_number（任务号），且该任务需存在于 specs/state.json。技能会自行读取 language、status、project_name、description 四个字段。

输入示例（概念示意）：

/implement 500
# 对应 specs/state.json 中 project_number = 500 的任务
# language: "typst"，status: "planned"

第 3 步：让技能自动完成预飞行

技能会依次把状态改为 implementing、把 TODO.md 标记改为 [IMPLEMENTING]、把最新计划文件（形如 specs/500_bimodal_docs/plans/implementation-*.md）的 Status 改为 [IMPLEMENTING]，并创建 .postflight-pending 标记。

第 4 步：子代理执行实现

技能通过 Task 工具拉起 typst-implementation-agent，传入任务上下文、委托上下文与计划文件路径。子代理随后：加载 Typst 上下文文件 → 创建或修改 .typ 文件 → 执行 typst compile 验证 → 生成实现摘要 → 写入 .return-meta.json → 返回简短文本摘要。

第 5 步：等待后处理

技能读取元数据文件，按状态分级处理：

implemented：状态置为 completed，写入 completion_summary 与 roadmap_items（如有），先用 select(.type == "summary" | not) 过滤旧摘要工件再追加新摘要，同时更新 TODO 与计划文件为 [COMPLETED]。
partial：保持 implementing，写入 resume_phase = 已完成阶段 + 1，计划文件改为 [PARTIAL]，提示可用 /implement <任务号> 续跑。
failed / blocked：不执行后处理，状态保留为 implementing，便于重试。

第 6 步：Git 提交与清理

技能执行 git add -A 并提交，提交信息包含任务号与 Session: <session_id>；随后删除标记文件与元数据文件。

输出示例（成功）

Typst implementation completed for task 500:
- All 4 phases executed, document compiles cleanly
- Created PDF at Theories/Bimodal/typst/BimodalReference.pdf
- Created summary at specs/500_bimodal_docs/summaries/implementation-summary-20260118.md
- Status updated to [COMPLETED]

输出示例（部分完成）

Typst implementation partially completed for task 500:
- Phases 1-2 of 3 executed
- Phase 3 blocked: unknown variable 'customcmd'
- Status remains [IMPLEMENTING] - run /implement 500 to resume

同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
skill-typst-implementation（本技能）	任务化的 Typst 实现委托器	预飞行状态更新、子代理委托、编译验证、元数据回写、工件登记、Git 提交、失败续跑	需具备技能与子代理机制、`specs/state.json` 任务数据、Typst CLI；配置项较多	多阶段文档项目、学术论文与技术书籍、需要状态可追溯的团队协作	优势是流程闭环完整、可断点续跑；不足是依赖前置工程结构，轻量一次性排版显得偏重
Typst 官方 CLI 手动编译	排版引擎本身	`typst compile`、`typst watch` 编译与热更新	门槛低，安装 CLI 即可，无需任务系统	单文件快速出稿、本地实时预览	优势是简单直接、完全可控；不足是没有状态管理、无规范约束、无自动归档与提交
通用 AI 助手直接写 Typst 代码	对话式代码生成	按提示生成或修改 `.typ` 片段	门槛最低，粘贴需求即可	临时片段、语法答疑、小范围改写	优势是灵活、零配置；不足是缺少项目级样式约束、无编译验证、无状态与版本可追溯
传统 LaTeX 工具链 + 编辑器	成熟排版生态	宏包体系、参考文献、公式排版	中等偏高，需要熟悉 TeX 生态	期刊投稿模板、长期维护的大型文档	优势是生态成熟、模板丰富；不足是编译链复杂、AI 协作链路不如 Typst 顺畅

从对比可以看出，本技能并非要取代编译器，而是在编译器之上补一层「工程管理」：谁来改、改到哪一步、产出放在哪里、有没有提交，全都有据可查。

该技能的典型应用场景与实际体验情况

场景一：理论文档与论文排版（学术研究者）

痛点：公式、记号、定理环境需要严格统一，人工维护容易前后不一致。
使用方式：把任务语言标记为 typst，执行 /implement；子代理按 theorem-environments.md、notation-conventions.md 与 notation-standards.md 的约定生成章节，再用 typst compile 验证。
实际体验：上手难度中等偏低，只要任务与计划准备好，基本是「发一条命令等结果」。效果上，记号一致性明显优于逐句对话式生成；注意点是上下文文件缺失时会退化为通用排版风格，建议先补齐规范文件。

场景二：技术书籍多章节批量生产（技术作者/内容团队）

痛点：章节模板、交叉引用、编号体系需要跨文件统一，逐章人工核对成本高。
使用方式：以 chapter-template.md 为基线，按计划文件逐阶段推进；技能会把每个阶段完成度写入 phases_completed / phases_total。
实际体验：多阶段任务的分级结果机制很实用，做到一半被卡住时状态仍是 implementing 并带 resume_phase，重跑即可从断点继续，不用从第一章重来。注意跨引用改动较大时要预留一次完整编译验证的时间。

场景三：需要审计痕迹的文档工程（工程/研究团队）

痛点：文档改动分散，谁改了什么、产物在哪里、状态有没有同步，难以追踪。
使用方式：完全依赖技能的状态机：PLANNED → IMPLEMENTING → COMPLETED / PARTIAL，配合 .return-meta.json 与 Git 提交记录。
实际体验：可追溯性是这个技能最被低估的部分，摘要工件会被去重后重新登记，不会堆积大量重复记录。注意点是它假设项目已采用 specs/ 目录约定，迁移成本需要提前评估。

场景四：长篇排版的断点续跑（独立开发者）

痛点：一次实现动辄几十分钟，中途出现未知变量或命令错误就前功尽弃。
使用方式：遇到 blocked 时修掉报错源（如示例中的未知变量），再次 /implement <任务号>。
实际体验：失败不执行后处理、状态保留为 implementing 的设计很贴合真实排错节奏；默认超时为 3600 秒，超时会返回部分状态，建议把大任务切分为更小的阶段。

该技能能为用户带来的价值

流程自动化带来的效率提升：把「改状态、写 TODO、更新计划、登记工件、提交代码」这些机械动作从每次实现中剥离出来，一次委托完成一整套收尾动作，人工只需关注排版内容本身。
降低 Typst 工程化门槛：样式指南、记号约定、定理环境模式、编译指南都被沉淀为可复用的上下文档，新成员不必从零理解项目规范，跟着任务跑即可。
可追溯性带来的长期价值：状态机、元数据文件、摘要工件与 Git 提交共同构成完整审计链，几个月后回看仍能说清每个文档版本是怎么来的。
失败成本可控：partial 结果会记录恢复点，failed 不污染状态，避免「跑到一半崩掉、状态还得手工修」的二次损耗。
消除编排往返损耗：技能内部后处理模式让「技能返回—编排器催促继续」的循环消失，长流程任务更稳定。
可量化的收益方向：对多阶段文档任务，减少的是每阶段的状态维护与提交操作次数；对频繁中断的长篇排版，减少的是重复执行已完成阶段的次数。具体节省比例取决于任务阶段数与中断频率，需结合自身项目实测。

常见问题 FAQ

Q1：这个技能具体怎么安装？装完怎么确认能用了？

把技能定义放入技能目录、确认 typst-implementation-agent 存在于 .claude/agents/、本地可执行 Typst CLI，并在 specs/state.json 中准备好语言为 typst 的任务。验证方式是对该任务执行 /implement <任务号>，观察状态是否从 planned 变为 implementing、TODO.md 标记是否切换、结束后是否出现摘要工件与 Git 提交。安装命令与目录约定以官方说明为准。

Q2：它是收费的吗？

技能详情中未包含任何价格、订阅或授权信息，本技能属于技能定义与子代理的工程化封装，本身不涉及计费逻辑。是否需要付费取决于你使用的 AI 运行环境与 Typst 工具链，具体以官方说明为准。

Q3：为什么不能直接用 Skill(typst-implementation-agent) 调用子代理？

因为 Skill 工具只能调用技能目录（.claude/skills/）中的技能，而子代理位于 .claude/agents/。本技能明确规定必须使用 Task 工具，参数中指定 subagent_type: "typst-implementation-agent"，用错工具会直接失败。

Q4：中途失败了，要从头再来吗？

不需要。如果子代理返回 partial，技能会保持状态为 implementing 并写入 resume_phase（已完成阶段 + 1），修掉报错源后再次执行 /implement <任务号> 即可从下一阶段继续。只有 failed / blocked 时会保留状态以便重试，但不会推进阶段。

Q5：它和直接让 AI 写 .typ 代码、或者自己跑 typst compile 有什么区别，该怎么选？

如果你只是要一小段 Typst 语法或临时改几行，直接对话更快；如果是多阶段、有样式规范、需要状态与版本可追溯的文档工程，本技能的预飞行校验、元数据交换、分级结果与自动提交就能显著省事。它并不替代 Typst 编译器，而是在编译器之上补了一层流程管理。