Agent skill

create-theme

Guide for creating new themes from preset template. CRITICAL: Includes MANDATORY dependency management rules for NPM distribution.

View SKILL.md on GitHub Repository

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/create-theme

SKILL.md

Create Theme Skill

Complete guide for scaffolding and configuring new themes from the preset template.

⚠️ MANDATORY: Dependency Management Rules

Principio Fundamental

Si @nextsparkjs/core tiene una dependencia, los themes DEBEN declararla como peerDependency, NUNCA como dependency.

Template OBLIGATORIO de package.json para Themes

json

{
  "name": "@nextsparkjs/theme-NOMBRE",
  "version": "1.0.0",
  "private": false,
  "main": "./config/theme.config.ts",
  "dependencies": {
    // Plugins que el theme requiere
    "@nextsparkjs/plugin-langchain": "workspace:*"
  },
  "peerDependencies": {
    "@nextsparkjs/core": "workspace:*",
    "next": "^15.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "zod": "^4.0.0"
    // Agregar otras de core que el theme use directamente
  }
}

Import Rules

Package	Can Import From
Theme	Core (peer), plugins (dep/peer), itself (never other themes)

Prerequisites

Command: pnpm create:theme <theme-name>
Preset Location: core/templates/contents/themes/starter/
Output Location: themes/<theme-name>/

Step 1: Gather Requirements

Before creating ANY theme, collect:

markdown

Required Information:
1. Theme name (lowercase, hyphenated slug)
2. Display name (human-readable)
3. Description (purpose of the theme)
4. Author (team or individual)
5. Primary use case (SaaS type, industry, features)
6. Color preferences (optional - can use defaults)

Step 2: Create Theme from Preset

Basic Usage

bash

pnpm create:theme <theme-name>

With Options

bash

pnpm create:theme <theme-name> \
  --description "Theme description" \
  --author "Author Name" \
  --display-name "Display Name"

Example

bash

pnpm create:theme project-manager \
  --description "Project management SaaS application" \
  --author "Development Team" \
  --display-name "Project Manager"

Step 3: Theme Structure Created

contents/themes/<theme-name>/
├── config/
│   ├── theme.config.ts         # Visual configuration
│   ├── app.config.ts           # Application overrides
│   ├── dashboard.config.ts     # Dashboard settings
│   └── permissions.config.ts   # Permission overrides
├── about.md                    # Theme description
├── styles/
│   ├── globals.css             # CSS variables
│   └── components.css          # Component overrides
├── messages/
│   ├── en.json                 # English translations
│   └── es.json                 # Spanish translations
├── migrations/
│   ├── README.md               # Migration docs
│   └── 001_example_schema.sql
├── docs/01-overview/
│   ├── 01-introduction.md
│   └── 02-customization.md
├── blocks/hero/                # Example hero block
├── entities/                   # Data entities (optional)
│   └── [entity]/               # Each entity has 4 required files
│       ├── [entity].config.ts
│       ├── [entity].fields.ts
│       ├── [entity].types.ts
│       ├── [entity].service.ts
│       └── messages/
├── templates/                  # Page overrides
├── public/brand/               # Brand assets
└── tests/                      # Theme tests

Step 4: Customize Configuration

4.1 theme.config.ts - Visual Identity

typescript

colors: {
  light: {
    // Blue for corporate/professional
    primary: 'oklch(0.55 0.2 250)',
    // Green for productivity/growth
    // primary: 'oklch(0.55 0.2 150)',
    // Orange for creative/energy
    // primary: 'oklch(0.65 0.2 50)',
    // Purple for premium/luxury
    // primary: 'oklch(0.55 0.2 300)',
  }
}

// Enable required plugins
plugins: [
  // 'plugin-analytics',
  // 'plugin-payments',
]

Color Presets by Use Case

Use Case	Color	OKLCH Value
Corporate/Professional	Blue	`oklch(0.55 0.2 250)`
Productivity/Growth	Green	`oklch(0.55 0.2 150)`
Creative/Energy	Orange	`oklch(0.65 0.2 50)`
Premium/Luxury	Purple	`oklch(0.55 0.2 300)`
Healthcare/Trust	Teal	`oklch(0.55 0.15 200)`
Finance/Stability	Navy	`oklch(0.45 0.15 260)`
E-commerce/Action	Red	`oklch(0.55 0.2 25)`

4.2 app.config.ts - Application Behavior

typescript

// Multi-tenant SaaS
teams: {
  allowCreation: true,
  maxTeamsPerUser: 5,
}

// Single-tenant Application
teams: {
  allowCreation: false,
  maxTeamsPerUser: 1,
}

// Features
features: {
  enableDocs: true,   // Documentation site
  enableBlog: false,  // Blog functionality
}

4.3 dashboard.config.ts - Admin Interface

typescript

topbar: {
  showSearch: true,
  showNotifications: true,
  showMessages: false,
}

sidebar: {
  defaultCollapsed: false,
  showEntityCounts: true,
}

entities: {
  defaultPageSize: 25,
  enableBulkActions: true,
}

Step 5: Verify Theme Setup

bash

# 1. Verify theme structure
ls -la contents/themes/<theme-name>/

# 2. Build registry to include new theme
node core/scripts/build/registry.mjs

# 3. Verify theme appears in registry
grep "<theme-name>" core/lib/registries/theme-registry.ts

# 4. Test theme activation (optional)
# Update .env.local: NEXT_PUBLIC_ACTIVE_THEME='<theme-name>'
# Run: pnpm dev

Step 6: Entity Structure (4-File Pattern)

Each theme entity requires 4 files:

File	Purpose
`[entity].config.ts`	Entity configuration
`[entity].fields.ts`	Field definitions
`[entity].types.ts`	TypeScript types
`[entity].service.ts`	Data access service

Reference: core/templates/contents/themes/starter/entities/tasks/

Verification Checklist

Antes de crear un theme (OBLIGATORIO):

Verificar si las dependencias que necesito ya están en core
Si están en core → declararlas como peerDependencies
Si NO están en core → declararlas como dependencies
Plugins como dependencies (workspace:*)
NUNCA duplicar: zod, react, next, @tanstack/*, lucide-react, etc.
NUNCA importar de otros themes

Después de crear el theme:

Theme name follows naming conventions (lowercase, hyphenated)
All preset files created successfully
package.json created with correct peerDependencies
theme.config.ts customized with appropriate colors
app.config.ts configured for use case
dashboard.config.ts settings appropriate
permissions.config.ts reviewed
messages/ translations have correct theme name
Registry rebuilt: node core/scripts/build/registry.mjs
Theme appears in THEME_REGISTRY
No TypeScript errors

Validación de Dependencias:

bash

# Verificar que no hay duplicados
pnpm ls zod
# Debe mostrar UNA sola versión

Anti-Patterns

Pattern	Why It's Wrong	Correct Approach
Manual file creation	Missing files, wrong structure	Use `pnpm create:theme`
Skipping registry rebuild	Theme won't be recognized	Always run `node core/scripts/build/registry.mjs`
Modifying core files	Architecture violation	Only work in `contents/themes/`
Implementing features	Scope creep	Hand off to backend/frontend agents

Handoff Template

After creating theme, document:

markdown

## Theme Created: <theme-name>

### Completed Setup:
- Theme scaffolded from preset
- Visual identity configured (primary color: X)
- Application settings configured
- Dashboard layout configured

### Ready for Development:
- Backend: Add custom entities, migrations, API endpoints
- Frontend: Customize UI components, add blocks

### Environment Setup:
NEXT_PUBLIC_ACTIVE_THEME='<theme-name>'

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31

Explore

majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31

Explore

majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31

Explore

majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31

Explore

majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

Didn't find tool you were looking for?

Search AI Tools

create-theme

Install this agent skill to your Project

SKILL.md

Create Theme Skill

⚠️ MANDATORY: Dependency Management Rules

Principio Fundamental

Template OBLIGATORIO de package.json para Themes

Import Rules

Prerequisites

Step 1: Gather Requirements

Step 2: Create Theme from Preset

Basic Usage

With Options

Example

Step 3: Theme Structure Created

Step 4: Customize Configuration

4.1 theme.config.ts - Visual Identity

Color Presets by Use Case

4.2 app.config.ts - Application Behavior

4.3 dashboard.config.ts - Admin Interface

Step 5: Verify Theme Setup

Step 6: Entity Structure (4-File Pattern)

Verification Checklist

Antes de crear un theme (OBLIGATORIO):

Después de crear el theme:

Validación de Dependencias:

Anti-Patterns

Handoff Template

Related Documentation

Recommended Agent Skills

agent-ops-spec

agent-ops-state

agent-ops-spec

agent-ops-testing

agent-ops-testing

agent-ops-state