技能创作
- 作者仓库星标 289
- 作者仓库 claude-night-market
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @athola · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Windows
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Skill Authoring Guide
## Overview
Writing effective Claude Code skills requires Test-Driven Development (TDD) and persuasion principles from compliance research. We treat skill writing as process documentation that needs empirical validation rather than just theoretical instruction. Skills are behavioral interventions designed to change model behavior in measurable ways.
By using TDD, we ensure skills address actual failure modes identified through testing. Optimized descriptions improve discovery, while a modular structure supports progressive disclosure to manage token usage. This framework also includes anti-rationalization patterns to prevent the assistant from bypassing requirements.
### The Iron Law
**NO SKILL WITHOUT A FAILING TEST FIRST**
Every skill must begin with documented evidence of Claude failing without it. This validates that you are solving a real problem. No implementation should proceed without a failing test, and no completion claim should be accepted without evidence. Detailed enforcement patterns for adversarial verification and coverage gates are available in `imbue:proof-of-work`.
## Skill Types
We categorize skills into three types: **Technique** skills for specific methods, **Pattern** skills for recurring solutions, and **Reference** skills for quick lookups and checklists. This helps organize interventions into the most effective format for the task.
## Quick Start
### Skill Analysis
\`\`\`bash
# Analyze skill complexity
python scripts/analyze.py
# Estimate tokens
python scripts/tokens.py
\`\`\`
### Validation
\`\`\`bash
# Validate skill structure
python scripts/abstract_validator.py --check
\`\`\`
**Verification**: Run analysis and review token estimates before proceeding.
## Description Optimization
Skill descriptions must be optimized for semantic search and explicit triggering. Follow the formula `[What it does] + [When to use it] + [Key triggers]`. Use a third-person voice (e.g., "Guides...", "Provides...") and include specific, concrete use cases. Avoid marketing language or vague phrases like "helps with coding."
### Skill Character Budget (Claude Code 2.1.32+)
Skill description character budgets now **scale with context window** at 2% of available context. This means:
| Context Window | Description Budget |
|---------------|-------------------|
| 200K (Sonnet/Haiku) | ~4,000 characters |
| 1M (Opus 4.6 GA) | ~20,000 characters |
Previously constrained skills can use more descriptive text on larger windows. However, keep descriptions concise regardless — longer is not better. The scaling primarily prevents truncation for skills with legitimately complex trigger conditions, not as an invitation to add verbose content.
### Plugin Name Auto-Display (Claude Code 2.1.33+)
Plugin names are now automatically shown alongside skill descriptions in the `/skills` menu. Do not repeat the plugin name in skill descriptions — it is redundant and wastes character budget. Focus descriptions on what the skill does and when to use it.
## The TDD Cycle for Skills
### RED Phase: Document Baseline Failures
Establish empirical evidence that an intervention is needed. Create at least three pressure scenarios that combine time pressure and ambiguity. Run these in a fresh instance without the skill active and document the exact failures, such as skipped error handling or missing validation.
### GREEN Phase: Minimal Skill Implementation
Create the smallest intervention that addresses the documented failures. Write the `SKILL.md` with required frontmatter and content that directly counters the baseline failures. Include one example of correct behavior and verify that the same pressure scenarios now show measurable improvement.
### REFACTOR Phase: Anti-Rationalization
Eliminate the ability for Claude to explain away requirements. Run pressure scenarios with the skill active to identify common rationalizations, such as claiming a task is "too simple" for the full process. Add explicit counters, such as exception tables and red flag lists, until rationalizations stop.
## Anti-Rationalization
Skills must explicitly counter patterns where Claude attempts to bypass requirements. Common excuses include claiming a task is "too simple" or that a "spirit vs letter of the law" approach is sufficient. Skills should include red flag lists for self-checking, such as "Stop if you think: this is too simple for the full process." When exceptions are necessary, document them explicitly to prevent unauthorized shortcuts.
## Module References
For detailed implementation guidance:
**Core authoring cycle:**
- **TDD Methodology**: See `modules/tdd-methodology.md` for RED-GREEN-REFACTOR cycle details
- **Persuasion Principles**: See `modules/persuasion-principles.md` for compliance research and techniques
- **Description Writing**: See `modules/description-writing.md` for discovery optimization
- **Progressive Disclosure**: See `modules/progressive-disclosure.md` for file structure patterns
- **Anti-Rationalization**: See `modules/anti-rationalization.md` for bulletproofing techniques
- **Graphviz Conventions**: See `modules/graphviz-conventions.md` for process diagram standards
**Working with concrete skills (load when implementing or debugging):**
- **Annotated Examples**: See `modules/examples.md` for walk-throughs of well-authored skills in this repo
- **Advanced Patterns**: See `modules/advanced-patterns.md` for skill-to-skill coordination, conditional behavior, and scaling across activation contexts
- **Authentication**: See `modules/authentication.md` for skills that invoke `gh`, `glab`, MCP servers, or other authenticated tools
- **Error Handling**: See `modules/error-handling.md` for missing tools, timeouts, partial subagent results, and permission denials
- **Troubleshooting**: See `modules/troubleshooting.md` for diagnosing skills that do not behave as the test corpus says they should
**Validation and deployment (load when shipping):**
- **Validation**: See `modules/validation.md` for frontmatter parsing, reference resolution, and structural checks before merge
- **Testing with Subagents**: See `modules/testing-with-subagents.md` for running the Iron Law test in a fresh subagent (and `abstract:subagent-testing` for the broader pressure-testing methodology)
- **Deployment Checklist**: See `modules/deployment-checklist.md` for final validation before promoting a skill
## Deployment and Quality Gates
Before deploying, verify that the RED, GREEN, and REFACTOR phases are complete and documented. Frontmatter must be valid, descriptions optimized, and line counts kept under 500 lines. Ensure all module references are valid and at least one concrete example is included.
### Scribe Validation
All markdown files must pass scribe validation. This includes a slop scan to ensure a score under 2.5 and doc verification to confirm all file paths and command examples work. Bullet-to-prose ratios must remain under 60% to maintain readability. Use `Skill(scribe:slop-detector)` and `Agent(scribe:doc-verifier)` for these checks.
## Integration and Best Practices
Individual skills are created using `skill-authoring`, while `modular-skills` handles the architecture of larger structures. `skills-eval` provides ongoing quality assessment. Avoid the common pitfall of writing skills based on theoretical behavior; always use documented failures to guide development. Use progressive disclosure to prevent monolithic files and ensure that each intervention remains focused and token-efficient.
## Skill Directory Variable (2.1.69+)
Skills can reference their own directory using
`${CLAUDE_SKILL_DIR}` in SKILL.md content. This
variable resolves to the absolute path of the
directory containing the SKILL.md file. Use it for
referencing sibling files, data assets, or module
paths without hardcoding absolute paths:
```markdown
See `${CLAUDE_SKILL_DIR}/modules/advanced-patterns.md`
for detailed patterns.
Run: `python3 ${CLAUDE_SKILL_DIR}/scripts/check.py`
```
This is especially useful for skills that ship
alongside scripts or data files and need portable
path references that work regardless of where the
plugin is installed.
### Description Colon Fix (2.1.69+)
Skill descriptions containing colons (e.g.,
`description: "Triggers include: X, Y, Z"`) previously
failed to load from SKILL.md frontmatter. This is
fixed in 2.1.69. Skills without a `description:` field
also now appear in the available skills list (previously
they were silently excluded).
## Troubleshooting
### Common Issues
**Skill not loading**
Check YAML frontmatter syntax and required fields.
As of 2.1.69, skills without a `description:` field
still appear in the skills list, but descriptions
with colons must be quoted in YAML frontmatter.
**Token limits exceeded**
Use progressive disclosure - move details to modules
**Modules not found**
Verify module paths in SKILL.md are correct
章节与文件索引
按说明文件中的顺序排列。
概述
铁律
技能类型
技能分析
验证
文件/命令 -> imbue:proof-of-work · [What it does] + [When to use it] + [Key triggers] · /skills · modules/tdd-methodology.md · modules/persuasion-principles.md · modules/description-writing.md · modules/progressive-disclosure.md · modules/anti-rationalization.md
内容校验值 -> e10c31ff07e4
当前原文的自动摘译,尚未人工审校。
概述
编写有效的 Claude 代码技能需要测试驱动开发 (TDD) 和来自合规性研究的说服原则。 我们将技能写作视为需要经验验证而不仅仅是理论指导的过程文档。
铁律
没有首先通过失败的测试就没有技能 每一项技能都必须从克劳德没有失败的书面证据开始。这证明您正在解决一个真正的问题。没有失败的测试就不应实施任何实施,并且在没有证据的情况下不应接受任何完成声明。
imbue:proof-of-work提供了对抗性验证和覆盖门的详细执行模式。技能类型
我们将技能分为三种类型:特定方法的技术技能、重复解决方案的模式技能以及快速查找和清单的参考技能。这有助于将干预措施组织成最有效的任务形式。
技能分析
```bash 分析技能复杂度 python scripts/analyze.py 估计 token python scripts/tokens.py
验证
```bash Validate skill structure python scripts/abstract_validator.py --check ``` 验证:在继续之前运行分析并检查令牌估计。