---

name: skill-authoring description: Guide for creating Claude Code skills to document @rytass packages (建立套件文件 skill 指南). Use when creating new package documentation skills, writing SKILL.md files, or designing skill structure.

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:

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

---

Phase 1: Exploration

1.1 Identify Package Scope

Determine which packages to document:

Copypackages/{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:

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

Copy.claude/skills/{package-name}/
└── SKILL.md

Multi-File Skill - For complex packages (recommended for adapters)

Copy.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

Copy.claude/skills/{package}-adapters/     # User-facing
.claude/skills/{package}-development/  # Developer-facing

2.2 Content Architecture

SKILL.md (Main File) - Keep under 500 lines

Reference Files - One per provider/component

2.3 Progressive Disclosure Pattern

CopySKILL.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

Copy---
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

Copy{What it does} ({中文說明}). Use when {use case 1}, {use case 2 (中文)}.
Covers {topic 1} ({中文}), {topic 2} ({中文}).

Example:

CopyTaiwan e-invoice integration (台灣電子發票整合). Use when working with
ECPay (綠界), EZPay (藍新). Covers issuing invoices (開立發票),
voiding (作廢), allowances (折讓).

3.3 Markdown Structure

Overview Section:

Copy# 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:

Copy## Installation

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

Quick Start Section:

Copy## 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:

Copy#### `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',
});
\`\`\`

---

Phase 4: Refinement

4.1 Bilingual Trigger Words

Add Chinese keywords for Taiwan users:

4.2 Feature Comparison Tables

Always include a comparison table for multi-provider skills:

Copy| Feature | Provider A | Provider B | Provider C |
|---------|:----------:|:----------:|:----------:|
| Feature 1 | Yes | Yes | No |
| Feature 2 | Yes | No | Yes |

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

4.3 Complete Examples

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

Copy## 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:

Copy.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