agentleFS
alamenaialamenai/terrae/.claude/skills/new/SKILL.md

new

Skill245 starsChanged 9 months agoMITView on GitHub

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

  • Reads credentials

21 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use upgrade, gate and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • agenticnotetakingSkill

    upgrade

    Apply plugin knowledge base updates to an existing generated system. Consults the Ars Contexta research graph for methodology improvements, proposes skill upgrades with research justification. Never auto-implements. Triggers on "/upgrade", "upgrade skills", "check for improvements", "update methodology".

    Also in 4 projects that use this

  • synaptiaiSkill

    gate

    Create a BDSK review_gate artifact. Defines a checkpoint that controls whether generated output may proceed toward acceptance. Use when defining quality, security, or scope gates for execution plans.

    Also in 3 projects that use this

  • VercelSkill

    setup

    Set up Vercel CLI and project configuration. Use when the user says "set up Vercel", "configure Vercel", "link to Vercel", or "vercel init".

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

26 rules. 0 are common, 6 are distinctive, and 20 are very specific to this project.

  • 0

    Common

    Most of the 21 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 20

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When the developer requests a new component:

    line 39
  2. Distinctive:

    If there are multiple valid implementation approaches (e.g., Mapbox layers vs DOM overlay, canvas vs CSS animations, GeoJSON source vs …

    line 52
  3. Very specific:

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

    line 56
  4. Very specific:

    Use kebab-case for file names (e.g., heat-map.tsx)

    line 59
  5. Very specific:

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

    line 64
  6. Very specific:

    Add extra dependencies only if the component needs packages beyond mapbox-gl

    line 91
  7. Distinctive:

    Use kebab-case for the file name.

    line 98
  8. Very specific:

    Only add "use client" if the example uses hooks, event handlers, or browser APIs — purely compositional examples that just render map …

    line 120
  9. Very specific:

    Create additional example files for each variation (e.g., heatmap-color-example.tsx, heatmap-custom-example.tsx)

    line 125
  10. Very specific:

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

    line 131
  11. Very specific:

    Always export metadata with a title

    line 182
  12. Very specific:

    Use DocsLayout with title, description, prev, and next navigation links

    line 183
  13. Very specific:

    Use ComponentPreview to wrap each example with its source code

    line 186
  14. Very specific:

    Use getExampleSource("filename.tsx") to load example source code

    line 187
  15. Very specific:

    Use DocsCode for inline code references in descriptions

    line 188
  16. Very specific:

    Use DocsSection with a title for each section

    line 189
  17. Very specific:

    Add a props Table when the component has many configurable props

    line 190
  18. Distinctive:

    Import the Lucide icon at the top (if not already imported)

    line 197
  19. Very specific:

    Add a NavItem entry in the correct section of the navigation array

    line 198
  20. Very specific:

    Add a ComponentItem entry to the components array

    line 217
  21. Very specific:

    Add mapboxOnly: true if the component only works with Mapbox GL (not MapLibre)

    line 236
  22. Distinctive:

    Place the entry near similar components in the array

    line 237
  23. Very specific:

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

    line 243
  24. Very specific:

    Add under components for new components, features for new features, fixes for bug fixes, properties for new props

    line 261
  25. Very specific:

    Always include href linking to the docs page

    line 263
  26. Distinctive:

    Before finalizing, show all changes:

    line 267

“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

#OutputFile(s)
1Component source filesrc/registry/map/{name}.tsx
2Barrel exportsrc/registry/map/index.tsx (update)
3Registry entryregistry.json (update)
4Example file(s)src/app/docs/_components/examples/{name}-example.tsx
5Documentation pagesrc/app/docs/{slug}/page.tsx
6Sidebar navigationsrc/app/docs/_components/docs-sidebar.tsx (update)
7Components listingsrc/app/docs/components/page.tsx (update)
8Changelog entrysrc/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:

{
  "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.

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).

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 CodeBlocks (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"
{ 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
{
  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:

{
  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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.