Package Documentation Skill Authoring Guide

Name: skill-authoring
Rating: 76
Author: Rytass

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:

code

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

code

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

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

code

.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

code

.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

code

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

code

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

Example:

code

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:

Example: Invoice Skills Structure

Reference implementation from invoice-adapters and invoice-development:

code

.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