关于 grove-spec-writing
用于在 Grove 生态中编写和验证技术规格的技能。它规定文档结构、视觉元素、写作规范和检查清单，面向编写内部规格及实施计划的开发者。
主要功能
- 01规定规格结构与 frontmatter
- 02ASCII 艺术标题和图表
- 03提供界面草图与状态图指南
- 04语气和风格检查清单
- 05Grove 相关文档编写指南
适用场景
- 01编写新的技术规格
- 02检查规格内容是否完整
- 03统一现有规格的格式
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/grove-spec-writing确认已加载。
详细介绍
Grove 规范编写
Grove 生态系统中编写技术规范的全面指南。使用此技能创建具有故事书条目风格的新规范，或验证并规范化现有规范。
何时启用
- 创建新的技术规范
- 检查现有规范是否完整
- 为缺少 ASCII 艺术标题的规范添加标题
- 为以文字为主的规范添加图表、示意图或视觉元素
- 统一规范文件的 frontmatter
- 在最终定稿前根据 Grove 标准验证规范
将规范写成故事书条目
Grove 规范不只是技术文档。它们是更大叙事中的故事书条目。每份规范都应让人感觉像是翻开了一本精美的森林图鉴。
公式：
- 封面页（frontmatter + ASCII 艺术 + 标语）
- 引言（这是什么，以及它在自然界和 Grove 中的意义）
- 旅程（架构、流程、实现）
- 细节（API、架构、 安全性）
- 前进之路（实现检查清单）
必需结构
1. Frontmatter（必需）
每份规范都必须使用以下确切的 frontmatter 格式：
---
aliases: []
date created: [Day], [Month] [Ordinal] [Year]
date modified: [Day], [Month] [Ordinal] [Year]
tags:
- primary-domain
- tech-stack
- category
type: tech-spec
---
日期格式示例：
Monday, December 29th 2025Saturday, January 4th 2026
类型选项：
tech-spec— 技术规范（最常见）implementation-plan— 分步实现指南index— 索引／导航文档
2. ASCII 艺术标题（必需）
紧接 frontmatter 之后，添加一个代码块，其中包含能直观表现概念的 ASCII 艺术：
# [Name] — [Short Description]
ASCII ART HERE
representing the concept
in a visual way
> *Poetic tagline in italics*
优秀的 ASCII 艺术：
- 与自然隐喻相关（森林、花园等）
- 以视觉方式表现概念（备份用层叠图，分析用同心圆）
- 使用制表符绘制字符：
─│┌┐└┘├┤┬┴┼╭╮╰╯ - 适度使用自然主题表情符号：
🌲🌿🍂✨🌸 - 包含富有诗意的标语或格言
优秀规范示例：
Wisp（鬼火）：
🌲 🌲 🌲
\ | /
\ | /
✨
╱ ╲
╱ ╲
╱ · ╲
╱ · ╲
╱ · ╲
· · ·
gentle
guiding
light
Patina（分层备份）：
╭───────────────────╮
╭┤ ┌─────────────┐ ├╮
╭┤│ │ 2026-01-05 │ │├╮
│││ │ ▓▓▓▓▓▓▓▓▓▓ │ │││
│││ │ ▒▒▒▒▒▒▒▒▒▒ │ │││
│││ │ ░░░░░░░░░░ │ │││
│││ │ ·········· │ │││
╰┴┴──└─────────────┘──┴┴╯
╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱
──────────────────────────────
~~~~~~~~ oxidation layer ~~~~~~~~
Age as armor. Time as protection.
Heartwood（树木年轮）：
╭──────────╮
╭──│ ╭──────╮ │──╮
╭─│ │ │ ╭──╮ │ │ │─╮
│ │ │ │ │♥ │ │ │ │ │
╰─│ │ │ ╰──╯ │ │ │─╯
╰──│ ╰──────╯ │──╯
╰──────────╯
every ring: a year, a story, a layer of growth
The center that holds it all.
3. 引言部分
ASCII 艺术标题之后：
> *Poetic tagline repeated*
[2-3 sentence description of what this is in the Grove ecosystem]
**Public Name:** [Name]
**Internal Name:** Grove[Name]
**Domain:** `name.grove.place`
**Repository:** [Link if applicable]
**Last Updated:** [Month Year]
[1-2 paragraphs explaining the nature metaphor and how it applies]
---
4. 正文部分
使用清晰的标题组织内容。包括：
- 概述／目标 — 此系统的功能
- 架构 — 系统的构建方式（附图表！）
- 技术栈 — 依赖项、框架
- API／架构 — 技术细节
- 安全性 — 重要注意事项
- 实现检查清单 — 明确的行动项
必需的视觉元素
流程图
每份描述流程的规范都必须至少包含一个 ASCII 流程图：
┌─────────────────────────────────────────────────────────────────────┐
│ Client Sites │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Site A │ │ Site B │ │ Site C │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼─────────────────┼─────────────────┼───────────────────────┘
│ │ │
│ 1. Request │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ Central Service │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ Handler A │ │ Handler B │ │
│ └─────────────────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
制表符绘制参考：
- 转角：
┌ ┐ └ ┘（直角）或╭ ╮ ╰ ╯（圆角） - 线条：
─ │ ═ ║ - 连接处：
├ ┤ ┬ ┴ ┼ - 箭头：
→ ← ↑ ↓ ▶ ◀ ▲ ▼
UI 示意图
描述用户界面的规范必须包含 ASCII 示意图：
┌─────────────────────────────────────────────────────────────────┐
│ ✧ Panel Title [×] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ Label ────────────────────────────────────────────────┐ │
│ │ Content here with proper spacing │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Input field... [↵] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ─────────────────────────────────────────────────────────── │
│ [ Action A ] [ Action B ✦ ] │
│ │
└─────────────────────────────────────────────────────────────────┘
状态图
适用于具有多种状态的功能：
Idle: Analyzing: Success:
. * . . * . * . analyzing . * *
. _ . . \ | / . * /|\ .
/ \ * . -- (o.o) -- thinking * / | \ *
/ ~ ~ \ . . / | \ /__|__\
/ \______ ~~~~~~~~~~~~~~~~~ ~~~~/ \~~~~
~~~~~~~~~~~~~~~~~~~ words flowing... all clear
对比表格
使用表格对比选项、状态或配置：
| Feature | Seedling | Sapling | Oak | Evergreen |
|---------|----------|---------|-----|-----------|
| Posts | 50 | 250 | ∞ | ∞ |
| Storage | 1 GB | 5 GB | 20 GB | 100 GB |
| Themes | 3 | 10 | All | All + custom |
时间线／保留期限图
适用于涉及时间的内容：
TODAY 12 WEEKS AGO
│ │
▼ ▼
┌─┬─┬─┬─┬─┬─┬─┐ ┌─┐
│█│█│█│█│█│█│█│ ◀── Daily backups (7 days) │░│
└─┴─┴─┴─┴─┴─┴─┘ └─┘
S M T W T F S
验证检查清单
定稿前，请验证每份规范：
结构
- 包含具有所有必需字段的 frontmatter
- 包含
aliases: []（即使为空） - 日期格式正确（星期、月份、序数日期、年份）
-
type: tech-spec或适当的类型 - frontmatter 后包含 ASCII 艺术标题
- 以斜体标注富有诗意的标语
- 列出公开／内部名称
- 指定领域（如适用）
视觉内容
- 至少包含一个 ASCII 流程图（如果以流程为主）
- 包含 UI 示意图（如果描述界面）
- 在适当情况下使用表格进行对比
- 使用代码块呈现技术细节
- 不要出现没有视觉间隔的大段文字
语气（完整列表请参阅 owl-archive/references/anti-patterns.md）
- 不使用长破折号（改用句号或逗号）
- 不使用“不是 X，而是 Y”句式或其变体（“不是 X。不是 Y。只是 Z。”“这个 X？一个 Y。”）
- 不使用 AI 腔词语（robust、seamless、leverage、delve、utilize、streamline 等）
- 不使用“serves as”/“stands as”/“marks a”。改用简单动词
- 不使用填充性过渡语（Furthermore、Moreover、It's worth noting、Notably）
- 不使用一连串动名词片段，也不使用粗体开头的项目符号句式
- 不制造悬念（“Here's the kicker”“Here's the thing”）
- 不使用陈旧的隐喻（不要在每个部分重复同一个隐喻）
- 段落简短
- 诗意的结尾要水到渠成，不要刻意为之
完整性
- 概述/目标部分
- 架构图
- 技术细节（API、架构）
- 安全注意事项
- 实施检查清单
创建 ASCII 艺术图
流程
- 确定核心隐喻 — 它代表什么自然事物？
- 勾勒概念 — 什么样的视觉效果能让人一眼看懂？
- 选择字符 — 制框线条、Emoji 或创意 ASCII 字符
- 逐层构建 — 从轮廓开始，再添加细节和装饰
- 添加标语 — 用一句诗意的话点明本质
字符集
制框线条（安全、一致）：
┌─────┬─────┐ ╭─────╮
│ │ │ │ │
├─────┼─────┤ ╰─────╯
│ │ │
└─────┴─────┘
线条和箭头：
→ ← ↑ ↓ ↔ ↕
▶ ◀ ▲ ▼
⟿ ⟸ ⟹
自然主题 Emoji（少量使用）：
🌲 🌳 🌿 🍂 🍃 🌸 🌺 🌻 🌷 🌱 🍄
☀️ 🌤️ ⭐ ✨ 💧 🔥
🦋 🐛 🐌
装饰字符：
· ∙ • ° ˚ ∘
~ ≈ ∿
═ ║ ╔ ╗ ╚ ╝
░ ▒ ▓ █
提示
- ASCII 艺术图高度不超过 20 行
- 在代码块内将图案居中
- 留出呼吸空间（上下留空行）
- 使用等宽字体进行测试
- 考虑移动设备上的显示效果（越简单越好）
示例：完整的规范标题
---
aliases: []
date created: Monday, January 6th 2026
date modified: Monday, January 13th 2026
tags:
- support
- user-communication
- cloudflare-workers
type: tech-spec
---
# Porch — Support System
🏠
___│___
│ │
~~~~~~│ PORCH │~~~~~~
╱│_______│╲
╱ ╲
╱ ┌───┐ ╲
╱ │ ☕ │ ╲
╱ └───┘ 👤 ╲
════════════════════════
台阶
请坐。我们一起想办法。
> *Have a seat on the porch. We'll figure it out together.*
Grove's front porch: a warm, accessible space where users sit down and have a conversation. Not a corporate help desk with ticket numbers. A porch where you chat with the grove keeper about what's going on.
**Public Name:** Porch
**Internal Name:** GrovePorch
**Domain:** `porch.grove.place`
**Status:** Planned (Launch Priority)
A porch is where you sit and talk. You come up the steps, have a seat, and the grove keeper comes out to chat. It's not a ticket counter. It's two people on a porch, figuring things out together.
---
与其他技能集成
编写规范之前
- walking-through-the-grove — 如果要为新功能命名，请先完成命名流程
- grove-ui-design — 如果规范涉及 UI，请先了解设计模式
编写过程中
- grove-documentation — 全文采用 Grove 语气，避免 AI 腔
编写之后
- grove-spec-writing（本技能）— 运行验证检查清单
- 以全新视角审阅：它读起来像故事书中的一篇吗？
何时改用 museum-documentation
此技能（grove-spec-writing）适用于内部技术规范：架构决策、系统设计和实施计划。面向开发者的文档。
编写供希望了解情况的 Wanderers阅读的内容时，请使用museum-documentation：
| 使用 grove-spec-writing | 使用 museum-documentation |
|---|---|
| 技术规范 | 为好奇的访客介绍“工作原理” |
| 架构决策 | 代码库导览 |
| 实施计划 | 知识库展品 |
| 内部系统文档 | 叙事式技术说明 |
如果读者是要实现某项功能的开发者，请使用此技能。 如果读者是探索森林的 Wanderer，请使用 museum-documentation。
快速参考
| 元素 | 必需 | 位置 |
|---|---|---|
| Frontmatter | 是 | 文件顶部 |
| ASCII 艺术图标题 | 是 | Frontmatter 之后 |
| 诗意标语 | 是 | ASCII 艺术图之后 |
| 公共/内部名称 | 是 | 引言 |
| 架构图 | 适用时 | 正文 |
| UI 模型图 | 有 UI 时 | 正文 |
| 实施检查清单 | 是 | 规范末尾 |
好的规范值得你在凌晨 2 点细读。让它美一些。
评论
支持 Markdown