skill-authoring

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