Package Creation

Package Creation Workflow

Post-creation workflow for new packages in dx-toolkit monorepo. Use these steps after creating a package with the create-package command.

Post-Creation Workflow

After creating a package with the create-package command:

1. Implement Package Logic

• Edit packages/{package-name}/src/main.ts to export your public API
• Add TSDoc comments to all exports for API documentation
• Create feature modules in src/ directory
• Add tests in src/tests/ directory
• Run bun run check from package directory to verify code quality

2. Register Package Documentation

• Add your package's AGENTS.md reference to root CLAUDE.md
• This ensures Claude Code can access package development guidelines
• Format: @packages/{package-name}/AGENTS.md

3. Create Package-Specific Skill (Optional)

When to create a package-specific skill:

• Package introduces framework-specific patterns (e.g., Teams.ai Memory API, Anthropic streaming)
• Package has domain-specific validation/transformation rules unique to its integration
• Patterns are substantial (50+ lines) and will be referenced frequently
• Examples: mcp-patterns, ai-sdk-patterns, teams-ai-patterns

When NOT to create a skill:

• Patterns are universal (belong in code-patterns skill)
• Package has minimal integration patterns (<50 lines)
• Patterns fit better in package AGENTS.md (very package-specific, not reusable)

Skill directory structure:

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

How to create:

1. Create skill directory and SKILL.md with frontmatter:

---
name: {package-name}-patterns
description: {Package} patterns for dx-toolkit - [key patterns summary]
---

# {Package} Patterns

Package-specific patterns for `@youdotcom-oss/{package-name}`. Use these patterns when developing with this package.

---

## Pattern Section 1

[Pattern description with ✅/❌ examples]

**Why this pattern?**
[Explanation]

## Pattern Section 2

[Continue with other patterns]

2. Add pattern sections with clear ✅/❌ code examples
3. Explain "Why this pattern?" for each
4. Reference skill from package AGENTS.md: > **For {package} patterns**, see '.claude/skills/{package-name}-patterns'
5. Add skill to root AGENTS.md skill list (lines 11-18 in Skill-Based Organization section)

Best practices:

• Focus on framework/domain-specific patterns only
• Use clear ✅/❌ code examples with explanations
• Keep under 200 lines (use root skills for universal patterns)
• Test that skill is discoverable and loadable
• Update root AGENTS.md to document the new skill

4. Add Performance Monitoring (Optional)

• Only required for packages that wrap You.com APIs directly
• Add measurements to scripts/performance/measure.ts
• See the performance-testing skill for detailed instructions
• Skip for utility libraries, CLI tools, or packages without API wrappers

5. Test Locally

cd packages/{package-name}
bun test                 # Run tests
bun run check            # Check code quality
bun run build            # Build package (if bundled pattern)

6. Test Publish Workflow

• Test with prerelease before first stable release
• Go to: https://github.com/youdotcom-oss/dx-toolkit/actions/workflows/publish-{package-name}.yml
• Enter version 0.1.0 with next 1 to create 0.1.0-next.1
• Verify workflow succeeds and package appears on npm

7. First Stable Release

• Push package code to main branch
• Trigger publish workflow with version 0.1.0 (no next value)
• Verify package at https://www.npmjs.com/package/{npm-package-name}
• Test installation: bun add {npm-package-name}

Best Practices

1. Test locally first - Ensure package works before publishing
2. Use prerelease - Test publish workflow with next version first
3. Document with TSDoc - Add API docs directly in code, not separate API.md
4. Follow patterns - Use appropriate skills for implementation
5. Check quality - Run bun run check before committing
6. Register docs - Add AGENTS.md to root CLAUDE.md
7. Create skills for substantial patterns - If package introduces 50+ lines of framework-specific patterns, create a skill

Related Skills

• code-patterns - For implementing package logic
• documentation - For writing README and thin AGENTS.md
• performance-testing - For adding performance monitoring
• git-workflow - For commits and releases

Related Resources

• Create package command: .claude/commands/create-package.md
• Root AGENTS.md: Development Workflow section
• Publishing guide: Root AGENTS.md → Publishing