skill-authoring

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:

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

| Package | Provider | Description |
|---------|----------|-------------|
| `@rytass/pkg-adapter-a` | Provider A (中文名) | Brief desc |
| `@rytass/pkg-adapter-b` | Provider B (中文名) | Brief desc |

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

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

English	中文
invoice	發票、電子發票
issue	開立
void	作廢
allowance	折讓
payment	付款、支付
storage	儲存、存儲

4.2 Feature Comparison Tables

Always include a comparison table for multi-provider skills:

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

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

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