Kaynağa Gözat

feat: Comprehensive documentation update and claude-skills module enhancement

tukuaiai 1 ay önce
ebeveyn
işleme
ae7d6da267

+ 46 - 69
libs/README.md

@@ -1,90 +1,67 @@
-# 📦 通用库与外部集成 (Libs)
+# 📦 通用库与外部集成 (libs)
 
-`libs/` 目录存放项目的通用库代码和外部集成模块,用于项目内部模块化和工具复用。
+`libs/` 用来放两类东西:
+
+1. **内部可复用的胶水代码**:小而稳、低耦合、可替换(`common/`)
+2. **第三方工具与外部集成**:尽量保持原样、只做最薄适配(`external/`)
+
+`database/` 预留未来的数据持久化层(当前仅占位)。
 
 ## 目录结构
 
 ```
 libs/
-├── README.md                # 本文件
-├── common/                  # 通用功能模块
+├── README.md
+├── common/
+│   ├── README.md
 │   ├── __init__.py
-│   ├── models/              # 数据模型定义
+│   ├── models/
 │   │   └── __init__.py
-│   └── utils/               # 工具函数
-│       └── backups/         # 备份工具
-├── database/                # 数据库相关模块(预留)
+│   └── utils/
+│       └── backups/
+│           ├── README.md
+│           ├── 快速备份.py
+│           └── 一键备份.sh
+├── database/
+│   ├── README.md
 │   └── .gitkeep
-└── external/                # 外部集成与第三方工具
-    ├── prompts-library/     # 提示词库管理工具
-    ├── my-nvim/             # Neovim 配置
-    └── XHS-image-to-PDF-conversion/  # 小红书图片转 PDF
+└── external/
+    ├── README.md
+    ├── prompts-library/
+    ├── my-nvim/
+    ├── XHS-image-to-PDF-conversion/
+    └── .gitkeep
 ```
 
-## 各子目录详解
-
-### `common/` - 通用功能模块
-
-存放项目内部共享的通用代码:
+## 子目录职责与边界
 
-- `models/` - 数据模型定义,如 Pydantic 模型、数据类等
-- `utils/` - 工具函数,如文件处理、格式转换等
-- `utils/backups/` - 备份相关工具函数
+### `common/`:内部通用模块
 
-### `database/` - 数据库模块(预留)
+- 入口:[`common/README.md`](./common/README.md)
+- 只放 **可复用** 的基础能力:模型、工具函数、脚本等
+- 不要把业务逻辑、项目临时代码塞进来
+- 约定:新增/调整能力时,同步更新 `libs/common/README.md`
 
-预留的数据库适配层,用于未来扩展数据持久化功能。
+### `database/`:数据库适配层(预留)
 
-### `external/` - 外部集成
-
-#### `prompts-library/` - 提示词库管理工具
-
-Excel ↔ Markdown 提示词互转工具:
-
-```bash
-cd libs/external/prompts-library
-pip install -r requirements.txt
-python main.py
-```
+- 入口:[`database/README.md`](./database/README.md)
+- 目标是把“存储细节”关进盒子里:连接、迁移、查询适配、事务边界
+- 约定:实现前先写清楚目录结构与边界(见 `libs/database/README.md`)
 
-功能:
-- Excel 转 Markdown:批量将表格提示词转为 .md 文件
-- Markdown 转 Excel:将 .md 文件汇总到表格中
-- 支持分类、标签、版本管理
+### `external/`:第三方工具与外部集成
 
-#### `my-nvim/` - Neovim 配置
+- 入口:[`external/README.md`](./external/README.md)
+- 尽量保持第三方代码原样,避免“魔改后不可升级”
+- 每个工具目录至少包含:`README.md`(用途/入口/依赖)与许可证/来源说明
+- 约定:新增外部工具时,同步更新 `libs/external/README.md`
 
-个人 Neovim 配置,基于 LazyVim,包含:
-- LSP 配置
-- 代码补全
-- 文件导航
-- Git 集成
+## 常用入口
 
-#### `XHS-image-to-PDF-conversion/` - 小红书图片转 PDF
+- 提示词批量管理:[`external/prompts-library/`](./external/prompts-library/)(配合 `../prompts/` 使用)
+- 备份工具:优先使用仓库根目录的 `backups/`(当前与 `libs/common/utils/backups/` 内容一致)
 
-将小红书图片合并为 PDF 的工具:
+## 贡献约定(最小要求)
 
-```bash
-cd libs/external/XHS-image-to-PDF-conversion
-pip install -r requirements.txt
-python pdf.py
-```
-
-## 使用原则
-
-1. **分层边界**: `common/` 只放通用代码,业务逻辑放其他地方
-2. **单一职责**: 每个模块只做一件事
-3. **依赖记录**: 新增外部依赖时更新对应的 `requirements.txt`
-4. **文档同步**: 新增模块时更新本 README
-
-## 新增模块指南
-
-```bash
-# 新增通用模块
-mkdir -p libs/common/新模块名
-touch libs/common/新模块名/__init__.py
-
-# 新增外部集成
-mkdir -p libs/external/工具名
-echo "# 工具说明" > libs/external/工具名/README.md
-```
+1. 新增模块先定义职责边界,再写代码/文档
+2. 新增依赖记录安装方式与最低版本(必要时补充到 `documents/工具集.md`)
+3. 目录结构/职责变化时,更新对应 README,保证“文档即真相源”

+ 27 - 14
libs/common/README.md

@@ -1,27 +1,40 @@
-# 🔧 通用功能模块 (Common)
+# 🔧 libs/common:通用模块
 
-存放项目内部共享的通用代码,包括数据模型和工具函数
+`libs/common/` 放的是项目内部可复用的“胶水代码”:**小而稳、低耦合、可替换**。这里的目标不是堆功能,而是为仓库提供少量可靠的基础能力
 
 ## 目录结构
 
 ```
-common/
+libs/common/
+├── README.md
 ├── __init__.py
-├── models/          # 数据模型定义
+├── models/                 # 预留:数据模型(当前仅占位)
 │   └── __init__.py
-└── utils/           # 工具函数
-    └── backups/     # 备份工具
+└── utils/
+    └── backups/            # 基于 .gitignore 的快速备份工具
+        ├── README.md
+        ├── 快速备份.py
+        └── 一键备份.sh
 ```
 
-## 子模块
+## 现有内容
 
-- `models/` - Pydantic 模型、数据类等
-- `utils/` - 文件处理、格式转换等工具函数
-- `utils/backups/` - 备份相关工具
+- `utils/backups/`:快速备份工具(当前与仓库根目录 [`backups/`](../../backups/) 内容一致,用于避免脚本散落各处)
 
-## 使用
+## 约束与约定
 
-```python
-from libs.common.models import YourModel
-from libs.common.utils import your_function
+1. **不放业务逻辑**:`common/` 只提供基础能力与工具
+2. **接口要稳**:一旦被引用,就把它当作公开 API 对待
+3. **可审计输出**:脚本/工具的输出要可复盘(明确输入、输出路径、失败原因)
+4. **新增即文档**:新增模块/目录必须同步更新本 README 与 `libs/README.md`
+
+## 使用方式(当前推荐)
+
+本目录的内容目前主要以“脚本/工具”形式存在,推荐直接运行:
+
+```bash
+# 备份当前仓库(建议优先使用根目录 backups/ 入口)
+python3 backups/快速备份.py
 ```
+
+更多参数与说明见:[`../../backups/README.md`](../../backups/README.md)。

+ 16 - 14
libs/database/README.md

@@ -1,22 +1,24 @@
-# 🗄️ 数据库模块 (Database)
+# 🗄️ libs/database:数据库适配层(预留)
 
-预留的数据库适配层,用于未来扩展数据持久化功能
+`libs/database/` 预留给未来的“存储适配层”。目标是把数据库的细节(连接、迁移、事务、查询)封装在一个清晰边界内,避免业务代码到处散落 SQL/ORM
 
-## 规划用途
+## 设计边界(先写清楚再实现)
 
-- 数据库连接管理
-- ORM 模型定义
-- 数据迁移脚本
-- 查询工具函数
+- 这里负责:连接管理、迁移脚本、ORM/SQL 模型、统一的查询/事务封装
+- 这里不负责:业务规则、HTTP/API 逻辑、领域对象的复杂编排
 
-## 待实现
-
-当前为占位目录,后续可添加:
+## 推荐目录结构(落地时按需取舍)
 
 ```
-database/
+libs/database/
+├── README.md
 ├── __init__.py
-├── connection.py    # 连接管理
-├── models.py        # ORM 模型
-└── migrations/      # 迁移脚本
+├── connection.py             # 连接与池化
+├── migrations/               # 迁移脚本(Alembic/Flyway/自研均可)
+├── repositories/             # 数据访问层(可选)
+└── models/                   # ORM 模型或 SQL schema(可选)
 ```
+
+## 何时开始实现
+
+当仓库出现“需要长期保存/查询的数据”且 **文件系统不够用** 时,再把这一层落地;否则保持为空,避免过早引入复杂度。

+ 21 - 19
libs/external/README.md

@@ -1,29 +1,31 @@
-# 🔌 外部集成模块 (External)
+# 🔌 libs/external:外部集成与第三方工具
 
-存放第三方工具、外部依赖和集成模块。
+`libs/external/` 用来收纳第三方工具、外部依赖与集成模块。核心原则是:
+
+- **尽量原样保留**:避免“魔改后不可升级”
+- **隔离依赖与风险**:外部工具的依赖不要污染主仓库
+- **可追溯**:来源、许可证、用法要写清楚
 
 ## 目录结构
 
 ```
-external/
-├── prompts-library/              # 提示词库管理工具(Excel ↔ MD 互转)
-├── my-nvim/                      # Neovim 配置
-└── XHS-image-to-PDF-conversion/  # 小红书图片转 PDF
+libs/external/
+├── README.md
+├── prompts-library/                 # 提示词库管理工具(Excel ↔ Markdown)
+├── my-nvim/                         # Neovim 配置(含 nvim-config/)
+├── XHS-image-to-PDF-conversion/     # 图片合并 PDF 工具
+└── .gitkeep
 ```
 
-## 工具说明
-
-| 工具 | 用途 | 使用方法 |
-|------|------|----------|
-| `prompts-library` | 提示词 Excel/MD 互转 | `python main.py` |
-| `my-nvim` | Neovim 配置 | 复制到 `~/.config/nvim` |
-| `XHS-image-to-PDF-conversion` | 图片合并 PDF | `python pdf.py` |
+## 工具清单(入口与文档)
 
-## 新增外部工具
+- `prompts-library/`:提示词 Excel ↔ Markdown 批量互转与索引生成(详见 [`prompts-library/README.md`](./prompts-library/README.md))
+- `my-nvim/`:个人 Neovim 配置(详见 [`my-nvim/README.md`](./my-nvim/README.md))
+- `XHS-image-to-PDF-conversion/`:图片合并 PDF(详见 [`XHS-image-to-PDF-conversion/README.md`](./XHS-image-to-PDF-conversion/README.md))
 
-```bash
-mkdir -p libs/external/工具名
-echo "# 工具说明" > libs/external/工具名/README.md
-```
+## 新增外部工具(最小清单)
 
-新增时请注明来源、许可证和依赖。
+1. 创建目录:`libs/external/<tool-name>/`
+2. 必备文件:`README.md`(用途/入口/依赖/输入输出)、许可证与来源说明(如 `LICENSE` / `SOURCE.md`)
+3. 依赖约束:尽量使用工具自带的虚拟环境/容器化方式,不影响仓库其他部分
+4. 文档同步:在本 README 增加一行工具说明,保证可发现性

+ 54 - 52
prompts/README.md

@@ -1,81 +1,83 @@
-# 💡 AI 提示词库 (Prompts Library)
+# 💡 AI 提示词库 (Prompts)
 
-`prompts/` 目录是本项目中 AI 提示词的核心资产,包含 **40+ 个**经过精心设计和分类的提示词,用于指导 AI 进行各种任务
+`prompts/` 存放本仓库的提示词资产:用 **系统提示词** 约束 AI 的边界与品味,用 **任务提示词** 驱动「需求澄清 → 计划 → 执行 → 复盘」的开发流水线
 
-## 目录结构
+## 推荐使用路径(从 0 到可控)
+
+1. **先定边界**:选择一个系统提示词版本(推荐 `v8` 或 `v10`)。
+2. **再跑流程**:在具体任务里按阶段选用 `coding_prompts/`(澄清 / 计划 / 执行 / 复盘)。
+3. **最后产品化**:当你在某领域反复做同类工作,把「提示词 + 资料」升级为 `skills/` 里的 Skill(更可复用、更稳定)。
+
+## 目录结构(以仓库真实目录为准)
 
 ```
 prompts/
-├── README.md                # 本文件
-├── coding_prompts/          # 编程与代码生成相关提示词(40+ 个)
-│   ├── index.md             # 提示词索引与版本矩阵
-│   ├── plan提示词.md         # 实施计划生成
-│   ├── 系统架构可视化生成Mermaid.md
+├── README.md
+├── coding_prompts/                 # 编程/研发提示词(当前 41 个 .md)
+│   ├── index.md                    # 自动生成的索引与版本矩阵(请勿手改)
+│   ├── 标准化流程.md
 │   ├── 项目上下文文档生成.md
+│   ├── 智能需求理解与研发导航引擎.md
+│   └── ...
+├── system_prompts/                 # 系统提示词(CLAUDE 多版本 + 其他收集)
+│   ├── CLAUDE.md/                  # 1~10 版本目录(v9 目前仅占位)
+│   │   ├── 1/CLAUDE.md
+│   │   ├── 2/CLAUDE.md
+│   │   ├── ...
+│   │   ├── 9/AGENTS.md             # v9 当前没有 CLAUDE.md
+│   │   └── 10/CLAUDE.md
 │   └── ...
-├── system_prompts/          # AI 系统级提示词(10 个版本)
-│   └── CLAUDE.md/
-│       ├── 1/ ~ 10/         # 不同版本的系统提示词
-│       └── ...
-└── user_prompts/            # 用户自定义提示词
+└── user_prompts/                   # 用户自用/一次性提示词
     ├── ASCII图生成.md
     ├── 数据管道.md
     └── 项目变量与工具统一维护.md
 ```
 
-## 各子目录详解
+## `system_prompts/`:系统级提示词(先把 AI 变“可控”)
 
-### `coding_prompts/` - 编程提示词集
+系统提示词用于定义 **工作模式、代码品味、输出格式、安全边界**。目录采用版本化结构:
 
-| 类别 | 示例提示词 | 用途 |
-|------|-----------|------|
-| 项目规划 | `plan提示词.md` | 生成详细实施计划 |
-| 架构设计 | `系统架构可视化生成Mermaid.md` | 架构分析与可视化 |
-| 文档生成 | `项目上下文文档生成.md`、`精华技术文档生成提示词.md` | 自动生成项目文档 |
-| 代码规范 | `标准项目目录结构.md`、`标准化流程.md` | 统一代码风格与结构 |
-| 需求分析 | `智能需求理解与研发导航引擎.md` | 需求澄清与任务分解 |
-| 深度思考 | `ultrathink` 系列 | 触发 AI 深度推理模式 |
+- 路径约定:`prompts/system_prompts/CLAUDE.md/<版本号>/CLAUDE.md`
+- 推荐版本:
+  - `v8`:综合版,适合通用 Vibe Coding
+  - `v10`:偏 Augment/上下文引擎的规范化约束
+- 注意:`v9` 目录目前仅占位(无 `CLAUDE.md`)
 
-**索引文件**: `index.md` 提供完整的提示词列表和快速跳转链接。
+## `coding_prompts/`:任务级提示词(把流程跑通)
 
-### `system_prompts/` - 系统级提示词
+`coding_prompts/` 面向「一次任务」:从需求澄清、计划拆解到交付与复盘。建议把它当作工作流脚本库:
 
-用于设定 AI 整体行为模式和思维框架,当前包含 **10 个版本**:
+- **入口级**(新会话/新项目必用)
+  - `项目上下文文档生成.md`:固化上下文,降低跨会话漂移
+  - `智能需求理解与研发导航引擎.md`:把模糊需求拆成可执行任务
+- **交付级**(保证输出可审计)
+  - `标准化流程.md`:把“先做什么、后做什么”写死,减少失控
+  - `系统架构可视化生成Mermaid.md`:把架构输出成可视化(图胜千言)
 
-| 版本 | 特点 |
-|------|------|
-| v1 | 开发者行为准则与工程规范 |
-| v2 | ultrathink 模式与架构可视化规范 |
-| v3 | 思维创作哲学与执行确认机制 |
-| v4 | Linus 级工程师服务认知架构 |
-| v5 | 顶级程序员思维框架与代码品味 |
-| v6 | 综合版本,整合所有最佳实践 |
-| v7 | 推理与规划智能体,专职复杂任务分解 |
-| v8 | 最新综合版,顶级程序员服务 Linus 级工程师 |
-| v9 | 简化版本(实验性) |
-| v10 | 最新版,加入 Augment 上下文引擎规范 |
+### 关于 `index.md`(重要)
 
-**推荐**: 新项目建议从 `v8` 或 `v10` 开始
+[`coding_prompts/index.md`](./coding_prompts/index.md) 是自动生成的索引(包含版本矩阵与跳转链接),**不要手工编辑**。如果你批量增删/调整版本,建议通过工具链生成索引再同步。
 
-### `user_prompts/` - 用户自定义提示词
+## `user_prompts/`:个人工作台(不追求体系化)
 
-- `ASCII图生成.md` - 生成 ASCII 艺术图
-- `数据管道.md` - 数据处理流程设计
-- `项目变量与工具统一维护.md` - 项目配置管理
+放一些个人习惯、临时脚手架提示词,原则是 **能用、别烂、别污染主库**。
 
-## 快速使用
+## 快速使用(复制即用)
 
 ```bash
-# 查看某个提示词
-cat prompts/coding_prompts/plan提示词.md
+# 查看一个任务提示词
+sed -n '1,160p' prompts/coding_prompts/标准化流程.md
 
-# 使用 v8 版本的系统提示词
-cp prompts/system_prompts/CLAUDE.md/8/CLAUDE.md ./CLAUDE.md
+# 选定系统提示词版本(建议先备份你当前的 CLAUDE.md)
+cp prompts/system_prompts/CLAUDE.md/10/CLAUDE.md ./CLAUDE.md
 ```
 
+## 维护与批量管理(可选)
+
+如果你需要 Excel ↔ Markdown 的批量维护能力,仓库内置了第三方工具:`libs/external/prompts-library/`。建议把它视为“提示词资产的生产工具”,而把 `prompts/` 视为“日常开发的精选集”。
+
 ## 相关资源
 
-- [Google 表格提示词数据库](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=2093180351#gid=2093180351&range=A1)
-- [元提示词](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=1770874220#gid=1770874220)
-- [系统提示词收集仓库](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools)
-- [Skills 生成器](https://github.com/yusufkaraaslan/Skill_Seekers)
+- [`../skills/`](../skills/):把高频领域能力沉淀为 Skills(更强复用)
+- [`../documents/`](../documents/):方法论与最佳实践(提示词设计与工作流原则)
+- [`../libs/external/prompts-library/`](../libs/external/prompts-library/):提示词 Excel ↔ Markdown 管理工具

+ 41 - 0
skills/claude-skills/AGENTS.md

@@ -0,0 +1,41 @@
+# skills/claude-skills
+
+This directory is a **meta-skill**: it turns arbitrary domain material (docs/APIs/code/specs) into a reusable Skill (`SKILL.md` + `references/` + `scripts/` + `assets/`), and ships an executable quality gate + scaffolding.
+
+## Layout
+
+```
+claude-skills/
+|-- AGENTS.md
+|-- SKILL.md
+|-- assets/
+|   |-- template-minimal.md
+|   `-- template-complete.md
+|-- scripts/
+|   |-- create-skill.sh
+|   `-- validate-skill.sh
+`-- references/
+    |-- index.md
+    |-- README.md
+    |-- anti-patterns.md
+    |-- quality-checklist.md
+    `-- skill-spec.md
+```
+
+## File Responsibilities
+
+- `skills/claude-skills/SKILL.md`: entrypoint (triggers, deliverables, workflow, quality gate, tooling).
+- `skills/claude-skills/assets/template-minimal.md`: minimal template (small domains / quick bootstrap).
+- `skills/claude-skills/assets/template-complete.md`: full template (production-grade / complex domains).
+- `skills/claude-skills/scripts/create-skill.sh`: scaffold generator (minimal/full, output dir, overwrite).
+- `skills/claude-skills/scripts/validate-skill.sh`: spec validator (supports `--strict`).
+- `skills/claude-skills/references/index.md`: navigation for this meta-skill's reference docs.
+- `skills/claude-skills/references/README.md`: upstream official reference (lightly adjusted to keep links working in this repo).
+- `skills/claude-skills/references/skill-spec.md`: the local Skill spec (MUST/SHOULD/NEVER).
+- `skills/claude-skills/references/quality-checklist.md`: quality gate checklist + scoring.
+- `skills/claude-skills/references/anti-patterns.md`: common failure modes and how to fix them.
+
+## Dependencies & Boundaries
+
+- `scripts/*.sh`: depend only on `bash` + common POSIX tooling (`sed/awk/grep/find`), no network required.
+- This directory is about "how to build Skills", not about any specific domain; domain knowledge belongs in `skills/<domain>/`.

+ 160 - 333
skills/claude-skills/SKILL.md

@@ -1,416 +1,243 @@
 ---
 name: claude-skills
-description: Meta-skill for creating, optimizing, and managing Claude Skills. Use when building new skills from documentation, converting domain expertise into AI capabilities, structuring skill files, or learning skill development best practices. This is the foundational skill that generates other skills.
+description: "Claude Skills meta-skill: extract domain material (docs/APIs/code/specs) into a reusable Skill (SKILL.md + references/scripts/assets), and refactor existing Skills for clarity, activation reliability, and quality gates."
 ---
 
 # Claude Skills Meta-Skill
 
-The definitive guide to creating production-grade Claude Skills. This meta-skill teaches Claude how to transform any domain knowledge into structured, reusable AI capabilities.
+Turn scattered domain material into a Skill that is reusable, maintainable, and reliably activatable:
+- `SKILL.md` as the entrypoint (triggers, constraints, patterns, examples)
+- `references/` for long-form evidence and navigation
+- optional `scripts/` and `assets/` for scaffolding and templates
 
 ## When to Use This Skill
 
-This skill should be triggered when:
-- Creating a new Claude Skill from scratch
-- Converting documentation, APIs, or domain knowledge into a Skill
-- Optimizing or restructuring existing Skills
-- Learning Skill architecture patterns and best practices
-- Debugging or troubleshooting Skill behavior
-- Understanding YAML frontmatter and Skill metadata
-- Building multi-file Skills with references, scripts, and assets
+Trigger this meta-skill when you need to:
+- Create a new Skill from scratch from docs/specs/repos
+- Refactor an existing Skill (too long, unclear, inconsistent, misfires)
+- Design reliable activation (frontmatter + triggers + boundaries)
+- Extract a clean Quick Reference from large material
+- Split long content into navigable `references/`
+- Add a quality gate and a validator
+
+## Not For / Boundaries
+
+This meta-skill is NOT:
+- A domain Skill by itself (it builds domain Skills)
+- A license to invent external facts (if the material does not prove it, say so and add a verification path)
+- A substitute for required inputs (if inputs are missing, ask 1-3 questions before proceeding)
 
 ## Quick Reference
 
-### Skill Directory Structure
+### Deliverables (What You Must Produce)
+
+Your output MUST include:
+1. A concrete directory layout (typically `skills/<skill-name>/`)
+2. An actionable `SKILL.md` with decidable triggers, boundaries, and reproducible examples
+3. Long-form docs moved to `references/` with a `references/index.md`
+4. A pre-delivery checklist (Quality Gate)
+
+### Recommended Layout (Minimal -> Full)
 
 ```
 skill-name/
-├── SKILL.md              # Required: Main instructions with YAML frontmatter
-├── references/           # Optional: Detailed documentation files
-│   ├── index.md          # Navigation index for references
-│   ├── api.md            # API documentation
-│   └── examples.md       # Code examples
-├── scripts/              # Optional: Helper scripts and automation
-│   └── setup.sh          # Setup/installation scripts
-└── assets/               # Optional: Templates, configs, media
-    └── templates/        # Boilerplate files
+|-- SKILL.md              # Required: entrypoint with YAML frontmatter
+|-- references/           # Optional: long-form docs/evidence/index
+|   `-- index.md          # Recommended: navigation index
+|-- scripts/              # Optional: helpers/automation
+`-- assets/               # Optional: templates/configs/static assets
 ```
 
-### YAML Frontmatter Specification
+The truly minimal version is just `SKILL.md` (you can add `references/` later).
+
+### YAML Frontmatter (Required)
 
 ```yaml
 ---
-name: skill-name                    # Required: lowercase, hyphens, unique
-description: Complete description   # Required: What it does + when to trigger
+name: skill-name
+description: "What it does + when to use (activation triggers)."
 ---
 ```
 
-### Production SKILL.md Template
+Frontmatter rules:
+- `name` MUST match `^[a-z][a-z0-9-]*$` and SHOULD match the directory name
+- `description` MUST be decidable (not "helps with X") and include concrete trigger keywords
+
+### Minimal `SKILL.md` Skeleton (Copy/Paste)
 
 ```markdown
 ---
 name: my-skill
-description: [Purpose] + [Trigger conditions]. Use when [specific scenarios].
+description: "[Domain] capability: includes [capability 1], [capability 2]. Use when [decidable triggers]."
 ---
 
-# [Skill Name] Skill
+# my-skill Skill
 
-[One-paragraph overview]
+One sentence that states the boundary and the deliverable.
 
 ## When to Use This Skill
 
-This skill should be triggered when:
-- [Trigger 1]
+Trigger when any of these applies:
+- [Trigger 1: concrete task/keyword]
 - [Trigger 2]
 - [Trigger 3]
 
-## Quick Reference
-
-### Common Patterns
-
-**Pattern 1:** [Name]
-```[language]
-[code]
-```
-
-### Example Code Patterns
-
-**Example 1** ([language]):
-```[language]
-[complete working example]
-```
-
-## Reference Files
-
-This skill includes documentation in `references/`:
-- **[file.md]** - [Description]
-
-## Working with This Skill
-
-### For Beginners
-[Getting started guidance]
-
-### For Specific Features
-[How to find detailed information]
-
-## Resources
-
-### references/
-[Description]
-
-### scripts/
-[Description]
-
-### assets/
-[Description]
-```
-
----
-
-## Core Concepts
+## Not For / Boundaries
 
-### What is a Skill?
+- What this skill will not do (prevents misfires and over-promising)
+- Required inputs; ask 1-3 questions if missing
 
-**A Skill is a folder containing instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks.**
-
-Skills teach Claude to:
-- Apply domain-specific knowledge consistently
-- Follow organization-specific workflows
-- Work with specific APIs, file formats, or tools
-- Automate complex multi-step processes
-
-### Skill Activation Triggers
-
-Skills activate based on:
-- **Explicit mention**: "Use the [skill-name] skill to..."
-- **Description matching**: Task matches skill's description keywords
-- **Context relevance**: Task domain aligns with skill's purpose
-
----
-
-## Creating Production-Grade Skills
-
-### Step 1: Define Scope
-
-Answer before writing:
-1. What specific problem does this skill solve?
-2. What triggers should activate this skill?
-3. What are the boundaries (what it should NOT do)?
-
-### Step 2: Gather Source Material
-
-Collect:
-- Official documentation
-- API references
-- Code examples and patterns
-- Common errors and solutions
-
-### Step 3: Structure the SKILL.md
-
-**Critical sections:**
-1. YAML frontmatter with comprehensive description
-2. "When to Use This Skill" with specific triggers
-3. "Quick Reference" with common patterns
-4. Code examples that are complete and working
-5. Reference file pointers
-
-### Step 4: Create Reference Files
+## Quick Reference
 
-**references/index.md:**
-```markdown
-# [Skill Name] Documentation Index
+### Common Patterns
 
-## Quick Links
-- Getting Started → `getting_started.md`
-- API Reference → `api.md`
-- Examples → `examples.md`
+**Pattern 1:** one-line explanation
+```text
+[command/snippet you can paste and run]
 ```
 
-### Step 5: Add Scripts and Assets
+## Examples
 
-```bash
-# scripts/setup.sh
-#!/bin/bash
-echo "Setting up [skill-name]..."
-```
-
----
-
-## Best Practices
-
-### Description Writing
-
-```yaml
-# ❌ Too vague
-description: Helps with databases
-
-# ✅ Comprehensive
-description: PostgreSQL database development including SQL queries, schema design, performance optimization. Use when working with PostgreSQL, writing SQL, or managing databases.
-```
+### Example 1
+- Input:
+- Steps:
+- Expected output / acceptance:
 
-### Trigger Conditions
+### Example 2
 
-```markdown
-# ❌ Vague
-- Working with code
+### Example 3
 
-# ✅ Specific
-- Writing PostgreSQL queries or stored procedures
-- Designing database schemas or indexes
-- Optimizing slow queries
-```
+## References
 
-### Code Examples
+- `references/index.md`: navigation
+- `references/...`: long-form docs split by topic
 
-```markdown
-# ❌ Incomplete
-```sql
-SELECT * FROM users
-```
+## Maintenance
 
-# ✅ Complete with context
-**Example: Paginated query with filtering**
-```sql
-SELECT id, username, email, created_at
-FROM users
-WHERE status = 'active'
-ORDER BY created_at DESC
-LIMIT 20 OFFSET 0;
+- Sources: docs/repos/specs (do not invent)
+- Last updated: YYYY-MM-DD
+- Known limits: what is explicitly out of scope
 ```
-```
-
----
 
-## Skill Patterns by Category
+### Authoring Rules (Non-negotiable)
 
-### API/Library Skills
+1. Quick Reference is for short, directly usable patterns
+   - Keep it <= 20 patterns when possible.
+   - Anything that needs paragraphs of explanation goes to `references/`.
+2. Activation must be decidable
+   - Frontmatter `description` should say "what + when" with concrete keywords.
+   - "When to Use" must list specific tasks/inputs/goals, not vague help text.
+   - "Not For / Boundaries" is mandatory for reliability.
+3. No bluffing on external details
+   - If the material does not prove it, say so and include a verification path.
 
-```markdown
-## Quick Reference
+### Workflow (Material -> Skill)
 
-### Authentication
-```python
-client = APIClient(api_key="your-key")
-```
+Do not skip steps:
+1. Scope: write MUST/SHOULD/NEVER (three sentences total is fine)
+2. Extract patterns: pick 10-20 high-frequency patterns (commands/snippets/flows)
+3. Add examples: >= 3 end-to-end examples (input -> steps -> acceptance)
+4. Define boundaries: what is out-of-scope + required inputs
+5. Split references: move long text into `references/` + write `references/index.md`
+6. Apply the gate: run the checklist and the validator
 
-### Common Operations
-```python
-# Create
-resource = client.create(name="example")
+### Quality Gate (Pre-delivery Checklist)
 
-# List
-resources = client.list(limit=10)
+Minimum checks (see `references/quality-checklist.md` for the full version):
+1. `name` matches `^[a-z][a-z0-9-]*$` and matches the directory name
+2. `description` states "what + when" with concrete trigger keywords
+3. Has "When to Use This Skill" with decidable triggers
+4. Has "Not For / Boundaries" to reduce misfires
+5. Quick Reference is <= 20 patterns and each is directly usable
+6. Has >= 3 reproducible examples
+7. Long content is in `references/` and `references/index.md` is navigable
+8. Uncertain claims include a verification path (no bluffing)
+9. Reads like an operator's manual, not a documentation dump
 
-# Delete
-client.delete(resource_id)
-```
-
-### Error Handling
-```python
-try:
-    result = client.operation()
-except APIError as e:
-    print(f"Error {e.code}: {e.message}")
-```
-```
+Validate locally:
 
-### Framework Skills
-
-```markdown
-## Project Structure
-```
-my-project/
-├── src/
-├── tests/
-└── config/
-```
-
-## Common Commands
 ```bash
-framework init my-project
-framework dev
-framework build
-```
-```
+# From repo root (basic validation)
+./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name>
 
-### Domain Knowledge Skills
+# From repo root (strict validation)
+./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name> --strict
 
-```markdown
-## Core Concepts
-
-### Concept 1
-[Explanation]
-
-### Concept 2
-[Explanation]
+# From skills/claude-skills/ (basic validation)
+./scripts/validate-skill.sh ../<skill-name>
 
-## Decision Framework
-
-When to use Approach A:
-- [Condition 1]
-- [Condition 2]
-
-When to use Approach B:
-- [Condition 1]
-- [Condition 2]
+# From skills/claude-skills/ (strict validation)
+./scripts/validate-skill.sh ../<skill-name> --strict
 ```
 
----
+### Tools & Templates
 
-## Generating Skills from Source Material
-
-### Transformation Process
-
-```
-Source Material
-      ↓
-Extract: concepts, patterns, examples, edge cases, errors
-      ↓
-Structure: YAML → When to Use → Quick Reference → Details
-      ↓
-Create: references/index.md + categorized docs
-      ↓
-Production-Grade Skill
-```
-
-### Generation Prompt
-
-When creating a skill from source material:
-
-```
-Create a production-grade Claude Skill:
-
-1. Analyze source material
-2. Extract core concepts and patterns
-3. Create SKILL.md with:
-   - Comprehensive description (purpose + triggers)
-   - Specific "When to Use" conditions
-   - Quick Reference with code patterns
-   - Complete working examples
-4. Create references/index.md
-5. Organize detailed docs in references/
-```
-
----
-
-## Platform Integration
-
-### Claude Code
+Generate a new Skill skeleton:
 
 ```bash
-# Add marketplace
-/plugin marketplace add anthropics/skills
+# From repo root (generate into ./skills/)
+./skills/claude-skills/scripts/create-skill.sh my-skill --full --output skills
 
-# Install
-/plugin install example-skills@anthropic-agent-skills
+# From skills/claude-skills/ (generate into ../ i.e. ./skills/)
+./scripts/create-skill.sh my-skill --full --output ..
 
-# Use
-"Use the PDF skill to extract tables from report.pdf"
+# Minimal skeleton
+./skills/claude-skills/scripts/create-skill.sh my-skill --minimal --output skills
 ```
 
-### Claude.ai
-
-1. Navigate to Claude.ai (paid plan)
-2. Upload custom skill folder
-3. Reference in conversations
-
-### Claude API
-
-See: https://docs.claude.com/en/api/skills-guide
-
----
-
-## Troubleshooting
-
-### Skill Not Activating
-
-1. Check `description` includes trigger keywords
-2. Verify `name` is lowercase with hyphens
-3. Ensure valid YAML (no tabs)
-4. Try explicit: "Use the [skill-name] skill to..."
-
-### Inconsistent Behavior
-
-1. Add more specific trigger conditions
-2. Include more code examples
-3. Make instructions unambiguous
-4. Add explicit constraints
-
----
-
-## Reference Files
+Templates:
+- `assets/template-minimal.md`
+- `assets/template-complete.md`
 
-This skill includes documentation in `references/`:
+## Examples
 
-- **README.md** - Official Anthropic Skills repository documentation
-- **index.md** - Documentation index and quick links
+### Example 1: Create a Skill from Docs
 
-## Working with This Skill
+- Input: an official doc/spec + 2-3 real code samples + common failure modes
+- Steps:
+  1. Run `create-skill.sh` to scaffold `skills/<skill-name>/`
+  2. Write frontmatter `description` as "what + when"
+  3. Extract 10-20 high-frequency patterns into Quick Reference
+  4. Add >= 3 end-to-end examples with acceptance criteria
+  5. Put long content into `references/` and wire `references/index.md`
+  6. Run `validate-skill.sh --strict` and iterate
 
-### For Creating New Skills
-Follow the 5-step process in "Creating Production-Grade Skills"
+### Example 2: Refactor a "Doc Dump" Skill
 
-### For Optimizing Existing Skills
-Review "Best Practices" and compare against your skill
+- Input: an existing `SKILL.md` with long pasted documentation
+- Steps:
+  1. Identify which parts are patterns vs. long-form explanation
+  2. Move long-form text into `references/` (split by topic)
+  3. Rewrite Quick Reference as short copy/paste patterns
+  4. Add or fix Examples until they are reproducible
+  5. Add "Not For / Boundaries" to reduce misfires
 
-### For Understanding Architecture
-Read "Core Concepts" for foundational understanding
+### Example 3: Validate and Gate a Skill
 
-## Resources
+- Input: `skills/<skill-name>/`
+- Steps:
+  1. Run `validate-skill.sh` (non-strict) to get warnings
+  2. Fix frontmatter/name mismatches and missing sections
+  3. Run `validate-skill.sh --strict` to enforce the spec
+  4. Run the scoring rubric in `references/quality-checklist.md` before shipping
 
-### references/
-- Official Anthropic documentation
-- Navigation index
+## References
 
-### scripts/
-- `create-skill.sh` - Quick skill directory generator
+Local docs:
+- `references/index.md`
+- `references/skill-spec.md`
+- `references/quality-checklist.md`
+- `references/anti-patterns.md`
+- `references/README.md` (upstream official reference)
 
-### assets/
-- `template-minimal.md` - Minimal template
-- `template-complete.md` - Full production template
+External (official):
+- https://support.claude.com/en/articles/12512176-what-are-skills
+- https://support.claude.com/en/articles/12512180-using-skills-in-claude
+- https://support.claude.com/en/articles/12512198-creating-custom-skills
+- https://docs.claude.com/en/api/skills-guide
 
-## Notes
+## Maintenance
 
-- Skills are portable across Claude Code, Claude.ai, and API
-- The `description` field is critical for reliable activation
-- Code examples should be complete and immediately usable
-- This skill generates other production-grade skills
+- Sources: local spec files in `skills/claude-skills/references/` + upstream official docs in `references/README.md`
+- Last updated: 2025-12-14
+- Known limits: `validate-skill.sh` is heuristic; strict mode assumes the recommended section headings

+ 56 - 77
skills/claude-skills/assets/template-complete.md

@@ -1,109 +1,88 @@
 ---
-name: my-skill
-description: [Domain] development and operations including [capability 1], [capability 2], [capability 3]. Use when working with [domain], implementing [solutions], or troubleshooting [issues].
+name: {{skill_name}}
+description: "[Domain] end-to-end capability: includes [capability 1], [capability 2], [capability 3]. Use when [decidable triggers]."
 ---
 
-# [Skill Name] Skill
+# {{skill_name}} Skill
 
-Comprehensive assistance with [domain] development, generated from official documentation.
+Production-grade skill for [domain]: extract rules, patterns, and reproducible examples from source material (avoid documentation dumps).
 
 ## When to Use This Skill
 
-This skill should be triggered when:
-- Working with [domain/technology]
-- Asking about [domain] features or APIs
-- Implementing [domain] solutions
-- Debugging [domain] code
-- Learning [domain] best practices
+Trigger when any of these applies:
+- You are designing/implementing/debugging [domain/tech]
+- You need to turn requirements into concrete commands/code/configs
+- You need common pitfalls, boundaries, and acceptance criteria
 
-## Quick Reference
-
-### Common Patterns
+## Not For / Boundaries
 
-**Pattern 1:** [Name]
-```[language]
-[code example]
-```
+- What this skill will not do (prevents misfires and over-promising)
+- Required inputs; ask 1-3 questions if missing
 
-**Pattern 2:** [Name]
-```[language]
-[code example]
-```
-
-**Pattern 3:** [Name]
-```[language]
-[code example]
-```
+## Quick Reference
 
-### Example Code Patterns
+### Common Patterns
 
-**Example 1** ([language]):
-```[language]
-// [Description of what this example demonstrates]
-[complete working code]
+**Pattern 1:** one-line explanation
+```text
+[command/snippet you can paste and run]
 ```
 
-**Example 2** ([language]):
-```[language]
-// [Description]
-[complete working code]
+**Pattern 2:**
+```text
+[command/snippet you can paste and run]
 ```
 
-## [Domain-Specific Section 1]
-
-### [Subsection]
-
-[Content]
-
-### [Subsection]
-
-[Content]
-
-## [Domain-Specific Section 2]
+## Rules & Constraints
 
-### [Subsection]
+- MUST: non-negotiable rules (security boundaries, defaults, acceptance)
+- SHOULD: strong recommendations (best practices, performance habits)
+- NEVER: explicit prohibitions (dangerous ops, inventing facts)
 
-[Content]
+## Examples
 
-## Reference Files
+### Example 1
+- Input:
+- Steps:
+- Expected output / acceptance:
 
-This skill includes comprehensive documentation in `references/`:
+### Example 2
 
-- **getting_started.md** - Installation, setup, first steps
-- **api.md** - Complete API reference
-- **examples.md** - Code examples by use case
-- **troubleshooting.md** - Common issues and solutions
+### Example 3
 
-Use `view` to read specific reference files when detailed information is needed.
+## FAQ
 
-## Working with This Skill
+- Q: ...
+  - A: ...
 
-### For Beginners
-Start with the getting_started reference file for foundational concepts.
+## Troubleshooting
 
-### For Specific Features
-Use the api reference file for detailed function/method information.
+- Symptom -> Likely causes -> Diagnosis -> Fix
 
-### For Code Examples
-The examples reference file contains patterns organized by use case.
+## References
 
-## Resources
+- `references/index.md`: navigation
+- `references/getting_started.md`: onboarding and vocabulary
+- `references/api.md`: API/CLI/config reference (if applicable)
+- `references/examples.md`: long examples and extra use cases
+- `references/troubleshooting.md`: edge cases and failure modes
 
-### references/
-Organized documentation extracted from official sources:
-- Detailed explanations
-- Code examples with language annotations
-- Links to original documentation
+## Maintenance
 
-### scripts/
-Helper scripts for common automation tasks.
+- Sources: docs/repos/specs (do not invent)
+- Last updated: YYYY-MM-DD
+- Known limits: what is explicitly out of scope
 
-### assets/
-Templates, boilerplate, and example configurations.
+## Quality Gate
 
-## Notes
+Minimum checks before shipping (see meta-skill `claude-skills` for the full version):
 
-- This skill was generated from official documentation
-- Reference files preserve structure from source docs
-- Code examples include language detection for syntax highlighting
-- Quick reference patterns are extracted from common usage
+1. `description` is decidable ("what + when") and includes trigger keywords
+2. Has "When to Use This Skill" with decidable triggers
+3. Has "Not For / Boundaries" to reduce misfires
+4. Quick Reference is <= 20 patterns and each is directly usable
+5. Has >= 3 reproducible examples (input -> steps -> acceptance)
+6. Long content is in `references/` with a navigable `references/index.md`
+7. Uncertain claims include a verification path (no bluffing)
+8. No documentation dumps in Quick Reference
+9. Reads like an operator's manual, not a knowledge dump

+ 31 - 18
skills/claude-skills/assets/template-minimal.md

@@ -1,37 +1,50 @@
 ---
-name: my-skill
-description: [Domain] assistance including [key capability]. Use when [trigger condition].
+name: {{skill_name}}
+description: "[Domain] capability: includes [key capability]. Use when [decidable triggers]."
 ---
 
-# [Skill Name] Skill
+# {{skill_name}} Skill
 
-[One-sentence overview of what this skill does]
+One sentence that states the boundary and the deliverable.
 
 ## When to Use This Skill
 
-This skill should be triggered when:
-- [Trigger 1]
+Trigger when any of these applies:
+- [Trigger 1: concrete task/keyword]
 - [Trigger 2]
 - [Trigger 3]
 
+## Not For / Boundaries
+
+- What this skill will not do (prevents misfires and over-promising)
+- Required inputs; ask 1-3 questions if missing
+
 ## Quick Reference
 
 ### Common Patterns
 
-**Pattern 1:**
-```[language]
-[code]
+**Pattern 1:** one-line explanation
+```text
+[command/snippet you can paste and run]
 ```
 
-**Pattern 2:**
-```[language]
-[code]
-```
+## Examples
+
+### Example 1
+- Input:
+- Steps:
+- Expected output / acceptance:
+
+### Example 2
+
+### Example 3
+
+## References
 
-## Resources
+- `references/index.md`: navigation
+- `references/...`: long-form docs split by topic
 
-### references/
-[Documentation files if any]
+## Maintenance
 
-### scripts/
-[Helper scripts if any]
+- Sources: docs/repos/specs (do not invent)
+- Last updated: YYYY-MM-DD

+ 2 - 2
skills/claude-skills/references/README.md

@@ -13,7 +13,7 @@ This repository contains example skills that demonstrate what's possible with Cl
 
 Each skill is self-contained in its own directory with a `SKILL.md` file containing the instructions and metadata that Claude uses. Browse through these examples to get inspiration for your own skills or to understand different patterns and approaches.
 
-The example skills in this repo are open source (Apache 2.0). We've also included the document creation & editing skills that power [Claude's document capabilities](https://www.anthropic.com/news/create-files) under the hood in the [`document-skills/`](./document-skills/) folder. These are source-available, not open source, but we wanted to share these with developers as a reference for more complex skills that are actively used in a production AI application.
+The example skills in this repo are open source (Apache 2.0). We've also included the document creation & editing skills that power [Claude's document capabilities](https://www.anthropic.com/news/create-files) under the hood in the [`skills/`](https://github.com/anthropics/skills/tree/main/skills) directory. These are source-available, not open source, but we wanted to share these with developers as a reference for more complex skills that are actively used in a production AI application.
 
 **Note:** These are reference examples for inspiration and learning. They showcase general-purpose capabilities rather than organization-specific workflows or sensitive content.
 
@@ -120,4 +120,4 @@ The markdown content below contains the instructions, examples, and guidelines t
 
 Skills are a great way to teach Claude how to get better at using specific pieces of software. As we see awesome example skills from partners, we may highlight some of them here:
 
-- **Notion** - [Notion Skills for Claude](https://www.notion.so/notiondevs/Notion-Skills-for-Claude-28da4445d27180c7af1df7d8615723d0)
+- **Notion** - [Notion Skills for Claude](https://www.notion.so/notiondevs/Notion-Skills-for-Claude-28da4445d27180c7af1df7d8615723d0)

+ 110 - 0
skills/claude-skills/references/anti-patterns.md

@@ -0,0 +1,110 @@
+# Anti-Patterns (And How to Fix Them)
+
+This file documents common ways Skills fail in practice. Use it when refactoring existing Skills.
+
+## 1) Documentation Dump in Quick Reference
+
+**Symptom**
+- Quick Reference contains paragraphs of text, pasted docs, or large excerpts.
+
+**Why it fails**
+- Users cannot scan or reuse it.
+- The model treats it as "knowledge soup" rather than executable patterns.
+
+**Fix**
+- Move long text into `references/` (split by topic).
+- Keep Quick Reference as <= 20 copy/paste patterns when possible.
+- Add Examples for anything non-trivial.
+
+## 2) Vague Triggers ("Helps with X")
+
+**Symptom**
+- `description` says "helps with databases" or similar.
+- "When to Use" is a generic list with no tasks/inputs/goals.
+
+**Why it fails**
+- Activation becomes noisy and unpredictable.
+
+**Fix**
+- Rewrite `description` as: "What + when".
+- In "When to Use", list decidable tasks:
+  - "Writing migration SQL for PostgreSQL"
+  - "Debugging a failing CCXT order placement"
+- Add "Not For / Boundaries" to prevent misfires.
+
+## 3) Missing Boundaries
+
+**Symptom**
+- The Skill never says what it will not do.
+
+**Why it fails**
+- The model over-promises and makes unsafe assumptions.
+- The skill triggers in irrelevant contexts.
+
+**Fix**
+- Add `## Not For / Boundaries` with:
+  - explicit out-of-scope items
+  - required inputs and what questions to ask when missing
+
+## 4) Non-reproducible Examples
+
+**Symptom**
+- Examples are pseudo-code, missing inputs, or missing expected outputs.
+
+**Why it fails**
+- Users cannot trust or validate the behavior.
+
+**Fix**
+- Each example should contain:
+  - Input(s)
+  - Steps
+  - Expected output / acceptance criteria
+- Prefer minimal reproducible examples over big "showcase" code.
+
+## 5) One Giant File Syndrome
+
+**Symptom**
+- Everything is in `SKILL.md` (or one huge reference file).
+
+**Why it fails**
+- The entrypoint becomes unscannable and hard to maintain.
+
+**Fix**
+- Keep `SKILL.md` execution-focused (patterns + examples + boundaries).
+- Split long content into `references/` and add `references/index.md`.
+
+## 6) Invented Facts and Unverifiable Claims
+
+**Symptom**
+- The Skill claims API fields/flags/commands without citing sources.
+
+**Why it fails**
+- Incorrect guidance is worse than missing guidance.
+
+**Fix**
+- Add a "verification path": where/how to confirm in official docs or source code.
+- Prefer statements backed by your material; mark assumptions explicitly.
+
+## 7) Unsafe Defaults and Destructive Commands
+
+**Symptom**
+- The Skill suggests destructive commands as the default path.
+
+**Why it fails**
+- Users copy/paste and lose data.
+
+**Fix**
+- Put destructive actions behind explicit warnings and confirmation steps.
+- Prefer read-only diagnostics first.
+
+## 8) Inconsistent Terminology
+
+**Symptom**
+- Same concept has multiple names; different concepts share a name.
+
+**Why it fails**
+- Increases cognitive load and produces inconsistent outputs.
+
+**Fix**
+- Add a short glossary (in `references/getting_started.md` or similar).
+- Use one concept, one name.

+ 17 - 91
skills/claude-skills/references/index.md

@@ -1,100 +1,26 @@
-# Claude Skills Documentation Index
+# Claude Skills Meta-Skill Reference Index
 
-## Overview
+This directory contains long-form documentation that supports the `claude-skills` meta-skill.
 
-This index provides navigation for the Claude Skills meta-skill documentation.
+## Start Here
 
-## Categories
+- [`../SKILL.md`](../SKILL.md): the meta-skill entrypoint (workflow, quality gate, tooling)
 
-### Official Documentation
-**File:** `README.md`
+## Local Reference Docs (This Repo)
 
-Complete overview of Claude Skills including:
-- What are skills and how they work
-- Example skills by category
-- Document skills (source-available)
-- Usage across platforms (Claude Code, Claude.ai, API)
-- Creating basic skills
+- [`skill-spec.md`](skill-spec.md): normative spec (MUST/SHOULD/NEVER) for a production-grade Skill in this repo
+- [`quality-checklist.md`](quality-checklist.md): quality gate checklist + scoring rubric
+- [`anti-patterns.md`](anti-patterns.md): common failure modes and how to fix them
 
-## Quick Links
+## Upstream / Official Reference
 
-| Topic | File | Section |
-|-------|------|---------|
-| What are skills | `README.md` | Lines 1-9 |
-| Example skills list | `README.md` | Lines 24-45 |
-| Document skills | `README.md` | Lines 47-56 |
-| Claude Code setup | `README.md` | Lines 58-78 |
-| Claude.ai usage | `README.md` | Lines 80-84 |
-| Claude API | `README.md` | Lines 86-88 |
-| Creating a skill | `README.md` | Lines 90-117 |
+- [`README.md`](README.md): upstream overview of Claude Skills (what skills are, usage, examples)
 
-## Skill Structure Reference
+## External Links (Official)
 
-### Required Files
-
-```
-skill-name/
-└── SKILL.md           # Main instructions with YAML frontmatter
-```
-
-### Optional Directories
-
-```
-skill-name/
-├── SKILL.md
-├── references/        # Documentation files
-├── scripts/           # Helper scripts
-└── assets/            # Templates, configs
-```
-
-### YAML Frontmatter
-
-```yaml
----
-name: skill-name          # lowercase, hyphens
-description: What + When  # Purpose and trigger conditions
----
-```
-
-## Topics Covered
-
-### Getting Started
-- What skills are
-- How skills work
-- Platform availability
-- Installation methods
-
-### Skill Categories
-
-| Category | Examples |
-|----------|----------|
-| Creative | algorithmic-art, canvas-design, slack-gif-creator |
-| Development | artifacts-builder, mcp-server, webapp-testing |
-| Enterprise | brand-guidelines, internal-comms, theme-factory |
-| Documents | docx, pdf, pptx, xlsx |
-| Meta | skill-creator, template-skill |
-
-### Platform Integration
-
-| Platform | Method |
-|----------|--------|
-| Claude Code | `/plugin marketplace add anthropics/skills` |
-| Claude.ai | Upload via skills interface |
-| Claude API | Skills API endpoint |
-
-## External Resources
-
-### Official Links
-- [What are skills?](https://support.claude.com/en/articles/12512176-what-are-skills)
-- [Using skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
-- [Creating custom skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
-- [Skills API Quickstart](https://docs.claude.com/en/api/skills-guide)
-- [Anthropic Skills GitHub](https://github.com/anthropics/skills)
-
-### Blog Posts
-- [Equipping agents with Agent Skills](https://anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
-
-## License
-
-- Example skills: Apache 2.0 (open source)
-- Document skills: Source-available (reference only)
+- What are skills? https://support.claude.com/en/articles/12512176-what-are-skills
+- Using skills in Claude https://support.claude.com/en/articles/12512180-using-skills-in-claude
+- Creating custom skills https://support.claude.com/en/articles/12512198-creating-custom-skills
+- Skills API Quickstart https://docs.claude.com/en/api/skills-guide
+- Anthropic Skills GitHub https://github.com/anthropics/skills
+- Engineering blog: Agent Skills https://anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

+ 49 - 0
skills/claude-skills/references/quality-checklist.md

@@ -0,0 +1,49 @@
+# Quality Checklist (Production Gate)
+
+Use this checklist to decide whether a Skill is shippable. It is intentionally biased toward reliability and maintainability over "more content".
+
+## Scoring
+
+Score each item:
+- 2 = fully satisfied
+- 1 = partially satisfied / needs work
+- 0 = missing
+
+Suggested ship threshold:
+- Total score >= 24 (out of 32)
+- No "critical" item below 2
+
+## A. Activation Reliability (Critical)
+
+1. Frontmatter `name` matches `^[a-z][a-z0-9-]*$` and matches directory name (2)
+2. Frontmatter `description` is decidable ("what + when") with concrete keywords (2)
+3. `## When to Use This Skill` lists concrete tasks/inputs/goals (2)
+4. `## Not For / Boundaries` exists and meaningfully prevents misfires (2)
+
+## B. Usability (Critical)
+
+5. `## Quick Reference` is short and directly usable (no doc dumps) (2)
+6. Quick Reference patterns are formatted for copy/paste (2)
+7. `## Examples` contains >= 3 reproducible examples (2)
+8. Examples include acceptance criteria / expected output (2)
+
+## C. Evidence & Correctness
+
+9. `## Maintenance` lists sources (docs/repos/specs) and last-updated date (2)
+10. Uncertain external details include a verification path (2)
+11. Terminology is consistent (one concept, one name) (2)
+12. No contradictions between Quick Reference and Examples (2)
+
+## D. Structure & Maintainability
+
+13. Long-form content lives in `references/` with `references/index.md` navigation (2)
+14. Reference files are split by topic (not one giant file) (2)
+15. The skill reads like an operator manual (task -> steps -> acceptance) (2)
+16. Optional: scripts/assets are minimal and clearly scoped (2)
+
+## Common Reasons to Fail the Gate
+
+- Vague activation ("helps with X") with no boundaries
+- Quick Reference contains pasted documentation instead of patterns
+- Examples are not reproducible (no inputs, no steps, no expected output)
+- No sources and no update date (cannot be trusted or maintained)

+ 111 - 0
skills/claude-skills/references/skill-spec.md

@@ -0,0 +1,111 @@
+# Skill Spec (This Repo)
+
+This document defines what a "production-grade Skill" means in this repository. Use it as the source of truth when creating or refactoring anything under `skills/`.
+
+Keywords: MUST / SHOULD / MAY / MUST NOT / SHOULD NOT are normative.
+
+## 1. Directory & Naming
+
+- A Skill MUST be a directory under `skills/` named after its `name` field.
+- The directory name MUST match `^[a-z][a-z0-9-]*$`.
+- The Skill entrypoint MUST be `SKILL.md` at the root of the skill directory.
+
+## 2. Frontmatter (Required)
+
+`SKILL.md` MUST start with YAML frontmatter:
+
+```yaml
+---
+name: skill-name
+description: "What it does + when to use (activation triggers)."
+---
+```
+
+Rules:
+- `name` MUST match `^[a-z][a-z0-9-]*$`.
+- `name` SHOULD equal the directory name.
+- `description` MUST be decidable and operational:
+  - Good: "X development and debugging. Use when doing A/B/C."
+  - Bad: "Helps with X."
+
+## 3. SKILL.md Structure
+
+### 3.1 Required Sections
+
+`SKILL.md` SHOULD follow this section order, and in strict mode it MUST:
+
+1. `## When to Use This Skill`
+2. `## Not For / Boundaries`
+3. `## Quick Reference`
+4. `## Examples`
+5. `## References`
+6. `## Maintenance`
+
+Rationale:
+- Activation reliability depends on explicit triggers and boundaries.
+- Usability depends on short patterns and reproducible examples.
+- Maintainability depends on sources and navigable references.
+
+### 3.2 Quick Reference Rules
+
+- Quick Reference MUST contain short, directly usable patterns.
+- Quick Reference MUST NOT become a documentation dump.
+- Long explanations SHOULD go to `references/`.
+- A good target is <= 20 patterns, but large domains may justify more.
+
+### 3.3 Example Rules
+
+- The Examples section MUST contain reproducible examples.
+- Each example SHOULD specify:
+  - input(s)
+  - steps
+  - expected output / acceptance criteria
+- Pseudo-code MAY be used only if the platform is unavailable, and MUST be clearly labeled.
+
+### 3.4 Boundaries Rules
+
+- "Not For / Boundaries" MUST list:
+  - explicit out-of-scope items (to prevent misfires)
+  - required inputs and what to ask when missing (1-3 questions)
+
+## 4. references/ (Long-form Docs)
+
+- `references/` SHOULD exist when the domain has:
+  - long docs
+  - many edge cases
+  - extensive APIs/CLIs/config surfaces
+- If `references/` exists, it SHOULD include:
+  - `references/index.md` as a navigation entrypoint
+
+Guideline:
+- `references/` is for evidence, depth, and navigation.
+- `SKILL.md` is for execution: short patterns + examples + constraints.
+
+## 5. scripts/ and assets/
+
+- `scripts/` MAY contain helper automation (generators, validators, setup).
+  - Scripts MUST be non-interactive by default.
+  - Scripts MUST NOT require network access unless explicitly stated.
+- `assets/` MAY contain templates, configs, or static resources.
+
+## 6. Safety & Integrity
+
+- Skills MUST NOT include secrets (API keys, tokens, credentials).
+- Skills MUST NOT invent external facts.
+  - If uncertain, they MUST include a verification path (where/how to check).
+- Potentially destructive commands MUST be explicitly labeled and gated.
+
+## 7. Maintenance Metadata
+
+Each Skill SHOULD include a `## Maintenance` section with:
+- sources (docs/repos/specs)
+- last-updated date
+- known limits / non-goals
+
+## 8. Quality Gate
+
+Before shipping, run the checklist in `quality-checklist.md` and (if available) the validator:
+
+```bash
+./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name> --strict
+```

+ 142 - 151
skills/claude-skills/scripts/create-skill.sh

@@ -1,190 +1,181 @@
-#!/bin/bash
-#
-# create-skill.sh - Production-grade Skill directory generator
-#
-# Usage: ./create-skill.sh <skill-name> [--minimal]
-#
-# Examples:
-#   ./create-skill.sh postgresql
-#   ./create-skill.sh my-api --minimal
-#
-
-set -e
-
-SKILL_NAME=$1
-MINIMAL=$2
-
-if [ -z "$SKILL_NAME" ]; then
-    echo "Usage: ./create-skill.sh <skill-name> [--minimal]"
-    echo ""
-    echo "Examples:"
-    echo "  ./create-skill.sh postgresql"
-    echo "  ./create-skill.sh my-api --minimal"
-    exit 1
-fi
-
-# Validate skill name (lowercase, hyphens only)
-if [[ ! "$SKILL_NAME" =~ ^[a-z][a-z0-9-]*$ ]]; then
-    echo "Error: Skill name must be lowercase, start with letter, use hyphens"
-    echo "Example: my-skill-name"
-    exit 1
-fi
-
-echo "Creating skill: $SKILL_NAME"
-
-# Create directory structure
-mkdir -p "$SKILL_NAME"/{assets,scripts,references}
-
-# Create references/index.md
-cat > "$SKILL_NAME/references/index.md" << 'EOF'
-# Documentation Index
-
-## Categories
+#!/usr/bin/env bash
 
-### Getting Started
-- **getting_started.md** - Installation and setup
+set -euo pipefail
 
-### API Reference
-- **api.md** - Complete API documentation
+# ==================== Help ====================
 
-### Examples
-- **examples.md** - Code examples by use case
+usage() {
+  cat <<'EOF'
+Usage:
+  create-skill.sh <skill-name> [--minimal|--full] [--output <dir>] [--force]
 
-## Quick Links
+Notes:
+  - <skill-name> MUST be lowercase, start with a letter, and only contain letters, digits, and hyphens
+  - Default mode: --full
+  - Default output: current directory (creates ./<skill-name>/)
 
-- Installation → `getting_started.md`
-- API Reference → `api.md`
-- Examples → `examples.md`
+Examples:
+  ./skills/claude-skills/scripts/create-skill.sh postgresql --full --output skills
+  ./skills/claude-skills/scripts/create-skill.sh my-api --minimal
 EOF
+}
+
+die() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+# ==================== Arg Parsing ====================
+
+skill_name=""
+mode="full"
+output_dir="."
+force=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --minimal)
+      mode="minimal"
+      shift
+      ;;
+    --full)
+      mode="full"
+      shift
+      ;;
+    -o|--output)
+      [[ $# -ge 2 ]] || die "--output requires a directory argument"
+      output_dir="$2"
+      shift 2
+      ;;
+    -f|--force)
+      force=1
+      shift
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      die "Unknown argument: $1 (use --help)"
+      ;;
+    *)
+      if [[ -z "$skill_name" ]]; then
+        skill_name="$1"
+        shift
+      else
+        die "Extra argument: $1 (only one <skill-name> is allowed)"
+      fi
+      ;;
+  esac
+done
+
+[[ -n "$skill_name" ]] || { usage; exit 1; }
+
+if [[ ! "$skill_name" =~ ^[a-z][a-z0-9-]*$ ]]; then
+  die "skill-name must be lowercase, start with a letter, and only contain letters/digits/hyphens (e.g. my-skill-name)"
+fi
 
-if [ "$MINIMAL" == "--minimal" ]; then
-    # Minimal template
-    cat > "$SKILL_NAME/SKILL.md" << EOF
----
-name: $SKILL_NAME
-description: [Domain] assistance including [key capability]. Use when [trigger condition].
----
-
-# ${SKILL_NAME^} Skill
-
-[One-sentence overview]
-
-## When to Use This Skill
-
-This skill should be triggered when:
-- [Trigger 1]
-- [Trigger 2]
-- [Trigger 3]
-
-## Quick Reference
-
-### Common Patterns
-
-**Pattern 1:**
-\`\`\`
-[code]
-\`\`\`
-
-## Resources
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+assets_dir="${script_dir}/../assets"
 
-### references/
-Documentation files
+template_path=""
+case "$mode" in
+  minimal) template_path="${assets_dir}/template-minimal.md" ;;
+  full) template_path="${assets_dir}/template-complete.md" ;;
+  *) die "Internal error: unknown mode=$mode" ;;
+esac
 
-### scripts/
-Helper scripts
-EOF
-else
-    # Full production template
-    cat > "$SKILL_NAME/SKILL.md" << EOF
----
-name: $SKILL_NAME
-description: [Domain] development including [capability 1], [capability 2]. Use when working with [domain], implementing solutions, or troubleshooting issues.
----
+[[ -f "$template_path" ]] || die "Template not found: $template_path"
 
-# ${SKILL_NAME^} Skill
+mkdir -p "$output_dir"
 
-Comprehensive assistance with [domain] development.
+target_dir="${output_dir%/}/${skill_name}"
 
-## When to Use This Skill
+if [[ -e "$target_dir" && "$force" -ne 1 ]]; then
+  die "Target already exists: $target_dir (use --force to overwrite)"
+fi
 
-This skill should be triggered when:
-- Working with [domain/technology]
-- Asking about [domain] features or APIs
-- Implementing [domain] solutions
-- Debugging [domain] code
-- Learning [domain] best practices
+mkdir -p "$target_dir"/{assets,scripts,references}
 
-## Quick Reference
+# ==================== Write Files ====================
 
-### Common Patterns
+render_template() {
+  local src="$1"
+  local dest="$2"
+  sed "s/{{skill_name}}/${skill_name}/g" "$src" > "$dest"
+}
 
-**Pattern 1:** [Name]
-\`\`\`
-[code example]
-\`\`\`
+render_template "$template_path" "$target_dir/SKILL.md"
 
-**Pattern 2:** [Name]
-\`\`\`
-[code example]
-\`\`\`
+cat > "$target_dir/references/index.md" <<EOF
+# ${skill_name} Reference Index
 
-### Example Code Patterns
+## Quick Links
 
-**Example 1:**
-\`\`\`
-[complete working code]
-\`\`\`
+- Getting started: \`getting_started.md\`
+- API/CLI/config: \`api.md\` (if applicable)
+- Examples: \`examples.md\`
+- Troubleshooting: \`troubleshooting.md\`
 
-## Reference Files
+## Notes
 
-This skill includes documentation in \`references/\`:
+- Put long-form content here: excerpts, evidence links, edge cases, FAQ
+- Keep \`SKILL.md\` Quick Reference short and directly usable
+EOF
 
-- **index.md** - Documentation navigation
-- **getting_started.md** - Setup and basics
-- **api.md** - API reference
-- **examples.md** - Code examples
+if [[ "$mode" == "full" ]]; then
+  cat > "$target_dir/references/getting_started.md" <<'EOF'
+# Getting Started & Vocabulary
 
-## Working with This Skill
+## Goals
 
-### For Beginners
-Start with getting_started reference file.
+- Define the 10 most important terms in this domain
+- Provide the shortest path from zero to working
+EOF
 
-### For Specific Features
-Use api reference for detailed information.
+  cat > "$target_dir/references/api.md" <<'EOF'
+# API / CLI / Config Reference (If Applicable)
 
-### For Code Examples
-See examples reference file.
+## Suggested Structure
 
-## Resources
+- Organize by use case, not alphabetically
+- Key parameters: defaults, boundaries, common misuse
+- Common errors: message -> cause -> fix steps
+EOF
 
-### references/
-Organized documentation from official sources.
+  cat > "$target_dir/references/examples.md" <<'EOF'
+# Long Examples
 
-### scripts/
-Helper scripts for automation.
+Put examples longer than ~20 lines here, split by use case:
 
-### assets/
-Templates and configurations.
+- Use case 1: ...
+- Use case 2: ...
+EOF
 
-## Notes
+  cat > "$target_dir/references/troubleshooting.md" <<'EOF'
+# Troubleshooting & Edge Cases
 
-- Generated from official documentation
-- Code examples are complete and working
+Write as: symptom -> likely causes -> diagnosis -> fix.
 EOF
 fi
 
+# ==================== Summary ====================
+
 echo ""
-echo "✅ Created skill: $SKILL_NAME/"
+echo "OK: Skill generated: $target_dir/"
 echo ""
-echo "   $SKILL_NAME/"
-echo "   ├── SKILL.md"
-echo "   ├── assets/"
-echo "   ├── scripts/"
-echo "   └── references/"
-echo "       └── index.md"
+echo "Layout:"
+echo "  $target_dir/"
+echo "  |-- SKILL.md"
+echo "  |-- assets/"
+echo "  |-- scripts/"
+echo "  \\-- references/"
+echo "      \\-- index.md"
 echo ""
 echo "Next steps:"
-echo "  1. Edit $SKILL_NAME/SKILL.md"
-echo "  2. Add documentation to references/"
-echo "  3. Add helper scripts to scripts/"
-echo "  4. Add templates to assets/"
+echo "  1) Edit $target_dir/SKILL.md (triggers/boundaries/quick reference/examples)"
+echo "  2) Put long-form docs into $target_dir/references/ and update index.md"

+ 212 - 0
skills/claude-skills/scripts/validate-skill.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  validate-skill.sh <skill-dir> [--strict]
+
+What it does:
+  - Validates SKILL.md YAML frontmatter (name/description)
+  - Performs lightweight structural checks
+  - In --strict mode, enforces the recommended section layout
+
+Examples:
+  ./skills/claude-skills/scripts/validate-skill.sh skills/postgresql
+  ./skills/claude-skills/scripts/validate-skill.sh skills/my-skill --strict
+EOF
+}
+
+die() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+warn() {
+  echo "Warning: $*" >&2
+}
+
+strict=0
+skill_dir=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --strict)
+      strict=1
+      shift
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      die "Unknown argument: $1 (use --help)"
+      ;;
+    *)
+      if [[ -z "$skill_dir" ]]; then
+        skill_dir="$1"
+        shift
+      else
+        die "Extra argument: $1 (only one <skill-dir> is allowed)"
+      fi
+      ;;
+  esac
+done
+
+[[ -n "$skill_dir" ]] || { usage; exit 1; }
+[[ -d "$skill_dir" ]] || die "Not a directory: $skill_dir"
+
+skill_md="$skill_dir/SKILL.md"
+[[ -f "$skill_md" ]] || die "Missing SKILL.md: $skill_md"
+
+base_name="$(basename -- "${skill_dir%/}")"
+
+# -------------------- Parse YAML frontmatter --------------------
+
+frontmatter=""
+if frontmatter="$(
+  awk '
+    BEGIN { in_fm=0; closed=0 }
+    NR==1 {
+      if ($0 != "---") exit 2
+      in_fm=1
+      next
+    }
+    in_fm==1 {
+      if ($0 == "---") { closed=1; exit 0 }
+      print
+      next
+    }
+    END {
+      if (closed == 0) exit 3
+    }
+  ' "$skill_md"
+)"; then
+  :
+else
+  rc=$?
+  case "$rc" in
+    2) die "SKILL.md must start with YAML frontmatter (--- as the first line)" ;;
+    3) die "YAML frontmatter is not closed (missing ---)" ;;
+    *) die "Failed to parse YAML frontmatter (awk exit=$rc)" ;;
+  esac
+fi
+
+name="$(
+  printf "%s\n" "$frontmatter" | awk -F: '
+    tolower($1) ~ /^name$/ {
+      sub(/^[^:]*:[[:space:]]*/, "", $0)
+      gsub(/[[:space:]]+$/, "", $0)
+      print
+      exit
+    }
+  '
+)"
+
+description="$(
+  printf "%s\n" "$frontmatter" | awk -F: '
+    tolower($1) ~ /^description$/ {
+      sub(/^[^:]*:[[:space:]]*/, "", $0)
+      gsub(/[[:space:]]+$/, "", $0)
+      print
+      exit
+    }
+  '
+)"
+
+[[ -n "$name" ]] || die "Missing frontmatter field: name"
+[[ -n "$description" ]] || die "Missing frontmatter field: description"
+
+if [[ ! "$name" =~ ^[a-z][a-z0-9-]*$ ]]; then
+  die "Invalid name: '$name' (expected ^[a-z][a-z0-9-]*$)"
+fi
+
+if [[ "$strict" -eq 1 && "$name" != "$base_name" ]]; then
+  die "Strict mode: frontmatter name ('$name') must match directory name ('$base_name')"
+fi
+
+# -------------------- Strip fenced code blocks for section checks --------------------
+
+filtered_md="$(mktemp)"
+trap 'rm -f "$filtered_md"' EXIT
+
+awk '
+  BEGIN { in_fence=0 }
+  /^[[:space:]]*```/ { in_fence = !in_fence; next }
+  in_fence==0 { print }
+' "$skill_md" > "$filtered_md"
+
+# -------------------- Structural checks --------------------
+
+required_h2=(
+  "When to Use This Skill"
+  "Not For / Boundaries"
+  "Quick Reference"
+  "Examples"
+  "References"
+  "Maintenance"
+)
+
+for title in "${required_h2[@]}"; do
+  if ! grep -Eq "^##[[:space:]]+${title}([[:space:]]*)$" "$filtered_md"; then
+    if [[ "$strict" -eq 1 ]]; then
+      die "Strict mode: missing required section heading: '## ${title}'"
+    fi
+    warn "Missing recommended section heading: '## ${title}'"
+  fi
+done
+
+# references/index.md presence (only enforced in strict mode when references/ exists)
+if [[ -d "$skill_dir/references" && "$strict" -eq 1 && ! -f "$skill_dir/references/index.md" ]]; then
+  die "Strict mode: references/ exists but references/index.md is missing"
+fi
+
+# -------------------- Heuristics: Quick Reference size --------------------
+
+quick_start="$(awk 'match($0, /^##[[:space:]]+Quick Reference([[:space:]]*)$/){print NR; exit}' "$filtered_md" || true)"
+if [[ -n "$quick_start" ]]; then
+  quick_end="$(awk -v s="$quick_start" 'NR>s && match($0, /^##[[:space:]]+/){print NR; exit}' "$filtered_md" || true)"
+  total_lines="$(wc -l < "$filtered_md" | tr -d ' ')"
+  if [[ -z "$quick_end" ]]; then
+    quick_end="$((total_lines + 1))"
+  fi
+  quick_len="$((quick_end - quick_start - 1))"
+  if [[ "$quick_len" -gt 250 ]]; then
+    if [[ "$strict" -eq 1 ]]; then
+      die "Strict mode: Quick Reference section is too long (${quick_len} lines). Move long-form text into references/."
+    fi
+    warn "Quick Reference section is large (${quick_len} lines). Consider moving long-form text into references/."
+  fi
+fi
+
+# -------------------- Heuristics: Examples count --------------------
+
+examples_start="$(awk 'match($0, /^##[[:space:]]+Examples([[:space:]]*)$/){print NR; exit}' "$filtered_md" || true)"
+if [[ -n "$examples_start" ]]; then
+  examples_end="$(awk -v s="$examples_start" 'NR>s && match($0, /^##[[:space:]]+/){print NR; exit}' "$filtered_md" || true)"
+  total_lines="$(wc -l < "$filtered_md" | tr -d ' ')"
+  if [[ -z "$examples_end" ]]; then
+    examples_end="$((total_lines + 1))"
+  fi
+
+  example_count="$(
+    awk -v s="$examples_start" -v e="$examples_end" '
+      NR>s && NR<e && match($0, /^###[[:space:]]+Example([[:space:]]|$)/) { c++ }
+      END { print c+0 }
+    ' "$filtered_md"
+  )"
+
+  if [[ "$example_count" -lt 3 ]]; then
+    if [[ "$strict" -eq 1 ]]; then
+      die "Strict mode: expected >= 3 examples (found ${example_count})."
+    fi
+    warn "Recommended: >= 3 examples (found ${example_count})."
+  fi
+fi
+
+echo "OK: $skill_dir"