Package Documentation Skill Authoring Guide

This skill documents the methodology for creating Claude Code skills that document @rytass/* packages.

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

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?

1.2 Analyze Package Exports

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

1.3 Understand Usage Patterns

Identify common operations:

• Initialization / configuration

• CRUD operations (create, read, update, delete)

• Validation methods

• Error handling patterns

Phase 2: Planning

2.1 Determine Skill Structure

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

2.2 Content Architecture

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

2.3 Progressive Disclosure Pattern

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

Phase 3: Implementation

3.1 YAML Frontmatter

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

3.2 Description Template

{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 (折讓).

3.3 Markdown Structure

Overview Section:

Package Name

Brief description of the package family.

Overview

Installation Section:

Installation

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

Quick Start Section:

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:

methodName(options: OptionsType): Promise<ReturnType>

Brief description.

Parameters:

Returns: Promise<ReturnType>

Example:

```typescript const result = await gateway.methodName({ param1: 'value', }); ```

Phase 4: Refinement

4.1 Bilingual Trigger Words

Add Chinese keywords for Taiwan users:

English 中文

invoice 發票、電子發票

issue 開立

void 作廢

allowance 折讓

payment 付款、支付

storage 儲存、存儲

4.2 Feature Comparison Tables

Always include a comparison table for multi-provider skills:

Use :-----: for centered alignment with checkmarks.

4.3 Complete Examples

Every reference file should end with a complete, runnable example:

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); ```

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

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