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
npx skills add alamenai/terrae --skill new -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/new/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/new/
1Skills CLI (Vercel)
npx skills add alamenai/terrae --skill new -a codex2Manually: put the files in place
.agents/skills/new/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add alamenai/terrae --skill new -a cursor2Manually: put the files in place
.cursor/skills/new/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install alamenai/terrae .claude/skills/new2Manually: put the files in place
.github/skills/new/SKILL.md1Skills CLI (Vercel)
npx skills add alamenai/terrae --skill new -a gemini-cli2Platform CLI
gemini skills install https://github.com/alamenai/terrae --path .claude/skills/newManually: put the files in place
.devin/skills/new/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add alamenai/terrae --skill new -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.