← All writing
March 31, 2026
GIS
ArcGISSDK5.0ClaudeClaude CodeSkillsAIWeb Components
gis

I Taught Claude the SDK 5.0 — Here's the Skill File

The problem

I wrote about SDK 5.0 landing and what it means for developers building with 4.x. But when I sat down to actually build my first 5.0 app with Claude Code, I hit a wall I should have expected.

Claude doesn't know SDK 5.0.

Not really. It knows 4.x cold — AMD require(), new MapView(), view.ui.add(). It's been trained on years of Esri documentation and Stack Overflow answers for version 4. But 5.0 shipped in February 2026, and Claude's training data is thin on it. Ask it to write a map with <arcgis-map> web components and it'll hallucinate attributes, guess at event names, and mix 4.x patterns with 5.0 syntax in ways that don't work.

This is the same problem a top user in the Esri community posted about — he solved it by pasting working 5.0 code into his Claude conversations as context. That works, but it's manual. You have to remember to do it every time.

I wanted something automatic.

What a Claude Code skill is

If you use Claude Code — Anthropic's CLI tool — you can create skill files. A skill is a markdown file that sits in ~/.claude/skills/ on your machine. When Claude detects that your task matches the skill's description, it loads the file automatically and uses that knowledge to generate better code.

Think of it as a domain-specific reference card that Claude reads before it starts working. You don't paste it in. You don't ask for it. It just shows up when relevant.

I have about 70 skills covering everything from ArcGIS popup patterns to deployment workflows. They're the reason Claude can build a working map app for me on the first try instead of the third. The patterns are pre-loaded. The gotchas are documented. The code examples are tested.

What I built

I created an SDK 5.0 skill — arcgis-sdk-5 — that covers everything you need to build 5.0 apps with Claude Code. It's four files, about 1,200 lines total:

SKILL.md (~400 lines) — The core reference. Quick start templates, the $arcgis.import() pattern, event handling, slot positioning, a component quick reference table, renderer patterns, and a migration cheat sheet mapping every common 4.x pattern to its 5.0 equivalent.

references/component-catalog.md (~300 lines) — Every <arcgis-*> web component in 5.0, organized by category. Properties, events, slots, and code examples for the major ones.

references/migration-patterns.md (~250 lines) — Ten detailed before/after code comparisons. AMD to ESM. new MapView() to <arcgis-map>. view.on("click") to addEventListener("arcgisViewClick"). The patterns you'll actually need when converting existing code.

references/ai-assistant.md (~150 lines) — Setup guide for the <arcgis-assistant> component (still in beta). Prerequisites, embeddings generation, the query pipeline, and gotchas.

What it actually does

Here's the difference. Without the skill, if you ask Claude Code to build a map with SDK 5.0:

  • It might use require() instead of $arcgis.import()
  • It might forget type="module" on the script tag
  • It might try view.on("click") instead of addEventListener("arcgisViewClick")
  • It might import a separate CSS file that isn't needed anymore
  • It might self-close <arcgis-map /> which silently fails

With the skill loaded, Claude knows:

  • The CDN script tag needs type="module"
  • $arcgis.import() replaces AMD require()
  • Events use arcgisView-prefixed names on the element
  • Components need explicit closing tags
  • Renderers, FeatureLayer, and popupTemplate are unchanged — don't rewrite them
  • <arcgis-map> needs an explicit CSS height or it's invisible

The skill doesn't make Claude perfect. But it makes it reliably correct on the patterns that matter most.

How to install it

The skill is open source on GitHub. To use it:

  1. Make sure you have Claude Code installed
  2. Clone or download the skill into your skills directory:
# If you don't have a skills directory yet
mkdir -p ~/.claude/skills

# Clone the skill
git clone https://github.com/franzenjb/arcgis-sdk-5-skill.git ~/.claude/skills/arcgis-sdk-5
  1. That's it. Next time you ask Claude Code to build something with ArcGIS, the skill triggers automatically.

You can also just download the files manually and drop them into ~/.claude/skills/arcgis-sdk-5/. The skill is just markdown — no dependencies, no build step, no configuration.

What's next

This is version 1. It covers the core patterns well enough to build real apps, but there are gaps. The component catalog is broad but not deep — detailed APIs for arcgis-map and arcgis-search, but the other 50+ components are listed without full property documentation.

I'm filling those gaps as I build. My next two projects are both SDK 5.0 — a conversion of an existing 4.x demo and a mobile-first field assessment tool. Every bug I hit, every pattern I discover, every gotcha that burns me goes back into the skill.

If you use it and find something wrong or missing, open an issue on the GitHub repo. This is a living document. It gets better every time someone builds with it.

The bigger idea

This is what I mean when I say the SDK was always there. The knowledge exists. The documentation exists. The problem was never capability — it was access.

Claude Code skills are a new kind of access. Not a tutorial you read once and forget. Not a Stack Overflow answer from 2019. A persistent, machine-readable reference that loads exactly when you need it and stays current because you maintain it alongside your code.

If you're building with ArcGIS and Claude, you should be building skills. Start with the patterns you look up most often. Write them down in markdown. Drop them in ~/.claude/skills/. Let Claude read them so you don't have to repeat yourself.

The SDK was always this powerful. Now your AI assistant knows it too.