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:

Explore - Understand the package structure
Plan - Design the skill architecture
Implement - Write the skill files
Refine - Add bilingual triggers and optimize

在创建套件文档相关技能时，请遵循以下结构化方法：

探索 - 理解套件结构
规划 - 设计技能架构
实现 - 编写技能文件
优化 - 添加双语触发词并进行优化

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:

Category	What to Document
Classes	Gateway, Entity, Allowance classes
Interfaces	Core interfaces and their properties
Enums	All enum values with descriptions
Types	Type aliases and union types
Functions	Utility functions with signatures
Constants	Exported 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

Section	Purpose
Overview	What the packages do, unified interface
Installation	npm install commands
Quick Start	Minimal working examples
Feature Comparison	Table comparing providers
Detailed Docs Links	Links to reference files

Reference Files - One per provider/component

Section	Purpose
Constructor	Parameters and initialization
Methods	All public methods with signatures
Classes	Entity and value object classes
Types	Provider-specific type definitions
Complete Example	Full 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

概述

Package	Provider	Description
`@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

```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:

Option	Type	Required	Description
`param1`	`string`	Yes	Description
`param2`	`number`	No	Description (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:

Split into user vs developer skills
One reference file per provider
Progressive disclosure for detailed API
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      # 如何创建新适配器

关键决策：

拆分为面向用户和开发者的两类技能
每个提供商对应一个参考文件
采用渐进式披露展示详细API
描述中添加面向台湾用户的中文关键词