Back to Details

template-skill-enhanced

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Enhanced Skill Template

增强版Skill模板

A production-ready skill template demonstrating progressive disclosure, bundled resource patterns, and quality validation. Use this template when creating skills that require tiered content loading, reference file organization, or structured quality scoring.
一款具备生产就绪能力的Skill模板，展示了渐进式披露、捆绑资源模式和质量验证方法。当你需要创建支持分层内容加载、参考文件组织或结构化质量评分的Skill时，请使用此模板。

When to Use This Skill

适用场景

  • Creating a new skill that needs progressive disclosure (tiered content loading)
  • Building skills with bundled resources (references, examples, validation rubrics)
  • Designing skills that exceed basic template complexity
  • Setting up skills with quality targets and scoring rubrics
  • Avoid using for simple, single-purpose skills — use 
    template-skill
    instead
  • 创建需要渐进式披露（分层内容加载）的新Skill
  • 构建包含捆绑资源（参考资料、示例、验证评估标准）的Skill
  • 设计复杂度超出基础模板的Skill
  • 搭建带有质量目标和评分标准的Skill
  • 简单的单一用途Skill请勿使用此模板，请改用
    template-skill

Workflow

工作流程

Step 1: Set Up Frontmatter

步骤1：设置前置元数据

Define metadata with kebab-case name, quoted description including a "Use when" clause, version, and tags:
yaml
---
name: my-new-skill
description: "Clear description of what this skill does. Use when [specific trigger condition]."
version: 1.0.0
tags: [domain, category]
---
使用短横线命名法（kebab-case）定义元数据，包含带引号的描述（需包含“适用场景”条款）、版本和标签：
yaml
---
name: my-new-skill
description: "Clear description of what this skill does. Use when [specific trigger condition]."
version: 1.0.0
tags: [domain, category]
---

Step 2: Write Core Principles (Tier 1 — Always Loaded)

步骤2：编写核心原则（层级1 — 始终加载）

The first section loads immediately on activation. Keep it under ~1000 tokens:
markdown
undefined
第一部分在激活时立即加载，内容控制在约1000token以内：
markdown
undefined

Core Principles

核心原则

Principle 1: Foundation Concept

原则1：基础概念

Explanation with a concise code example:
```python
附带简洁代码示例的说明：
python
undefined

Demonstrate the concept clearly

Demonstrate the concept clearly

def foundation_example(input_data): validated = validate(input_data) return transform(validated) ```
Key Points:
  • Critical aspect that must be understood
  • Common misconception to avoid
undefined
def foundation_example(input_data): validated = validate(input_data) return transform(validated)

**核心要点:**
- 必须理解的关键内容
- 需要避免的常见误区

Step 3: Add Implementation Patterns (Tier 2 — Loaded When Needed)

步骤3：添加实现模式（层级2 — 按需加载）

Detailed patterns for common scenarios (~1500 tokens):
markdown
undefined
针对常见场景的详细模式（约1500token）：
markdown
undefined

Pattern: Descriptive Name

模式：描述性名称

Problem: What specific problem this solves Solution: High-level approach
```python def pattern_implementation(input_data): validate(input_data) result = transform(input_data) return format_output(result) ```
Trade-offs:
AspectBenefitCost
PerformanceFast executionHigher memory
MaintainabilityClear structureMore boilerplate
undefined
问题：此模式解决的具体问题 解决方案：整体方法
python
def pattern_implementation(input_data):
    validate(input_data)
    result = transform(input_data)
    return format_output(result)
权衡分析:
维度优势成本
性能执行速度快内存占用更高
可维护性结构清晰冗余代码更多
undefined

Step 4: Add Advanced Usage (Tier 3 — Complex Scenarios)

步骤4：添加高级用法（层级3 — 复杂场景）

Reserve for sophisticated implementations (~2000+ tokens). Include edge cases:
ScenarioExpected BehaviorHandling Strategy
Empty inputGraceful failureReturn default or descriptive error
Invalid formatValidation errorClear error message with fix guidance
Resource exhaustionGraceful degradationBackoff and retry logic
用于复杂实现场景（约2000+token），包含边缘案例：
场景预期行为处理策略
空输入优雅失败返回默认值或描述性错误
格式无效验证错误提供清晰错误信息及修复指引
资源耗尽优雅降级退避重试逻辑

Step 5: Organize Bundled Resources

步骤5：组织捆绑资源

Create sibling directories for heavy content:
skills/my-new-skill/
├── SKILL.md                          # Core skill (under token budget)
├── references/
│   ├── README.md                     # Guide to reference docs
│   └── detailed-patterns.md          # Extended pattern documentation
├── examples/
│   └── basic.md                      # Annotated usage example
└── validation/
    └── rubric.yaml                   # Quality scoring rubric
为大容量内容创建同级目录：
skills/my-new-skill/
├── SKILL.md                          # 核心Skill（控制在token预算内）
├── references/
│   ├── README.md                     # 参考文档指南
│   └── detailed-patterns.md          # 扩展模式文档
├── examples/
│   └── basic.md                      # 带注释的用法示例
└── validation/
    └── rubric.yaml                   # 质量评分标准

Step 6: Define Quality Targets

步骤6：定义质量目标

Set measurable quality criteria:
yaml
quality_targets:
  clarity: ">= 4/5"
  completeness: ">= 4/5"
  accuracy: ">= 5/5"
  usefulness: ">= 4/5"
设置可衡量的质量标准：
yaml
quality_targets:
  clarity: ">= 4/5"
  completeness: ">= 4/5"
  accuracy: ">= 5/5"
  usefulness: ">= 4/5"

Step 7: Validate the Skill

步骤7：验证Skill

bash
cortex skills validate my-new-skill
cortex skills info my-new-skill --show-tokens
Ensure total token count stays within 500–8,000 tokens per CONTRIBUTING guidelines.
bash
cortex skills validate my-new-skill
cortex skills info my-new-skill --show-tokens
确保总token数符合贡献指南要求的500–8000token范围。

Best Practices

最佳实践

  • Progressive disclosure: Keep Tier 1 concise — load detail on demand
  • Bundled resources: Move lengthy examples and deep-dives to 
    references/
    or 
    examples/
  • Quality rubrics: Define scoring criteria in 
    validation/rubric.yaml
    so skill outputs can be evaluated consistently
  • Token budget: Core SKILL.md should stay under token limits; offload heavy content to sibling files
  • Real examples: Replace all placeholder content with domain-specific, working code
  • Kebab-case naming: Directories and skill names use lowercase hyphen-case
  • 渐进式披露：保持层级1内容简洁，按需加载详细内容
  • 捆绑资源：将冗长示例和深度分析移至
    references/
    或
    examples/
    目录
  • 质量评估标准：在
    validation/rubric.yaml
    中定义评分标准，确保Skill输出可被一致评估
  • Token预算：核心SKILL.md需控制在token限制内，将大容量内容转移至同级文件
  • 真实示例：将所有占位符内容替换为领域特定的可运行代码
  • 短横线命名法：目录和Skill名称使用小写短横线格式

Anti-Patterns

反模式

  • Placeholder content in production: Shipping 
    [Pattern Name]
    or 
    example_code_here()
    — always fill in real content
  • Monolithic skills: Putting everything in SKILL.md instead of using bundled resources
  • Missing "Use when" clause: Description must include activation context
  • Ignoring token budgets: Skills over 8,000 tokens slow activation and may be truncated
  • 生产环境使用占位符内容：发布
    [Pattern Name]
    或
    example_code_here()
    这类内容——务必填充真实内容
  • 单体Skill：将所有内容放入SKILL.md，而非使用捆绑资源
  • 缺失“适用场景”条款：描述中必须包含激活场景
  • 忽略Token预算：超过8000token的Skill会减慢激活速度，可能被截断