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

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

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:

markdown

# 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

## Installation

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

Quick Start Section:

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

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

markdown

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

markdown

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

skill-authoring

NPX Install

Tags

SKILL.md Content

Package Documentation Skill Authoring Guide

Overview

Phase 1: Exploration

1.1 Identify Package Scope

1.2 Analyze Package Exports

1.3 Understand Usage Patterns

Phase 2: Planning

2.1 Determine Skill Structure

2.2 Content Architecture

2.3 Progressive Disclosure Pattern

Phase 3: Implementation

3.1 YAML Frontmatter

3.2 Description Template

3.3 Markdown Structure

Phase 4: Refinement

4.1 Bilingual Trigger Words

4.2 Feature Comparison Tables

4.3 Complete Examples

Checklist

Example: Invoice Skills Structure