Agent skill

Skill Optimization

by shinpr in shinpr/ai-coding-project-boilerplate

使用 9 种内容模式和 10 条编辑原则评估并优化技能文件质量。适用于创建技能、完善技能内容或审计技能质量的场景. An agent skill from shinpr/ai-coding-project-boilerplate.

MITAuto-check passed

Install Skill Optimization

skills CLI
$ npx skills add shinpr/ai-coding-project-boilerplate --skill skill-optimization -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install shinpr/ai-coding-project-boilerplate skill-optimization --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/shinpr/ai-coding-project-boilerplate.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills-zh-CN/skill-optimization .claude/skills/skill-optimization && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
skill-optimization
GitHub stars
232
Token cost
~1.4k tokens
SKILL.md length
289 words
Files
3 (incl. references)
Skills in repo
42
Repo updated
First seen
Licence
MIT

At a glance

使用 9 种内容模式和 10 条编辑原则评估并优化技能文件质量。适用于创建技能、完善技能内容或审计技能质量的场景. An agent skill from shinpr/ai-coding-project-boilerplate.

  • Works in 6 steps: 基于发现:每次变更都应解决一个已记录的问题,或遵循一个具名的项目专属来源 → 具体化:每种模式都提供检测标准和转换方法 → 聚焦结构:优化表达和组织方式;领域知识本身保持不变 → …
  • SKILL.md covers 核心理念, 内容优化模式, 10 条技能编辑原则 and 参考资料
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Skill Optimization is an agent skill from shinpr/ai-coding-project-boilerplate. 使用 9 种内容模式和 10 条编辑原则评估并优化技能文件质量。适用于创建技能、完善技能内容或审计技能质量的场景。

Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including reference files (for example `references/creation-guide.md` and `references/review-criteria.md`).

The repository describes itself as: Agentic coding TypeScript boilerplate for Claude Code: sub-agent workflows with built-in quality checks and context engineering. The licence is MIT.

Example prompts

  • “/skill-optimization”

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. 基于发现:每次变更都应解决一个已记录的问题,或遵循一个具名的项目专属来源
  2. 具体化:每种模式都提供检测标准和转换方法
  3. 聚焦结构:优化表达和组织方式;领域知识本身保持不变
  4. 保留意图:在改变结构、措辞、约束、上下文或示例之前,记录原始需求
  5. 可追溯:将每一处应用的变更关联到一个发现或具名的项目来源
  6. 自包含:确保每个纯技能在单独加载时都可独立执行;当每份副本都是独立执行所必需时,跨多个独立加载的纯技能之间的重复内容是合理的

What it can do on your machine

Read from SKILL.md and the folder at commit 56913a2. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Skill Optimization loads about 1.4k tokens when it runs, and up to ~3.8k if it reads all its reference files. Until then it costs about 19 tokens; SKILL.md has 289 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~19
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from shinpr/ai-coding-project-boilerplate at commit 56913a2, republished under its MIT licence (© shinpr). 289 words, ~1,412 tokens.

Download SKILL.mdSave it as .claude/skills/skill-optimization/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
skill-optimization
description
使用 9 种内容模式和 10 条编辑原则评估并优化技能文件质量。适用于创建技能、完善技能内容或审计技能质量的场景。

技能内容优化

核心理念

  1. 基于发现:每次变更都应解决一个已记录的问题,或遵循一个具名的项目专属来源
  2. 具体化:每种模式都提供检测标准和转换方法
  3. 聚焦结构:优化表达和组织方式;领域知识本身保持不变
  4. 保留意图:在改变结构、措辞、约束、上下文或示例之前,记录原始需求
  5. 可追溯:将每一处应用的变更关联到一个发现或具名的项目来源
  6. 自包含:确保每个纯技能在单独加载时都可独立执行;当每份副本都是独立执行所必需时,跨多个独立加载的纯技能之间的重复内容是合理的

内容优化模式

P1:关键问题(必须修复)

会直接降低 LLM 使用该技能时执行准确性的问题。

BP-001:否定式指令 → 正向表达
检测转换
技能指令中出现“不要”、“禁止”、“永远不要”、“避免”首先陈述期望的动作或允许的状态。仅当违反行为是不可逆的操作性动作、调用方通常无法恢复、且纯正向改写会模糊边界时,才保留明确的禁止性表述。将禁止性表述与安全替代方案以及允许跨越该边界的条件配对。可评审的质量策略应改写为正向形式。

例外边界示例:

  • 允许保留:“将过期记录移至可恢复的归档区。除非用户明确授权永久删除,否则不要永久删除它们。”
  • 改写为正向形式:“不要臆造问题” → “每个问题都应基于 BP 模式或 10 条原则”、“不要跳过 P1 问题” → “在每次评审中评估所有 P1 问题”、“存在 P1 问题时不要给 A 级” → “仅当 P1 数量为零时才给出 A 级”

质量策略、角色边界、评分标准和一般工作规则始终使用正向表达。调用方会校验、覆盖或丢弃的输出永远不是不可逆的。

技能示例:

  • 修改前:“不要使用通用变量名”
  • 修改后:“使用能反映用途的描述性变量名(例如 userId 而非 x)”

为何对技能而言是关键问题:仅有禁止性表述,会使可执行的目标状态无从确定。

BP-002:模糊指令 → 具体标准
检测转换
模糊用词(“恰当”、“良好”、“合适”、“最佳”、“应当清晰”)遗留了一个预期成果所需的决策,且不同的合理解读会实质性改变执行或验证方式按照下面的解决步骤,用限制最少但足够充分的标准来解决
未指定的格式、长度、范围、语气或成功标准,只要不同的合理解读同样能满足预期结果视为可接受的灵活性;仅当只有一种解读符合要求时才添加约束(如下游使用方需要特定格式,参见 BP-003)

解决步骤(针对第一行的发现):

  1. 选择限制最少但足够充分的标准——即在排除最少有效行为的前提下,提供所需精确度的可衡量的 if-then 规则或阈值。
  2. 记录其精确度贡献:它为预期结果所改进的可观测输出差异。
  3. 记录其约束成本:它排除了原始意图中哪些本来有效的解决方案。
  4. 只有当精确度贡献可识别、且约束成本仍保留原始意图时,才应用该标准。
  5. 当输入或项目上下文无法确定该决策时,记录所需的来源,而不是凭空猜测。

技能例外:LLM 能从输入上下文中明确解决的表述(例如“用户遗留的空白之处”,当用户的提示词可供比对时)不算模糊——它描述的是确定性操作,而非主观判断。

技能示例:

  • 修改前:“适当地处理错误”
  • 修改后(标准来自具名来源):“遵循项目错误处理策略(docs/error-handling.md):对外部 API 调用、文件 I/O 和 JSON.parse 使用 try-catch 包裹;记录 error.name、error.stack 和时间戳;当调用方必须处理该错误时,携带上下文重新抛出。”
  • 修改后(无可用来源):“将‘错误处理策略’记录为所需来源,而不是臆造 try-catch 目标、日志字段或阈值。”

为何对技能而言是关键问题:模糊指令会迫使模型在没有给定标准的情况下,选择一个影响结果的行为。

BP-003:缺失输出格式 → 结构化输出
检测转换
技能描述了要做什么,但未说明预期的交付物格式添加输出章节,定义输出使用方(解析、路由、比对、验证)所需的结构、字段和顺序,而非按惯例随意选择格式

对于技能评审,输出契约包含 BP-001 至 BP-009 的覆盖情况、稳定的发现 ID、严重程度、位置、引用依据、有依据的拒绝项、需保留的要求、未解决的输入,以及最终评级。对于技能创建,输出是完整的 SKILL.md 内容,加上任何所需的同目录引用文件或脚本。

技能示例:

  • 修改前:“分析代码中的问题”
  • 修改后(评审报告使用方所需的格式):“输出 ## Issues Found 作为报告渲染器可解析的表格:| 严重程度 | 位置 | 描述 | 建议修复方案 |”

为何对技能而言是关键问题:结构化输出约束能减少幻觉,并使技能结果保持一致。

BP-009:无边界的工作生成 → 相称的工作量
检测转换
一个发现、可能性或技术上有效的改进,在不改变结果、必需边界、真实使用方或必要证明的情况下变成了强制项将其视为候选项;保留必需的工作,并允许无变更、复用以及有依据支持的拒绝
研究广度决定了实现或产物的范围一旦预期结果可被观察到即停止;单纯的发现本身不应扩大工作范围

为何对技能而言是关键问题:能力强的模型会执行隐含的义务,因此缺乏支撑依据的可能性会凭空制造出并不能改善结果的工作。

P2:高影响(应当修复)

处理后能提升技能有效性的问题。

BP-004:非结构化内容 → 有组织的格式
检测转换
一大段文字没有标题分隔应用标准章节顺序(见下文)
一个章节中混杂了多个主题拆分为各自独立的带标题章节
参考数据未使用表格呈现将标准/模式列表转换为表格

标准技能章节顺序:

  1. 上下文/前置条件
  2. 核心概念(定义、模式)
  3. 流程/方法论(分步说明)
  4. 输出格式/示例
  5. 质量检查清单
  6. 参考资料

条件性:如果技能文件少于 30 行且只涉及单一主题,可跳过重新结构化。

BP-005:缺失或过多的上下文 → 必要且充分的上下文
检测转换
技能假设了未言明的已知知识添加“前置条件”章节,列出所需上下文
使用了领域术语但未加以定义内联添加定义,或放入术语表。技能例外:属于 LLM 基础知识范围内的术语(广泛使用的技术术语、标准领域词汇)无需定义。只有项目专属术语、内部命名约定或常见 LLM 训练数据之外的领域行话才需要明确定义。
没有“何时使用”的指引添加带具体场景的触发条件
对下游没有影响,且内容重复、会分散注意力或不可执行的上下文将重复的事实浓缩为一条可操作的陈述;只有在需要提取出的事实时,才把原始背景信息保留在路径或引用之后;为项目专属事实标注来源

技能示例:

  • 修改前:“迁移时应用绞杀者(strangler)模式”
  • 修改后:“前置条件:存在具备可识别模块边界的现有单体应用。何时使用:在维持生产流量的同时替换遗留模块。”
BP-006:缺失或过多的流程控制 → 依据驱动的检查点
检测转换
若缺少前置依据,后续动作将失效添加检查点,指明所需依据和转换条件
权限、不可逆动作、机器读取的契约或完成证明是隐含的将该边界明确化
一个可逆的选择被规定为强制路径陈述目的、依据和选择标准;让模型自行选择路径
某检查点要求特定标签或产物,尽管存在语义等价的依据除非机器读取方要求确切形式,否则应接受等价的依据

关键洞察:控制的是边界和所需依据,而非在两者之间预设的路径。

对于技能创建,依次使用三个检查点:

  1. 分析检查点:原始需求已记录、BP-001 至 BP-009 均已覆盖、每个问题都有依据、且没有未解决的输入阻碍工作的忠实完成。
  2. 优化检查点:每个发现都有一个已应用/已跳过的处理方式、每处变更均可追溯、且所有需保留的要求依然得到体现。
  3. 平衡检查点:意图保留、决策充分性、信息密度、约束必要性、工作量相称性和可追溯性均通过后,结果方为最终版本。

对于评审驱动的修复,以当前评审作为分析依据,并将优化检查点和平衡检查点应用于已接受的修复范围。

P3:增强项(可以修复)

针对特定场景的渐进式改进。

BP-007:不必要或有偏差的示例 → 最小必要示例集
检测转换
示例只是复述了 LLM 已知的行为替换为简洁的规则或使用方所需的输出形态,并移除这些示例
示例编码了领域、产品或组织专属的映射关系、非显而易见的例外情况,或规则无法表达的边界保留能覆盖这些映射关系的最小集合;将每个示例对应到它所消除的歧义
多个示例消除了相同的歧义,或所有示例都具有相同的表层模式缩减为能覆盖所有情况的最小集合;仅当能消除不同的歧义时才添加新的示例
BP-008:不允许存在不确定性 → 明确的上报机制
检测转换
技能要求始终给出确定性答案将断言分类为已观察、已推断或未知;为模糊情况添加上报标准
没有“何时停止”的指引当某个未知因素阻碍下一步时,在当前检查点停止,并指明继续所需的确切依据或用户决策

技能示例:

  • 修改前:“确定根本原因”
  • 修改后:“将根本原因分类为已观察、已推断或未知。当缺失的依据阻碍下一步时,在当前检查点停止,并指明继续所需的确切依据或用户决策。”

10 条技能编辑原则

针对技能内容的可衡量质量标准。每条原则都包含一个通过/未通过的测试。

#原则通过标准未通过示例
1上下文效率每句话都提供非基础性知识、决策规则、必需边界或执行依据复述基础行为,却没有给出对应的失败案例、评审发现或能体现执行影响的项目需求
2去重同一技能内,同一抽象层级的概念不应被解释两次。当每份副本都是独立执行所必需时,跨多个独立加载的纯技能之间的重复是合理的;应评估这些副本之间的语义一致性,而非将其替换为对同级技能的引用同一条规则在同一技能中出现两次,却没有增加不同的执行作用
3归类相关标准集中在单一章节中(减少查阅次数)错误处理规则分散在 4 个章节中
4可衡量性标准指明了可观测的依据、确定性决策规则或有依据支撑的阈值“编写整洁的代码”,却没有可观测的判定条件
5正向表达指令陈述应当做什么(应用了 BP-001)将“只使用 X”写成“不要使用 any”
6记法一致标题层级、列表样式、表格格式统一同一上下文中混用 -、*、1.
7前置条件明确项目专属及非基础性的前置条件均已陈述或提供链接;基础技术知识保持简洁使用 "DI" 却未定义 Dependency Injection(依赖注入)
8优先级排序最重要的条目在前,例外情况在后边界情况排在常见模式之前
9范围边界明确说明该技能覆盖的范围,以及激活条件性内容的条件。一个纯技能应包含独立执行所需的全部上下文。跨技能引用仅保留给承担编排或技能选择角色的技能使用某个纯技能因为另一个独立加载的技能中也包含某条可执行规则,就省略了该规则
10工作量相称性每一项必需的产物、测试、检查点或决策都应改变结果、边界、使用方结果或必要证明要求实现所有发现或所有技术上有效的改进

参考资料

© shinpr, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in .claude/skills-zh-CN/skill-optimization of shinpr/ai-coding-project-boilerplate.

  • SKILL.md
  • references/creation-guide.md
  • references/review-criteria.md

Open the folder on GitHubat commit 56913a2

More from shinpr/ai-coding-project-boilerplate

All 42 skills in this repo
  • Integration E2E Testing

    shinpr/ai-coding-project-boilerplate

    Selects and designs the smallest integration/E2E test set that proves accepted behavior at an observable boundary.

    232 GitHub stars~2.8k tokensUpdated 4 days ago
    Auto-check passed
  • Skill Optimization

    shinpr/ai-coding-project-boilerplate

    Evaluates and optimizes skill file quality using 9 content patterns and 10 editing principles.

    232 GitHub stars~3.5k tokensUpdated 4 days ago
    Auto-check passed
  • Frontend Technical Spec

    shinpr/ai-coding-project-boilerplate

    Defines React environment, component architecture, state/data flow, build verification, and frontend non-functional criteria from repository evidence.

    232 GitHub stars~1.9k tokensUpdated 4 days ago
    Auto-check: notes
  • Frontend Typescript Rules

    shinpr/ai-coding-project-boilerplate

    Applies React/TypeScript type safety, component design, and state management rules.

    232 GitHub stars~1.7k tokensUpdated 4 days ago
    Auto-check passed
  • Implementation Approach

    shinpr/ai-coding-project-boilerplate

    Selects implementation strategy (vertical slice, horizontal, or hybrid) with risk assessment.

    232 GitHub stars~3.2k tokensUpdated 4 days ago
    Auto-check passed
  • Subagents Orchestration Guide

    shinpr/ai-coding-project-boilerplate

    Coordinates subagents through scale-based planning, approval, implementation, verification, and escalation flows.

    232 GitHub stars~8k tokensUpdated 4 days ago
    Auto-check passed

Questions about Skill Optimization

What does Skill Optimization do?

使用 9 种内容模式和 10 条编辑原则评估并优化技能文件质量。适用于创建技能、完善技能内容或审计技能质量的场景. An agent skill from shinpr/ai-coding-project-boilerplate. Skill Optimization is an agent skill from shinpr/ai-coding-project-boilerplate.

How do I install Skill Optimization in Claude Code?

Run `npx skills add shinpr/ai-coding-project-boilerplate --skill skill-optimization -a claude-code`. Or copy the skill folder (.claude/skills-zh-CN/skill-optimization in shinpr/ai-coding-project-boilerplate) into .claude/skills/skill-optimization in your project. Claude Code loads it when a task matches its description.

How do I install Skill Optimization in Codex?

Run `npx skills add shinpr/ai-coding-project-boilerplate --skill skill-optimization -a codex`. Or copy the skill folder (.claude/skills-zh-CN/skill-optimization in shinpr/ai-coding-project-boilerplate) into .agents/skills/skill-optimization in your project. Codex loads it when a task matches its description.

Can I use Skill Optimization in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add shinpr/ai-coding-project-boilerplate --skill skill-optimization -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/skill-optimization, .gemini/skills/skill-optimization, .github/skills/skill-optimization and .opencode/skills/skill-optimization in your project.

What does Skill Optimization need to run?

SKILL.md names no scripts, command-line tools or credentials: Skill Optimization is instructions for the agent only.

Does Skill Optimization access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Skill Optimization safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Skill Optimization use?

Skill Optimization is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Skill Optimization use?

About 1.4k tokens (SKILL.md is roughly 5.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2.4k tokens, read only when the agent opens those files.

Who maintains Skill Optimization?

shinpr (a GitHub user) maintains it in shinpr/ai-coding-project-boilerplate, which has 232 GitHub stars. The repository holds 42 skills in this directory. The repository was last updated on October 4, 2026.

Source: shinpr/ai-coding-project-boilerplate on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.