开发者指南¶

面向 Impeccable 贡献者的文档。

架构¶

位于 skill/ 的技能会由配置驱动的工厂转换为各 provider 特有的格式。每个 provider 都被定义为 scripts/lib/transformers/providers.js 中的一个配置对象——新增 provider 只需添加一条新配置项。

有关完整的 harness 能力（各 provider 支持的 frontmatter 字段、占位符体系、目录结构），请参阅 HARNESSES.md。

源格式¶

技能（`skill/SKILL.src.md`）¶

---
name: skill-name
description: What this skill provides
argument-hint: "[target]"
user-invocable: true
license: License info (optional)
compatibility: Environment requirements (optional)
---

Your skill instructions here...

Frontmatter 字段（基于 Agent Skills 规范）： - name（必填）：技能标识符（1-64 个字符，小写字母/数字/连字符） - description（必填）：技能提供的功能说明（1-1024 个字符） - user-invocable（可选）：布尔值——若为 true，该技能可作为斜杠命令调用 - argument-hint（可选）：自动补全时显示的提示（例如 [target]、[area (feature, page...)]） - license（可选）：许可证/署名信息 - compatibility（可选）：环境要求（1-500 个字符） - metadata（可选）：任意键值对 - allowed-tools（可选，实验性）：预先批准的工具列表

正文占位符（构建期间按 provider 替换）： - {{model}}——provider 特有的模型名称（例如 "Claude"、"Gemini"、"GPT"） - {{config_file}}——provider 特有的配置文件（例如 "CLAUDE.md"、".cursorrules"） - {{ask_instruction}}——如何向用户请求澄清 - {{command_prefix}}——斜杠命令前缀（多数为 /，Codex 为 $） - {{available_commands}}——用户可调用命令的逗号分隔列表

构建¶

开发者实验室 URL¶

无索引（no-index）的视觉 harness 与内部检查器位于 /labs/<subject> 下。使用简短的主题名词（/labs/live-ui，后续可用 /labs/detector），而不要添加第二个 -lab 后缀。/docs 和 /design-system 等稳定的公共引用保持在顶层。当某个 lab 迁移时，通过重定向让旧的顶层 lab 路由继续可用；在该页面下次变更时迁移现有例外，而不是复制页面。

先决条件¶

Bun（快速的 JavaScript 运行时和包管理器）
无需外部依赖

命令¶

# Build all provider formats
bun run build

# Clean dist folder
bun run clean

# Rebuild from scratch
bun run rebuild

生成内容¶

source/                          -> dist/
  skills/{name}/SKILL.md           {provider}/{configDir}/skills/{name}/SKILL.md

每个 provider 都有自己的输出目录。

构建系统细节¶

构建系统在 scripts/ 下采用工厂模式：

scripts/
  build.js                        # Main orchestrator
  lib/
    utils.js                      # Frontmatter parsing, placeholder replacement, YAML generation
    zip.js                        # ZIP bundle generation
    transformers/
      factory.js                  # createTransformer() -- generates transformer functions from config
      providers.js                # PROVIDERS config map -- one entry per provider
      index.js                    # Re-exports factory-generated transformer functions

新增 Provider¶

在 scripts/lib/utils.js 的 PROVIDER_PLACEHOLDERS 中添加一条占位符配置：

'my-provider': {
  model: 'MyModel',
  config_file: 'CONFIG.md',
  ask_instruction: 'ask the user directly to clarify.',
  command_prefix: '/'
}

在 scripts/lib/transformers/providers.js 的 PROVIDERS 中添加一条 provider 配置：

'my-provider': {
  provider: 'my-provider',
  configDir: '.my-provider',
  displayName: 'My Provider',
  frontmatterFields: ['user-invocable', 'argument-hint', 'license'],
}

运行 bun run build——该 provider 会被构建循环自动识别。
在 HARNESSES.md 中更新该 provider 的能力说明。

Provider 配置选项¶

字段	描述
`provider`	输出目录和占位符查找所用的键
`configDir`	点目录名称（例如 `.claude`）
`displayName`	供构建日志阅读的名称
`frontmatterFields`	要输出的可选字段（参见 `factory.js` 中的 `FIELD_SPECS`）
`bodyTransform`	可选的后处理函数 `(body, skill) => body`
`placeholderProvider`	覆盖所使用的 `PROVIDER_PLACEHOLDERS` 键（用于共享配置的变体）

关键函数¶

createTransformer(config)：根据 provider 配置返回一个 transformer 函数的工厂
parseFrontmatter()：从 SKILL.md 文件中提取 YAML frontmatter 和正文
readSourceFiles()：读取 skill/SKILL.src.md 及其同级目录 reference/ 和 scripts/
replacePlaceholders()：按 provider 替换 {{model}}、{{config_file}} 等
generateYamlFrontmatter()：将对象序列化为 YAML frontmatter（自动为以 [ 或 { 开头的值添加引号）

测试¶

bun run test                  # Default suite — unit + static fixtures (no API keys needed)
bun run test:live-e2e         # Opt-in — full-cycle live-mode E2E across framework fixtures (~2 min, needs `npx playwright install chromium` once)
bun run test:skill-behavior   # Opt-in — LLM-backed checks that the SKILL.md Setup flow actually drives the agent (~5 min, costs cents, needs `.env`)

skill-behavior 测试套件会运行三个 provider（claude-haiku-4-5、gpt-5.4-mini、gemini-3.1-flash-lite——每次运行都取各家最便宜的档位），并将源文件 skill/SKILL.src.md 内联为系统提示词，同时提供限定工作区范围的 bash/read/write/list 工具集。随后它会基于工具调用追踪进行断言，而不是基于自由格式输出。每当你修改 skill/SKILL.src.md 的 Setup 部分、skill/scripts/context.mjs，或任何涉及 Setup 的引用（teach.md、document.md、brand.md、product.md、子命令引用）时，都应运行该套件。各场景的断言及当前基线（21-22/24）位于 tests/skill-behavior/README.md。Provider 密钥位于仓库根目录的 .env（已加入 gitignore）；缺少密钥时会干净地跳过相应测试。

最佳实践¶

编写技能¶

聚焦范围：每个技能只覆盖一个明确的领域
清晰的描述：让目的一目了然
明确的指令：LLM 应准确理解要做什么
包含示例：当示例能阐明意图时提供示例
说明约束：什么不该做，要像什么该做一样清晰
跨提供方测试：验证其在多种环境中都能正常工作。对于针对 skill/ 的设置相关修改，bun run test:skill-behavior 可跨三个提供方自动完成此测试。

参考文档¶

Agent Skills Specification - 开放标准
HARNESSES.md - 提供方能力矩阵
Cursor Skills
Claude Code Skills
DeepSeek Harness
Gemini CLI Skills
Codex CLI Skills
VS Code Copilot Skills
Kiro Skills
OpenCode Skills
Pi Skills
Qoder Skills
Mistral Vibe Skills
Grok Build Skills, Plugins & Marketplaces
Grok Build Hooks

仓库结构¶

impeccable/
  skill/                           # Edit these! Source of truth
    SKILL.src.md                   # Frontmatter, shared design laws, command router
    reference/                     # One <command>.md per command + domain references
    scripts/                       # Skill runtime scripts (hooks, context.mjs, etc.)
    agents/                        # Nested subagent definitions
  cli/                             # Standalone `impeccable` CLI (npm package)
  site/                            # impeccable.style (Astro)
  extension/                       # Chrome extension
  functions/                       # Cloudflare Pages Functions
  plugin/                          # Committed Claude Code plugin build output
  dist/                            # Generated provider output (gitignored)
  scripts/
    build.js                       # Main orchestrator
    lib/
      utils.js                     # Shared utilities
      zip.js                       # ZIP generation
      transformers/
        factory.js                 # Config-driven transformer factory
        providers.js               # Provider config map
        index.js                   # Re-exports
  tests/                           # Bun test suite
  docs/
    HARNESSES.md                   # Provider capabilities reference
    STYLE.md                       # Editorial style guide
    adr-live-variant-mode.md       # Live mode architecture decision record
    DEVELOP.md                     # This file
  README.md                        # User documentation

故障排查¶

构建因 YAML 解析错误而失败¶

检查 frontmatter 缩进（YAML 对缩进敏感）
确保 --- 分隔符独占一行
以 [ 或 { 开头的值会自动加引号；其他特殊 YAML 字符可能需要手动加引号

输出与预期不符¶

检查 scripts/lib/transformers/providers.js 中的 provider 配置
确认源文件具有正确的 frontmatter 结构
运行 bun run rebuild 以确保干净的构建

提供方无法识别文件¶

检查你的提供方的安装路径
确认文件命名符合提供方要求
查阅 HARNESSES.md 了解提供方相关的详细信息

有疑问？¶

先开一个 issue。如果维护者认可方向，可主动提出用 PR 跟进。长期贡献者 pbakaus 和 abdulwahabone 可以直接开 PR。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 im/impeccable