api-contracts-and-zod-validation

Worldbuilding App Skills

Claude Code skills for developing and maintaining worldbuilding applications, built using official Anthropic best practices.

About This Project

This repository contains custom Claude Code skills designed specifically for web development work on worldbuilding applications. These skills help automate common tasks, enforce best practices, and streamline development workflows.

Structure

worldbuilding-app-skills/
├── README.md (this file)
├── QUICKSTART.md (quick start guide)
├── CLAUDE.md (guidance for Claude Code)
├── CATALOG.md (inventory of skills)
├── .claude-plugin/
│   └── marketplace.json   - Plugin marketplace manifest
├── plugins/ (plugin format for marketplace)
│   ├── nextjs-fullstack-scaffold/
│   ├── tailwind-shadcn-ui-setup/
│   └── ... (26 total plugins)
├── skills/ (organized by purpose)
│   ├── development/      - Code generation, refactoring, patterns
│   ├── data-modeling/    - Entity schemas, relationships, validation
│   ├── ui-components/    - Component generation, styling
│   ├── documentation/    - API docs, user guides, comments
│   ├── testing/          - Unit tests, integration tests, e2e tests
│   └── utilities/        - Helpers, formatters, tools
├── scripts/ (skill management tools)
│   ├── init_skill.py      - Initialize new skill structure
│   ├── quick_validate.py  - Validate skill structure
│   ├── package_skill.py   - Package for distribution
│   └── migrate_to_plugins.py - Convert skills to plugin format
├── dist/ (packaged skills as .zip files)
└── docs/ (additional documentation)

Quick Start

Create a New Skill

Ask Claude Code:

Create a skill for [what you want to automate]

Claude will follow the official 6-step process:

1. Ask clarifying questions with concrete examples
2. Plan reusable resources (scripts, references, assets)
3. Initialize with proper structure
4. Implement the skill with resources
5. Update the catalog
6. Offer deployment options

Or Use the Init Script

python scripts/init_skill.py my-skill-name --path skills/development

Then edit the generated SKILL.md and supporting files.

Installing Skills

Option 1: Plugin Marketplace (Recommended)

The easiest way to use these skills is through the Claude Code plugin marketplace:

Step 1: Add the marketplace

/plugin marketplace add hopeoverture/worldbuilding-app-skills

Step 2: Install plugins

/plugin install nextjs-fullstack-scaffold@worldbuilding-app-skills
/plugin install tailwind-shadcn-ui-setup@worldbuilding-app-skills
/plugin install form-generator-rhf-zod@worldbuilding-app-skills

Benefits:

• One-command installation and updates
• Easy discovery and version management
• Works across all your projects
• Official distribution method

See docs/plugin-marketplace-guide.md for complete plugin marketplace documentation.

Option 2: Direct Copy

Quick Deploy to Project:

# Copy to your worldbuilding app's .claude/skills directory
cp -r skills/category/skill-name /path/to/worldbuilding-app/.claude/skills/

Deploy to Personal Use (All Projects):

cp -r skills/category/skill-name ~/.claude/skills/

Deploy from Packaged Zip:

# All skills are pre-packaged in dist/
unzip dist/skill-name.zip -d /path/to/project/.claude/skills/

For Complete Deployment Guide: See docs/skill-deployment-guide.md for detailed instructions, troubleshooting, and best practices.

Skill Categories

Development

Code generation, refactoring, architecture patterns, debugging tools for worldbuilding features.

Data Modeling

Entity schemas, relationship definitions, validation rules, data transformation utilities.

UI Components

React component generation, styling patterns, responsive design helpers.

Documentation

API documentation, user guides, inline comments, architecture docs.

Testing

Test generation, coverage analysis, mock data generation, test utilities.

Utilities

General-purpose tools, formatters, converters, development helpers.

Worldbuilding-Specific Use Cases

Skills in this repository might help with:

• Generating entity types (characters, locations, items, factions)
• Creating relationship schemas between entities
• Building timeline and chronology tools
• Managing world attributes and settings
• Generating map data structures
• Creating content templates
• Validating world consistency
• Export/import utilities

Skill Structure

Each skill follows official Anthropic structure:

skill-name/
├── SKILL.md (required - YAML frontmatter + instructions)
└── Bundled Resources (optional)
    ├── scripts/      - Executable Python/Bash code
    ├── references/   - Documentation loaded as needed
    └── assets/       - Templates/files for output

Best Practices