Back to Details

skill-authoring

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Package Documentation Skill Authoring Guide

套件文档Skill编写指南

This skill documents the methodology for creating Claude Code skills that document 
@rytass/*
packages.
本技能介绍了创建用于编写
@rytass/*
套件文档的Claude Code技能的方法。

Overview

概述

When creating skills for package documentation, follow this structured approach:
  1. Explore - Understand the package structure
  2. Plan - Design the skill architecture
  3. Implement - Write the skill files
  4. Refine - Add bilingual triggers and optimize
在创建套件文档相关技能时，请遵循以下结构化方法：
  1. 探索 - 理解套件结构
  2. 规划 - 设计技能架构
  3. 实现 - 编写技能文件
  4. 优化 - 添加双语触发词并进行优化

Phase 1: Exploration

第一阶段：探索

1.1 Identify Package Scope

1.1 确定套件范围

Determine which packages to document:
packages/{category}-*          # e.g., invoice-*, payments-*, storages-*
Questions to answer:
  • Is there a base package defining interfaces? (e.g., 
    @rytass/invoice
    )
  • How many adapter implementations exist?
  • What is the relationship between packages?
确定需要编写文档的套件：
packages/{category}-*          # 例如：invoice-*, payments-*, storages-*
需要回答的问题：
  • 是否有定义接口的基础套件？（例如：
    @rytass/invoice
    ）
  • 存在多少个适配器实现？
  • 各套件之间的关系是什么？

1.2 Analyze Package Exports

1.2 分析套件导出内容

For each package, identify:
CategoryWhat to Document
ClassesGateway, Entity, Allowance classes
InterfacesCore interfaces and their properties
EnumsAll enum values with descriptions
TypesType aliases and union types
FunctionsUtility functions with signatures
ConstantsExported constants and helpers
针对每个套件，确定需要文档化的内容：
分类文档内容
类Gateway、Entity、Allowance类
接口核心接口及其属性
枚举所有枚举值及说明
类型类型别名和联合类型
函数带签名的工具函数
常量导出的常量和辅助工具

1.3 Understand Usage Patterns

1.3 理解使用模式

Identify common operations:
  • Initialization / configuration
  • CRUD operations (create, read, update, delete)
  • Validation methods
  • Error handling patterns
识别常见操作：
  • 初始化/配置
  • CRUD操作（创建、读取、更新、删除）
  • 验证方法
  • 错误处理模式

Phase 2: Planning

第二阶段：规划

2.1 Determine Skill Structure

2.1 确定技能结构

Single Skill - For simple packages with limited scope
.claude/skills/{package-name}/
└── SKILL.md
Multi-File Skill - For complex packages (recommended for adapters)
.claude/skills/{package-name}/
├── SKILL.md              # Overview, quick start, comparison
├── {PROVIDER-1}.md       # Detailed reference
├── {PROVIDER-2}.md       # Detailed reference
└── ...
Dual Skill - When separating user vs developer concerns
.claude/skills/{package}-adapters/     # User-facing
.claude/skills/{package}-development/  # Developer-facing
单文件技能 - 适用于范围有限的简单套件
.claude/skills/{package-name}/
└── SKILL.md
多文件技能 - 适用于复杂套件（推荐用于适配器）
.claude/skills/{package-name}/
├── SKILL.md              # 概述、快速开始、对比
├── {PROVIDER-1}.md       # 详细参考
├── {PROVIDER-2}.md       # 详细参考
└── ...
双技能结构 - 区分用户与开发者场景
.claude/skills/{package}-adapters/     # 面向用户
.claude/skills/{package}-development/  # 面向开发者

2.2 Content Architecture

2.2 内容架构

SKILL.md (Main File) - Keep under 500 lines
SectionPurpose
OverviewWhat the packages do, unified interface
Installationnpm install commands
Quick StartMinimal working examples
Feature ComparisonTable comparing providers
Detailed Docs LinksLinks to reference files
Reference Files - One per provider/component
SectionPurpose
ConstructorParameters and initialization
MethodsAll public methods with signatures
ClassesEntity and value object classes
TypesProvider-specific type definitions
Complete ExampleFull working code sample
SKILL.md（主文件） - 内容控制在500行以内
章节用途
概述套件功能介绍、统一接口说明
安装npm安装命令
快速开始最简可运行示例
功能对比各提供商对比表格
详细文档链接指向参考文件的链接
参考文件 - 每个提供商/组件对应一个文件
章节用途
构造函数参数和初始化说明
方法所有带签名的公共方法
类实体和值对象类
类型提供商特定的类型定义
完整示例完整可运行代码示例

2.3 Progressive Disclosure Pattern

2.3 渐进式披露模式

SKILL.md (loaded first)
    │
    ├── Quick overview (always visible)
    ├── Common operations
    └── Links to details
            │
            └── PROVIDER.md (loaded on demand)
                    │
                    └── Full API reference
Benefits:
  • Reduces initial context load
  • Users get relevant detail only when needed
  • Keeps main file scannable
SKILL.md（优先加载）
    │
    ├── 快速概述（始终可见）
    ├── 常见操作
    └── 详细内容链接
            │
            └── PROVIDER.md（按需加载）
                    │
                    └── 完整API参考
优势：
  • 减少初始上下文加载量
  • 用户仅在需要时获取相关细节
  • 主文件保持简洁易读

Phase 3: Implementation

第三阶段：实现

3.1 YAML Frontmatter

3.1 YAML前置元数据

yaml
---
name: package-name
description: Brief description with trigger words in English (中文觸發詞). Maximum 1024 characters.
---
Name Rules:
  • Lowercase letters, numbers, hyphens only
  • Maximum 64 characters
  • Should match directory name
Description Best Practices:
  • Include both English and Chinese trigger words
  • Format: 
    English term (中文)
    for key concepts
  • Cover primary use cases
  • Include provider names if applicable
yaml
---
name: package-name
description: 包含中英文触发词的简短描述，最多1024字符。
---
命名规则：
  • 仅使用小写字母、数字和连字符
  • 最多64字符
  • 需与目录名称匹配
描述最佳实践：
  • 同时包含英文和中文触发词
  • 格式：
    英文术语 (中文)
    用于关键概念
  • 覆盖主要使用场景
  • 如有需要，包含提供商名称

3.2 Description Template

3.2 描述模板

{What it does} ({中文說明}). Use when {use case 1}, {use case 2 (中文)}.
Covers {topic 1} ({中文}), {topic 2} ({中文}).
Example:
Taiwan e-invoice integration (台灣電子發票整合). Use when working with
ECPay (綠界), EZPay (藍新). Covers issuing invoices (開立發票),
voiding (作廢), allowances (折讓).
{功能说明} ({中文說明})。适用于{使用场景1}、{使用场景2 (中文)}时使用。
涵盖{主题1} ({中文})、{主题2} ({中文})。
示例：
台湾电子发票整合（台灣電子發票整合）。适用于对接ECPay (綠界)、EZPay (藍新)时使用。
涵盖发票开立（開立發票）、作废（作廢）、折让（折讓）等操作。

3.3 Markdown Structure

3.3 Markdown结构

Overview Section:
markdown
undefined
概述章节：
markdown
undefined

Package Name

套件名称

Brief description of the package family.
套件家族的简要介绍。

Overview

概述

PackageProviderDescription
@rytass/pkg-adapter-a
Provider A (中文名)Brief desc
@rytass/pkg-adapter-b
Provider B (中文名)Brief desc

**Installation Section:**
```markdown
套件提供商描述
@rytass/pkg-adapter-a
Provider A (中文名)简要说明
@rytass/pkg-adapter-b
Provider B (中文名)简要说明

**安装章节：**
```markdown

Installation

安装

```bash npm install @rytass/package-name ```

**Quick Start Section:**
```markdown
bash
npm install @rytass/package-name

**快速开始章节：**
```markdown

Quick Start

快速开始

Provider A

Provider A

```typescript import { ProviderAGateway } from '@rytass/pkg-adapter-a';
const gateway = new ProviderAGateway({ // configuration });
// Basic operation const result = await gateway.operation({ // parameters }); ```

**Method Documentation:**
```markdown
typescript
import { ProviderAGateway } from '@rytass/pkg-adapter-a';

const gateway = new ProviderAGateway({
  // 配置项
});

// 基础操作
const result = await gateway.operation({
  // 参数
});

**方法文档：**
```markdown

methodName(options: OptionsType): Promise<ReturnType>

methodName(options: OptionsType): Promise<ReturnType>

Brief description.
Parameters:
OptionTypeRequiredDescription
param1
string
YesDescription
param2
number
NoDescription (default: value)
Returns: 
Promise<ReturnType>
Example:
```typescript const result = await gateway.methodName({ param1: 'value', }); ```

---
简要说明。
参数：
选项类型必填描述
param1
string
是描述
param2
number
否描述（默认值：value）
返回值： 
Promise<ReturnType>
示例：
typescript
const result = await gateway.methodName({
  param1: 'value',
});

---

Phase 4: Refinement

第四阶段：优化

4.1 Bilingual Trigger Words

4.1 双语触发词

Add Chinese keywords for Taiwan users:
English中文
invoice發票、電子發票
issue開立
void作廢
allowance折讓
payment付款、支付
storage儲存、存儲
添加面向台湾用户的中文关键词：
英文中文
invoice發票、電子發票
issue開立
void作廢
allowance折讓
payment付款、支付
storage儲存、存儲

4.2 Feature Comparison Tables

4.2 功能对比表格

Always include a comparison table for multi-provider skills:
markdown
| Feature | Provider A | Provider B | Provider C |
|---------|:----------:|:----------:|:----------:|
| Feature 1 | Yes | Yes | No |
| Feature 2 | Yes | No | Yes |
Use 
:-----:
for centered alignment with checkmarks.
多提供商技能必须包含对比表格：
markdown
| 功能 | Provider A | Provider B | Provider C |
|---------|:----------:|:----------:|:----------:|
| 功能1 | 是 | 是 | 否 |
| 功能2 | 是 | 否 | 是 |
使用
:-----:
实现居中对齐，可配合勾选标记使用。

4.3 Complete Examples

4.3 完整示例

Every reference file should end with a complete, runnable example:
markdown
undefined
每个参考文件末尾应包含完整可运行示例：
markdown
undefined

Complete Example

完整示例

```typescript import { Gateway, Type1, Type2 } from '@rytass/package';
async function main() { // 1. Initialize const gateway = new Gateway({ /* config */ });
// 2. Create const entity = await gateway.create({ /* options */ });
// 3. Query const found = await gateway.query({ /* options */ });
// 4. Update/Modify const updated = await gateway.modify(entity, { /* options */ });
// 5. Delete/Void await gateway.delete(entity); }
main().catch(console.error); ```

---
typescript
import { Gateway, Type1, Type2 } from '@rytass/package';

async function main() {
  // 1. 初始化
  const gateway = new Gateway({ /* 配置 */ });

  // 2. 创建
  const entity = await gateway.create({ /* 选项 */ });

  // 3. 查询
  const found = await gateway.query({ /* 选项 */ });

  // 4. 更新/修改
  const updated = await gateway.modify(entity, { /* 选项 */ });

  // 5. 删除/作废
  await gateway.delete(entity);
}

main().catch(console.error);

---

Checklist

检查清单

Before finalizing a skill:
  • YAML frontmatter starts on line 1 (no blank lines before)
  • name
    is lowercase with hyphens only
  • description
    includes Chinese trigger words
  • description
    is under 1024 characters
  • SKILL.md is under 500 lines
  • All public methods documented
  • All types and enums documented
  • Installation instructions included
  • Quick start examples work
  • Feature comparison table included (if multi-provider)
  • Complete example at end of each reference file
  • Links to reference files use relative paths
技能最终定稿前需确认：
  • YAML前置元数据从第1行开始（前面无空行）
  • name
    仅使用小写字母和连字符
  • description
    包含中文触发词
  • description
    长度不超过1024字符
  • SKILL.md 内容不超过500行
  • 所有公共方法已文档化
  • 所有类型和枚举已文档化
  • 包含安装说明
  • 快速开始示例可正常运行
  • 多提供商技能包含功能对比表格
  • 每个参考文件末尾有完整示例
  • 参考文件链接使用相对路径

Example: Invoice Skills Structure

示例：发票技能结构

Reference implementation from 
invoice-adapters
and 
invoice-development
:
.claude/skills/
├── invoice-adapters/           # User-facing skill
│   ├── SKILL.md               # Overview, quick start, comparison
│   ├── ECPAY.md               # ECPay full reference
│   ├── EZPAY.md               # EZPay full reference
│   ├── BANK-PRO.md            # BankPro full reference
│   └── AMEGO.md               # Amego full reference
│
└── invoice-development/        # Developer-facing skill
    ├── SKILL.md               # Base package overview
    ├── BASE-INTERFACES.md     # Interface specifications
    └── CREATE-ADAPTER.md      # How to create new adapter
Key decisions made:
  1. Split into user vs developer skills
  2. One reference file per provider
  3. Progressive disclosure for detailed API
  4. Chinese keywords in description for Taiwan users
参考
invoice-adapters
和
invoice-development
的实现：
.claude/skills/
├── invoice-adapters/           # 面向用户的技能
│   ├── SKILL.md               # 概述、快速开始、对比
│   ├── ECPAY.md               # ECPay完整参考
│   ├── EZPAY.md               # EZPay完整参考
│   ├── BANK-PRO.md            # BankPro完整参考
│   └── AMEGO.md               # Amego完整参考
│
└── invoice-development/        # 面向开发者的技能
    ├── SKILL.md               # 基础套件概述
    ├── BASE-INTERFACES.md     # 接口规范
    └── CREATE-ADAPTER.md      # 如何创建新适配器
关键决策：
  1. 拆分为面向用户和开发者的两类技能
  2. 每个提供商对应一个参考文件
  3. 采用渐进式披露展示详细API
  4. 描述中添加面向台湾用户的中文关键词