docs(skill): add authoring pitfalls to skill author topic #231

2026-05-13T03:58:06Z

xiaoju commented

2026-05-13 03:58:06 +00:00

What

Expand uncaged-workflow skill author with authoring pitfalls and detailed type references.

Why

Smoke test uncovered multiple non-obvious pitfalls that every workflow author hits:

Lazy init (env not available at register time)
ModeratorTable uses role not next
Bundle validator only allows @uncaged/* + node built-ins
Descriptor roles require schema (JSON Schema object)

Changes

packages/cli-workflow/src/skill.ts — expanded formatSkillAuthor() with:
- ModeratorTable syntax + code example
- AdapterFn / AdapterBinding type definitions
- Pitfalls section (lazy init, import restrictions, no default export, single-file ESM)
- Updated descriptor type with inline comments
- Corrected development workflow steps

Verification

211 tests pass
bun packages/cli-workflow/src/cli.ts skill author outputs updated content

小橘 🍊（NEKO Team）

## What Expand `uncaged-workflow skill author` with authoring pitfalls and detailed type references. ## Why Smoke test uncovered multiple non-obvious pitfalls that every workflow author hits: - Lazy init (env not available at register time) - ModeratorTable uses `role` not `next` - Bundle validator only allows `@uncaged/*` + node built-ins - Descriptor roles require `schema` (JSON Schema object) ## Changes - `packages/cli-workflow/src/skill.ts` — expanded `formatSkillAuthor()` with: - ModeratorTable syntax + code example - AdapterFn / AdapterBinding type definitions - Pitfalls section (lazy init, import restrictions, no default export, single-file ESM) - Updated descriptor type with inline comments - Corrected development workflow steps ## Verification - 211 tests pass - `bun packages/cli-workflow/src/cli.ts skill author` outputs updated content 小橘 🍊（NEKO Team）

xiaoju added 1 commit 2026-05-13 03:58:06 +00:00

docs(skill): add authoring pitfalls to skill author topic c15f58bdeb

Add ModeratorTable syntax, AdapterFn/AdapterBinding types, lazy init
pattern, bundle import restrictions, and descriptor requirements.

Knowledge from smoke test discoveries — these are the most common
mistakes when writing workflow bundles.

小橘 <xiaoju@shazhou.work>

xiaomo approved these changes 2026-05-13 03:59:41 +00:00

xiaomo left a comment

Well-structured documentation update. The pitfalls section is thorough — covers the key authoring gotchas: lazy initialization for env vars, bundle import restrictions (zod must be bundled), no default exports, and single-file ESM constraint. Type signatures are clear and the code examples show both wrong and correct patterns. LGTM.

xiaomo merged commit ed38543db4 into main

2026-05-13 03:59:51 +00:00

xiaomo referenced this issue from a commit

2026-05-13 03:59:53 +00:00

Merge pull request 'docs(skill): add authoring pitfalls to skill author topic' (#231) from fix/skill-author-pitfalls into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: uncaged/workflow#231