Skip to main content
skill CX Codex

new · alamenai — Claude Code skill: what it does, how to install

Automates scaffolding of new Terrae map components, generating source code, registry metadata, documentation, and changelog updates.

MIT 1 installs ★ 252 updated 2026-04-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add alamenai/terrae --skill new -a claude-code
Open on GitHub

What new does

This skill guides developers through creating map components for Terrae. It starts by collecting requirements, including the component category, Lucide icons, compound elements, and control hooks. When multiple implementation strategies exist, such as Mapbox layers versus DOM overlays, it lays out the trade-offs before generating code.

The workflow touches eight distinct outputs across the project. It writes the component source to src/registry/map/, updates barrel exports, registers dependencies in registry.json, builds live demo files, and sets up the documentation page. It also syncs the navigation sidebar, the components listing, and the changelog.

Design conventions, performance rules, and code patterns rely entirely on .claude/rules/react/component.md. Every created component automatically requires the core map dependency https://www.terrae.dev/map.json in its registry entry.

What it helps with

  • scaffold a new map component in src/registry/map/
  • register component metadata and dependencies in registry.json
  • create interactive example files and documentation pages
  • update the docs sidebar, component listing, and changelog

Example prompts for the agent

  • Create a new MapHeatmap component
  • Scaffold MapPolygon with custom styling options
  • Generate MarkerPopup and register it across all project docs

How to install new

1Skills CLI (Vercel)

npx skills add alamenai/terrae --skill new -a claude-code

2Manually: put the files in place

~/.claude/skills/new/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/new/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about new

How to install the new skill in Claude Code?

Run npx skills add alamenai/terrae --skill new -a claude-code. Alternatively, add the configuration file to ~/.claude/skills/new/SKILL.md.

What outputs does this skill produce?

It handles eight outputs: component source, barrel export, registry entry, example files, documentation page, sidebar navigation, component index, and changelog.

What dependencies are required for a new component?

Every entry in registry.json depends on https://www.terrae.dev/map.json, while styling and architectural patterns are pulled from .claude/rules/react/component.md.

Source text

SKILL.md · MIT
---
name: new
description: End-to-end workflow for building a new Terrae component from scratch
argument-hint: [component-name]
---

# Create New Component Skill

End-to-end workflow for building a new Terrae component from scratch.

Covers all 8 outputs:

- Component source
- Registry
- Exports
- Documentation
- Examples
- Sidebar
- Components page
- Changelog

Component structure, patterns, responsiveness, and performance rules are in `.claude/rules/react/component.md`.

## All Outputs

| #   | Output                | File(s)                                                |
| --- | --------------------- | ------------------------------------------------------ |
| 1   | Component source file | `src/registry/map/{name}.tsx`                          |
| 2   | Barrel export         | `src/registry/map/index.tsx` (update)                  |
| 3   | Registry entry        | `registry.json` (update)                               |
| 4   | Example file(s)       | `src/app/docs/_components/examples/{name}-example.tsx` |
| 5   | Documentation page    | `src/app/docs/{slug}/page.tsx`                         |
| 6   | Sidebar navigation    | `src/app/docs/_components/docs-sidebar.tsx` (update)   |
| 7   | Components listing    | `src/app/docs/components/page.tsx` (update)            |
| 8   | Changelog entry       | `src/app/docs/changelog/page.tsx` (update)             |

## Instructions

When the developer requests a new component:

### Step 1: Gather Requirements

Ask for:

- Component name (e.g., `MapHeatmap`, `MapPolygon`)
- Core functionality
- Whether it needs compound components (like `MarkerContent`, `MarkerPopup`)
- Category: `"core"` or `"features"` (most components are features)
- Lucide icon for the sidebar and components page
- Whether it exposes a control hook (e.g., `useHeatmapControl`)

If there are multiple valid implementation approaches (e.g., Mapbox layers vs DOM overlay, canvas vs CSS animations, GeoJSON source vs custom rendering), present the options with trade-offs and let the developer choose before writing code.

### Step 2: Create the Component File and Export

Follow the map component rules in `.claude/rules/react/component.md` for the component structure, template, patterns, and barrel export.

- Location: `src/registry/map/{component-name}.tsx`
- Use kebab-case for file names (e.g., `heat-map.tsx`)
- Export from `src/registry/map/index.tsx`

### Step 3: Add Registry Entry

Update `registry.json` by adding an entry to the `items` array.

Follow this structure:

```json
{
  "name": "heat-map",
  "type": "registry:ui",
  "title": "Map Heatmap",
  "description": "Short description of the component.",
  "dependencies": ["mapbox-gl"],
  "devDependencies": ["@types/mapbox-gl"],
  "registryDependencies": ["https://www.terrae.dev/map.json"],
  "files": [
    {
      "path": "src/registry/map/heat-map.tsx",
      "type": "registry:ui",
      "target": "components/ui/map/heat-map.tsx"
    }
  ]
}
```

##### Key rules:

- `name` uses kebab-case with ``prefix (e.g.,`heat-map`)
- `registryDependencies` always includes `["https://www.terrae.dev/map.json"]` (the core `Map` component that all other components depend on)
- Add extra `dependencies` only if the component needs packages beyond `mapbox-gl`
- Components that don't need `mapbox-gl` directly can have empty `dependencies` (e.g., watermark)

### Step 4: Create Example File(s)

Location: `src/app/docs/_components/examples/{name}-example.tsx`

Use kebab-case for the file name.

The basic example should demonstrate the simplest usage of the component.

```typescript
import { Map, MapHeatmap } from "@/registry/map"

export const HeatmapExample = () => {
  const accessToken = process.env.NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN || ""

  return (
    <div className="h-full w-full">
      <Map accessToken={accessToken} center={[-74.006, 40.7128]} zoom={10}>
        <MapHeatmap id="heatmap-basic" {/* ...minimal props */} />
      </Map>
    </div>
  )
}
```

##### Key rules:

- Only add `"use client"` if the example uses hooks, event handlers, or browser APIs — purely compositional examples that just render map components don't need it
- Import from `@/registry/map`
- Wrap the map in a `<div className="h-full w-full">`
- Pass `process.env.NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN || ""` as the access token — the `Map` component validates it and shows an error if missing, so examples don't need their own check
- Export the component with a descriptive name (PascalCase)
- Create additional example files for each variation (e.g., `heatmap-color-example.tsx`, `heatmap-custom-example.tsx`)

### Step 5: Create Documentation Page

Location: `src/app/docs/{slug}/page.tsx`

Use the `lines-animated/page.tsx` as the gold standard reference.

The slug should match the sidebar href (e.g., `/docs/heatmap` → `src/app/docs/heatmap/page.tsx`).

```typescript
import { DocsLayout, DocsSection, DocsCode, DocsLink } from "../_components/docs"
import { ComponentPreview } from "../_components/component-preview"
import { CodeBlock } from "../_components/code-block"
import { HeatmapExample } from "../_components/examples/heatmap-example"
import { getExampleSource } from "@/lib/get-example-source"
import { Metadata } from "next"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

export const metadata: Metadata = {
  title: "Heatmap",
}

const HeatmapPage = () => {
  const basicSource = getExampleSource("heatmap-example.tsx")

  return (
    <DocsLayout
      title="Heatmap"
      description="Short description of what the component does."
      prev={{ title: "Previous Component", href: "/docs/previous" }}
      next={{ title: "Next Component", href: "/docs/next" }}
    >
      <DocsSection title="Installation">
        <p>First, make sure you have the base map component installed:</p>
        <CodeBlock code={`npx shadcn@latest add https://www.terrae.dev/map.json`} language="bash" />
        <p className="mt-4">Then install the heatmap component:</p>
        <CodeBlock
          code={`npx shadcn@latest add https://www.terrae.dev/heat-map.json`}
          language="bash"
        />
      </DocsSection>

      <ComponentPreview code={basicSource}>
        <HeatmapExample />
      </ComponentPreview>

      {/* Additional sections with examples, props tables, etc. */}
    </DocsLayout>
  )
}

export default HeatmapPage
```

##### Key rules:

- Always export `metadata` with a `title`
- Use `DocsLayout` with `title`, `description`, `prev`, and `next` navigation links
- First section is always "Installation" with two `CodeBlock`s (base map + component)
- The basic `ComponentPreview` goes directly after Installation (no section title or description, just the demo)
- Use `ComponentPreview` to wrap each example with its source code
- Use `getExampleSource("filename.tsx")` to load example source code
- Use `DocsCode` for inline code references in descriptions
- Use `DocsSection` with a `title` for each section
- Add a props `Table` when the component has many configurable props
- Set `prev`/`next` to match adjacent items in the sidebar navigation

### Step 6: Add to Sidebar

Update `src/app/docs/_components/docs-sidebar.tsx`:

1. Import the Lucide icon at the top (if not already imported)
2. Add a `NavItem` entry in the correct section of the `navigation` array
3. Add `badge: "new"`

```typescript
{ title: "Heatmap", href: "/docs/heatmap", icon: Flame, badge: "new" },
```

Sections:

- `"Explore"` — Story, Changelog
- `"Get Started"` — Introduction, Installation, Comparison, Components, Hooks, Reference
- `"Core"` — Map, Controls, Compass, Marker, Popup
- `"Features"` — Everything else

### Step 7: Add to Components Page

Update `src/app/docs/components/page.tsx`:

1. Import the Lucide icon at the top (if not already imported)
2. Add a `ComponentItem` entry to the `components` array
3. Add `isNew: true`

```typescript
{
  title: "Heatmap",
  href: "/docs/heatmap",
  description: "Short description matching the registry description",
  icon: Flame,
  category: "features",
  installCommand: "npx shadcn@latest add https://www.terrae.dev/heat-map.json",
  isNew: true,
},
```

##### Key rules:

- `category` is `"core"` or `"features"` (must match the sidebar section)
- `installCommand` URL follows the pattern `https://www.terrae.dev/{registry-name}.json`
- Add `mapboxOnly: true` if the component only works with Mapbox GL (not MapLibre)
- Place the entry near similar components in the array

### Step 8: Update Changelog

Update `src/app/docs/changelog/page.tsx`:

Add a new entry to the `components` array of the most recent (topmost) `ChangelogEntry` in the `changelogs` array:

```typescript
{
  title: "Heatmap",
  description: (
    <>
      New <code className="rounded bg-muted px-1 py-0.5 text-xs">MapHeatmap</code> component for
      visualizing data density on the map. Supports customizable color ramps, radius control,
      and intensity adjustment.
    </>
  ),
  href: "/docs/heatmap",
},
```

##### Key rules:

- Add under `components` for new components, `features` for new features, `fixes` for bug fixes, `properties` for new props
- The `description` uses JSX with inline `<code>` tags for component names
- Always include `href` linking to the docs page

### Step 9: Review with User

Before finalizing, show all changes:

- The component source code
- The barrel export addition
- The registry entry
- The example file(s)
- The documentation page
- The sidebar entry
- The components page entry
- The changelog entry

© alamenai · MIT · alamenai/terrae

Similar skills

All skills for Frontend and UI →

new by other authors comes first.

new Railway new is a Claude Code skill that provisions Railway projects, services, and repositories. It activates whenever you ask to initialize infrastructure or deploy an app. CX Codex +1 51installs mapbox-web-integration-patterns mapbox mapbox-web-integration-patterns — a skill for Claude Code, Codex, Cursor and other agents carrying official Mapbox GL JS integration patterns for React, Vue, Svelte and Angular. Covers map lifecycle, token handling, and Search JS setup. CX Codex +1 2,700installs pick-ui-library emilkowalski pick-ui-library is a Claude Code skill that selects a frontend library from a curated catalog for interface tasks. CX Codex +1 239,400installs remotion-maps official Remotion remotion-maps guides map animation techniques in Remotion, covering everything from static satellite shots to 3D terrain flythroughs. CX Codex GP ChatGPT +1 3installs 21st-cli-use 21st-dev 21st-cli-use is a Claude Code skill that searches, retrieves, and installs React and shadcn components, themes, and SVG logos from 21st.dev when components.json is present. CX Codex +1 2,600installs react-component-architecture aj-geddes react-component-architecture — a skill that tells your coding agent how to structure React components: function components, hooks, composition and TypeScript. Useful once a shared component library starts growing. CX Codex +1 687installs 21st-dev-builder-v2 trin-zenityx 21st-dev-builder-v2 — a skill that walks the agent through the 21st.dev registry: it finds components, picks the fitting ones and assembles pages and apps in React and Tailwind. CX Codex +1 474installs

Project sponsors

Companies that keep this analytics open