ZShip provides a set of development skills that help you perform common development tasks more efficiently. These skills are AI-powered workflows that guide you through complex operations while ensuring compliance with ZShip conventions.

What are Skills?

Skills are specialized AI workflows stored in .cursor/skills/ that provide step-by-step guidance for:

• Creating new apps and services
• Adding features to your dashboard
• Customizing branding
• Reviewing code for compliance
• Syncing with upstream updates
• And more...

When you ask the AI assistant to perform a task, it automatically uses the relevant skill to ensure best practices and convention compliance.

Available Skills

Core Development Skills

onboard

First-time setup guide for ZShip secondary development

• Explains architecture and read-only boundaries
• Security checklist (secrets, API keys)
• Naming rules and conventions
• Multi-tenant isolation requirements

Use when: Starting a new ZShip project or onboarding new developers.

create-app

Create a new brand site by copying from the official web template

• Copies apps/web/ to your new app directory
• Sets up app_key, branding, and configuration
• Configures unique ports and package names

Use when: Starting a new frontend project for a new brand.

create-admin

Create a custom admin console by copying from the official admin template

• Copies apps/admin/ to your custom admin directory
• Sets up admin-specific configuration
• Configures admin routes and permissions

Use when: You need admin functionality with custom modifications.

create-service

Create a new backend service (Cloudflare Worker + Hono + D1)

• Generates complete service structure
• Sets up Hono framework, D1 database, migrations
• Enforces naming conventions (never use nodeXX-* format)
• Includes multi-tenant isolation patterns

Use when: You need custom server-side logic beyond what official nodeX services provide.

Feature Development Skills

add-page

Add a new page to your ZShip app (Astro or Nuxt)

• Creates page component with proper structure
• Sets up API proxy routes if needed
• Integrates i18n support
• Works for both Astro and Nuxt apps

Use when: Adding a new page to your frontend application.

add-dashboard

Add a new feature tab to the user dashboard

• Creates Vue island component
• Sets up Astro page shell
• Adds navigation entry
• Creates API proxy routes

Use when: Adding a new feature/tab to the user-facing dashboard.

add-provider-model

Add a new AI provider model to zship-provider1-service

• Parses provider API documentation
• Generates complete DB seed SQL
• Updates documentation
• Supports KIE, WaveSpeed AI, and custom platforms

Use when: Integrating a new AI provider model into the provider service.

Customization Skills

customize-brand

Customize branding for your ZShip app

• Site name, logo, colors, SEO
• Theme customization
• CSS variable overrides
• Never modifies official templates

Use when: Customizing your app's branding and visual identity.

Maintenance Skills

sync-upstream

Sync your app with official ZShip template updates

• Performs diff analysis between templates and your copy
• Suggests changes to merge
• Preserves your customizations
• Identifies irrelevant changes to skip

Use when: After pulling ZShip updates and need to merge template changes.

review

Review code changes for ZShip convention compliance

• Checks for accidental official file modifications
• Validates naming conventions
• Security checklist (secrets, API keys)
• Multi-tenant isolation verification
• API response format validation
• Architecture boundary checks

Use when: Before committing code or creating pull requests.

How Skills Work

1. Automatic Activation: When you describe a task, the AI assistant automatically identifies and uses the relevant skill.

2. Step-by-Step Guidance: Each skill provides detailed steps, code templates, and examples.

3. Convention Enforcement: Skills ensure your code follows ZShip conventions:

   • Never modify official files (apps/web/, apps/admin/, backend/nodeX-*/)
   • Proper naming conventions
   • Multi-tenant isolation
   • Security best practices

4. Verification Checklists: Most skills include verification steps to ensure everything works correctly.

Skill Structure

Skills are stored as Markdown files in .cursor/skills/{skill-name}/SKILL.md with:

• Frontmatter: Name and description
• Critical Rules: Must-follow conventions
• Step-by-Step Instructions: Detailed guidance
• Code Templates: Ready-to-use code snippets
• Verification: Checklists to confirm completion

Best Practices

1. Always use skills for common tasks instead of doing them manually
2. Read the critical rules in each skill before starting
3. Follow the verification checklist after completing a task
4. Run review skill before committing significant changes
5. Use sync-upstream regularly to stay updated with template improvements

Next Steps

• Codebase Structure — Understand the project structure
• Deployment Guide — Deploy your application
• Customization Guide — Customize your app