DEV Community: AlexTDev

How I Automated Mermaid.js Upgrades with a Claude Code Skill

AlexTDev — Sun, 05 Apr 2026 17:11:08 +0000

I maintain an open-source IntelliJ plugin that bundles Mermaid.js. Every time Mermaid releases a new version, I need to update around ten files across a Kotlin codebase — lexer grammars, completion data, test fixtures, documentation. I know the process by heart, but knowing it doesn't make it less tedious. It's the same careful, detail-heavy work each time, and the kind where a single missed file means a debugging session you didn't plan for, or new features you silently skip without realizing.

The Plugin

Mermaid Visualizer is a JetBrains IDE plugin that adds full Mermaid.js support: rendering inside Markdown preview, a standalone editor with live preview for .mmd and .mermaid files, syntax highlighting, code completion, inspections, navigation, and structure view. It crossed 2,000 downloads in about six weeks on the JetBrains Marketplace, which was a nice surprise for a solo project.

The integration runs deep. The plugin bundles mermaid.min.js (~2.9 MB) and renders diagrams via JCEF (Chromium embedded in the IDE). But it also has a JFlex lexer that knows every diagram type and keyword, a Grammar-Kit parser with PSI tree, contextual code completion that suggests the right arrows and keywords depending on which diagram you're writing, and inspections that catch mistakes. All of that means when Mermaid.js adds a new diagram type or changes syntax, the upgrade isn't just swapping a JavaScript file — it's updating the lexer, the completion catalogs, the test data, the documentation, and then verifying everything still works.

GitHub repo if you want to look at the code.

The Problem

The first time I upgraded Mermaid.js, I did everything by hand. Read the changelog, figured out what was new, opened each file, made the edits, ran the tests, fixed what broke, ran them again. It took about three hours, and I still missed some new features from the release. I only noticed later when I went back to the changelog and realized I'd skipped a couple of new keywords.

The second time, I used Claude to help. I walked it through the process step by step — "now open this file, add these entries here, now regenerate the lexer, now update the tests." It was faster and more thorough, but I was essentially being the orchestrator. I had to remember the sequence, remember which files to touch, remember that longer arrow patterns need to come before shorter ones in the JFlex grammar or longest-match breaks. Every piece of domain knowledge was in my head, and I had to give it to Claude sequentially.

The core tension: the process is identical every time, but it demands attention to detail across many files with non-obvious ordering constraints. Miss one file and you get broken tests. Forget to regenerate the lexer after editing the grammar and you get a build that compiles fine but silently ignores your changes. It's the kind of work that's just tedious enough to be error-prone.

Why a Skill, Not a Prompt

Claude Code has a concept called skills — markdown files that live in your project and encode a reusable procedure. You invoke them with a slash command, and Claude follows the instructions. They're different from prompts in ways that matter for this kind of problem.

A prompt is one-shot. You write it, use it, and if you need it again next month, you rewrite it — or dig through your conversation history hoping you saved it. A skill lives in the project repository, versioned alongside the code. When the project structure changes, you update the skill. It evolves with the codebase.

More importantly, a skill encodes domain knowledge that would otherwise exist only in your head. The exact file paths. The line ranges where diagram types are defined in the lexer. The fact that the JFlex KEYWORDS HashSet lives around lines 17-66 and new entries need a comment naming the diagram type. The ordering constraint on arrow patterns. None of that is obvious from reading the code cold — you'd have to explore, grep, build a mental model. The skill front-loads all of that.

Skills also support conditional logic. A Mermaid.js release might add three new diagram types, or it might be just bug fixes. The skill adapts: if there are no new types, keywords, or arrows, it skips the lexer, completion data, and parser phases entirely and jumps straight to updating the bundled file and version references. A static prompt can't do that — or rather, it can suggest it, but it won't enforce it structurally.

The critical insight is simple: skills are for recurring problems. If you do something once, a prompt is fine. If you'll do it again in four weeks, and again four weeks after that, encode it. A skill is a reproducible process you can invoke instantly. That's the core difference.

Anatomy of the Skill

The skill has 11 phases, from changelog analysis through to a manual testing checklist. That might sound like overkill for "update a JavaScript file," but remember — this isn't just a file swap. It's a coordinated change across a lexer grammar, completion catalogs, test data, documentation, and a build pipeline.

The structure is: analyze what changed, download the new version, update each affected layer of the codebase in dependency order, run the build, report results.

Here's what makes it work.

The Impact Classification

Phase 0 starts with reading the changelog and classifying every change:

| Category | Impact | Examples |
|---|---|---|
| New diagram types | HIGH — touches ~10 files | venn-beta, ishikawa-beta |
| New keywords for existing types | MEDIUM — touches ~4 files | set, union for venn |
| New arrow patterns | MEDIUM — touches ~4 files | half-arrowheads |
| Breaking changes | HIGH — varies | renamed types, removed syntax, API changes |
| Internal changes only | LOW — version refs only | perf improvements, bug fixes |

This is the decision engine. A bug-fix-only release skips most phases — download the new file, update version strings, build, done. A release with new diagram types triggers the full pipeline. The skill doesn't waste time on phases that don't apply, and it doesn't skip phases that do.

Precision in File Locations

Phase 2 handles the JFlex lexer, and this is where precision matters:

## Phase 2 — JFlex Lexer (IF new types/keywords/arrows)
File: src/main/grammars/Mermaid.flex
### 2a. Diagram types (YYINITIAL state, ~lines 100-130)
Add new diagram type strings to the alternation block. Keep grouped logically.
### 2b. Keywords (KEYWORDS HashSet, ~lines 17-66)
Add new keywords grouped under a comment naming the diagram type.
Only reserved words, NOT arbitrary identifiers.
### 2c. Arrow patterns (NORMAL state, ~lines 160-218)
Longer patterns MUST come BEFORE shorter ones (JFlex longest-match).
Variable-length arrows go before fixed-length.

Without this, Claude would have to search the codebase, figure out the lexer structure, and guess where to insert new entries. It might get it right. It might put a new arrow pattern after shorter ones and break longest-match. The skill eliminates that uncertainty.

The line ranges use "~" because they shift as the file grows. They're landmarks, not GPS coordinates — close enough to orient, flexible enough to survive edits.

The Verification Gate

Phase 10 is short but non-negotiable:

## Phase 10 — Build & Verify
./gradlew build then ./gradlew verifyPlugin.
Both must succeed. If tests fail: read, fix, re-run.

This is what turns the skill from a checklist into a reliable process. It doesn't declare success until the build passes. If a test fails because a new diagram type wasn't added to a test fixture, Claude reads the failure, fixes it, and re-runs. The loop continues until green.

Why It Works

Looking across the whole skill, a few design choices carry the weight:

Explicit file paths and line ranges remove ambiguity. The agent knows where to look without exploring.
Conditional phases with clear triggers handle any type of release without wasted effort.
Ordered dependencies prevent cascading failures — the lexer is regenerated before completion data is updated, the parser before navigation, everything before tests.
Verification gates ensure the process produces a working build, not just a set of edits.
Delegation to existing tooling where it makes sense — ./gradlew updateMermaid handles the download, SHA-256 verification, and atomic file replacement. The skill doesn't reinvent that.

What I Changed Along the Way

The first version of this skill was too vague. It said things like "update the lexer with new diagram types" without specifying where in the lexer or how. Claude made reasonable guesses, but reasonable guesses are wrong often enough to be a problem.

The second version had better structure — numbered phases, file paths — but didn't handle variability well. What if the release has no new diagram types? What about breaking changes that rename existing syntax? It assumed every upgrade was the same shape, which they aren't.

The third version added the conditional branching and the impact classification table. That was the version that started working reliably in one activation — invoke the skill, provide the changelog, let it run.

I also had to refine the Gradle updateMermaid task itself to integrate cleanly. The skill assumes that task handles download and integrity verification, so the task needed to actually be reliable — atomic writes, SHA-256 checks, clear error messages on failure.

The lesson is familiar to anyone who writes code: you iterate. Expect two or three versions before a skill works the way you want. That's normal, not a failure.

Results

Before the skill, a Mermaid.js upgrade took about 3 hours of focused work and I'd still miss things. With the skill, it takes 45 minutes to an hour, including running the full test suite and verifying the build.

More importantly: zero missed features since adopting the skill. The impact classification in Phase 0 forces a thorough changelog review, and the per-phase file lists ensure nothing gets skipped. This matters because staying close to official Mermaid.js releases is the whole point of the plugin — one of the common criticisms of existing Mermaid plugins was lagging months behind upstream. The skill is what makes that goal sustainable as a solo dev, and I'll keep iterating on it to push that time down further.

Takeaways for Writing Your Own Skills

If you're thinking about encoding one of your own processes as a skill, here's what I've learned:

Target recurring processes. If you do something once, write a prompt. If you know you'll do it again, write a skill.

Be explicit about locations. File paths, line ranges, section names. The less the agent has to search, the less it can get wrong.

Use conditional branching. Real processes have variability. "IF new types exist, do X; otherwise skip to Y" handles that without separate skills for each scenario.

Include verification steps. A skill that makes edits but doesn't check if they work is just a fancy TODO list. Build, test, lint — whatever your project needs.

Iterate. Your first version will be too vague or too rigid. That's fine. Refine it after each use, the same way you'd refine code after a code review.

Keep it in the repo. Version the skill alongside the code it operates on. When the code structure changes, the skill should change too.

One Last Thing

If you work in JetBrains IDEs and want Mermaid diagram support, give the plugin a try. But the broader point here isn't about Mermaid or IntelliJ — it's about recognizing when a recurring process is worth encoding.

If you have a procedure that's always the same steps, always touches the same files, and always requires the same domain knowledge you keep in your head, that's a skill waiting to be written. The upfront cost is maybe an hour. The payoff compounds every time you invoke it.

If you found this helpful, you can buy me a coffee ☕.

Agent Client Protocol (ACP): A New Standard for Bringing AI Coding Agents into Your IDE

AlexTDev — Mon, 30 Mar 2026 06:15:00 +0000

Using AI coding agents inside your IDE works but it's rarely as seamless as it should be. Some features of your favorite agent are missing in the plugin of your IDE compared to another (you can see the difference between Claude Code plugin in VSCode and IntelliJ). A new agent gets a lot of buzz, but there's no support for your editor yet. You make it work, but there's always friction somewhere.

On the other side, agent developers face a different headache: they need to integrate into every IDE on the market. IntelliJ, VS Code, Zed, Neovim, and counting. Each one has its own API, its own extension format, its own quirks. And every time they ship an update, every plugin needs to follow — which it often doesn't or with a different experience.

This is the exact same problem the software industry solved once before, with the Language Server Protocol. And the same solution is now emerging for AI agents: the Agent Client Protocol (ACP).

This article covers what ACP is, how it works under the hood, how it relates to MCP, and how you can use it today.

The problem ACP solves

Before LSP, every editor needed custom plugins for every programming language — autocompletion, go-to-definition, linting. It was an N×M integration problem. LSP turned it into N+M: language servers implement one protocol, editors support one protocol, everything just works.

AI agents face the same N×M challenge. Every new agent needs a custom integration for every editor it wants to support. Every editor needs a custom integration for every agent it wants to offer. With 30+ agents and a dozen editors, that's hundreds of individual integrations — each one fragile, each one lagging behind the agent's latest release.

ACP collapses this the same way LSP did. Agents implement one protocol. Editors adopt one protocol. A new agent immediately works in every compatible editor. A new editor immediately supports every compatible agent. No custom work, no vendor lock-in.

Who's behind it

ACP was created by Zed Industries (the team behind the Zed editor) and launched in August 2025 with Google's Gemini CLI as the first reference implementation. In October 2025, JetBrains announced they would co-develop the protocol and bring ACP support to their entire IDE lineup. In January 2026, they jointly launched the ACP Agent Registry — a curated directory of agents installable in one click from any compatible editor.

The protocol is open source under the Apache 2.0 license, hosted at agentclientprotocol.com.

The ecosystem has grown fast. Over 30 agents have adopted ACP, including Claude Code, Codex CLI, Gemini CLI, Cursor (which joined the registry in March 2026), Cline, Junie, GitHub Copilot, Kiro CLI, Kimi CLI, OpenCode, Augment Code, and more. On the editor side, Zed has native support, JetBrains IDEs support it from 2025.3 with full registry integration in 2026.1, and community plugins exist for VS Code, Neovim and Obsidian.

How ACP works under the hood

The technical design is deliberately simple. ACP uses JSON-RPC 2.0 over stdio — when you activate an agent, your editor spawns it as a subprocess and communicates through stdin/stdout pipes. No network configuration, no ports, no complex setup.

The conversation follows a predictable sequence:

1. Initialize — The editor sends an initialize request declaring its capabilities (filesystem access, terminal, etc.). The agent responds with its own capabilities (image support, session loading, etc.).

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {
      "fs": { "readTextFile": true, "writeTextFile": true },
      "terminal": true
    },
    "clientInfo": { "name": "intellij-idea", "version": "2026.1" }
  }
}

2. New session — The editor creates a session, passing the working directory and available MCP servers.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/new",
  "params": {
    "cwd": "/home/user/my-project",
    "mcpServers": []
  }
}

3. Prompt — The user sends a message. The agent streams back responses in real-time via JSON-RPC notifications — the editor can display progress token by token.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/prompt",
  "params": {
    "sessionId": "sess_abc123",
    "content": [{ "type": "text", "text": "Refactor this controller" }]
  }
}

The communication is bidirectional: the editor sends prompts to the agent, but the agent can also request things back — reading a file, writing a file, running a terminal command. The editor mediates all access, keeping the user in control of what the agent can do.

ACP reuses data types from MCP wherever possible, so structures like text content, diffs, and tool results follow established JSON schemas. Human-readable text defaults to Markdown.

ACP vs MCP: complementary, not competing

This is the question everyone asks. The short answer: MCP connects agents to tools. ACP connects agents to editors. They operate at different layers of the stack and are designed to work together.

MCP (Model Context Protocol) standardizes how agents access external tools and data sources — databases, APIs, file systems, web search. It answers the question: what can the agent access?

ACP (Agent Client Protocol) standardizes how agents integrate into development environments — editors, IDEs, notebooks. It answers the question: where does the agent live in your workflow?

In practice, they compose naturally. When an ACP session starts, the editor can pass its configured MCP servers to the agent. The agent then uses MCP to access tools while communicating with the editor through ACP:

Editor ←— ACP (JSON-RPC/stdio) —→ Agent ←— MCP (JSON-RPC) —→ Tools & Data

A concrete example: you're in IntelliJ with Gemini CLI connected via ACP. You ask it to analyze your database schema. Gemini uses MCP to query a connected PostgreSQL server, gets the schema, and sends the analysis back to IntelliJ through ACP — rendered inline in the AI chat panel. With IntelliJ 2026.1, agents can even access your IDE's configured data sources natively, making this kind of workflow seamless.

Don't confuse with IBM's ACP. There's a separate protocol also called ACP — the Agent Communication Protocol — created by IBM's BeeAI team for agent-to-agent communication. It has since merged with Google's A2A protocol under the Linux Foundation. It's a completely different thing solving a different problem (agents talking to each other, not agents talking to editors).

Using ACP in JetBrains IDEs

ACP support landed in JetBrains IDEs with version 2025.3 and matured significantly with 2026.1, which brought the built-in ACP Registry, one-click agent installation, and expanded agent capabilities like database access and Git worktree support. It works across the entire lineup — IntelliJ IDEA, PyCharm, WebStorm, GoLand, and the rest. No JetBrains AI subscription is required.

From the ACP Registry (recommended)

This is the easiest path and the one JetBrains is pushing forward:

Open the AI Chat tool window
Click the chat mode selector and choose Install From ACP Registry (or go to Settings | Tools | AI Assistant | Agents)
Browse the available agents — Cursor, Claude Agent, Codex, Gemini CLI, Kimi CLI, Augment Code, and many more
Click Install — the IDE downloads everything needed, including runtimes if required
Select the agent from the dropdown in AI Chat and start prompting

That's it. The agent runs as a local subprocess. The registry handles updates automatically.

On the Agents settings page, you can also configure MCP exposure:

Pass custom MCP servers — exposes your configured MCP servers to installed agents
Pass IntelliJ MCP server — gives agents access to the IDE's built-in MCP server (project structure, open files, data sources)

Manual configuration

For agents not in the registry or custom setups, you can still edit ~/.jetbrains/acp.json directly:

{
  "default_mcp_settings": {
    "use_idea_mcp": true,
    "use_custom_mcp": true
  },
  "agent_servers": {
    "Gemini CLI": {
      "command": "/path/to/gemini",
      "args": ["--experimental-acp"],
      "env": {}
    }
  }
}

Restart your IDE, and the agent appears in the AI Chat selector.

What's new in 2026.1 specifically

The 2026.1 release made ACP a first-class citizen in JetBrains IDEs. Beyond the registry, a few features stand out:

Database access for agents — Codex, Claude Agent, and other ACP agents can query and modify your IDE's configured data sources natively.
Git worktrees — Work in parallel branches and hand one off to an agent while you keep coding in another. A natural fit for agent-driven workflows.
Cursor in the registry — Cursor joined the ACP Registry in March 2026, bringing its agentic workflows directly into JetBrains IDEs.

Using ACP in Zed

Zed has native ACP support and is where the protocol was born. The quickest way to get started: open the agent panel (Cmd+? / Ctrl+?), hit the + button, and pick an agent — Gemini CLI, Claude Agent, and Codex are available out of the box.

For additional agents, use the ACP Registry (zed: acp registry in the command palette) or add them manually in your settings:

{
  "agent_servers": {
    "My Custom Agent": {
      "type": "custom",
      "command": "/path/to/agent",
      "args": ["acp"]
    }
  }
}

What this changes in practice

The practical impact is bigger than it might seem at first:

For developers, you're no longer choosing between "the IDE I love" and "the agent I want." Use PyCharm with Claude Code. Use IntelliJ with Cursor. Use Zed with Codex. Switch agents for different tasks without switching editors.

For agent developers, you implement ACP once and reach users across Zed, JetBrains, Neovim, VS Code, and every future client that adopts the protocol. No more maintaining editor-specific plugins that break with every release.

For the ecosystem, it creates healthy competition. Agents compete on intelligence and capability, not on which editors they happen to support. Editors compete on UX and developer experience, not on which agents they've managed to integrate.

Getting started

Make sure your IDE supports ACP (JetBrains 2026.1+, Zed, or a community plugin for VS Code/Neovim)
Open the ACP Registry from your IDE and install an agent in one click
Or install manually from the agents list and configure acp.json
Open the AI Chat panel and start using it

The full protocol specification and SDK are at agentclientprotocol.com. The JetBrains documentation covers IDE-specific setup in detail.

ACP is still young — launched mid-2025, with JetBrains joining in October and the registry going live in January 2026. But with 30+ agents, Cursor on board, and the two biggest IDE ecosystems backing it, the trajectory is clear. This is the LSP moment for AI agents.

If you found this helpful, you can buy me a coffee ☕.

How to Write Effective Agent Skills for Claude

AlexTDev — Sat, 21 Mar 2026 22:27:16 +0000

If you use Claude Code or claude.ai, you've probably caught yourself giving the same instructions over and over. "Use conventional commits." "Run the linter before committing." "Check for breaking changes." Every new conversation, you start from scratch.

Agent Skills fix this. You package your instructions, conventions, and scripts into a reusable module that Claude picks up automatically.

What are Agent Skills?

Skills are directories containing a SKILL.md file with instructions, optional reference files, and optional scripts. Think of them as onboarding docs for Claude — reusable and automatically triggered when your request matches.

Anthropic ships pre-built Skills (PowerPoint, Excel, Word, PDF). The real power is custom Skills: your expertise, your conventions, your patterns.

Where they work:

Claude Code — drop into .claude/skills/ (project) or ~/.claude/skills/ (global). Auto-discovered.
claude.ai — upload as zip via Settings > Features (Pro/Max/Team/Enterprise).

Skills don't sync across surfaces — manage them separately.

How the loading works

Skills use progressive disclosure — they load in three stages, not all at once:

Metadata (always loaded) — Claude sees only name and description from YAML frontmatter. ~100 tokens per Skill.
Instructions (when triggered) — Claude reads SKILL.md when your request matches. Instructions enter the context window.
Resources (as needed) — Additional files and scripts are loaded only when referenced. Scripts are executed via bash — their code never enters context, only the output.

This matters because every token in your Skill competes with conversation history. Understanding this mechanism is key to writing efficient Skills.

The practices that matter most

Nail the description

The description determines whether Claude picks up your Skill at all. Write in third person, be specific, include trigger words:

# Good — Claude knows exactly when to use this
description: >
  Reviews code changes, generates commit messages, and validates
  diffs before committing. Use when the user asks to review code,
  prepare a commit, write a commit message, or open a pull request.

# Bad — too vague to match reliably
description: Helps with git stuff.

Constraints: name is lowercase + hyphens only (max 64 chars), description max 1024 chars, no XML tags in either.

Write for Claude, not for humans

Claude already knows what commits and pull requests are. Don't explain basics — focus on your specific conventions. If you wouldn't explain it to a senior dev joining your team, don't explain it to Claude.

Structure for progressive disclosure

Keep SKILL.md under 500 lines. Split detailed content into separate files referenced from the main file:

## Commit messages
Short version: `type(scope): description`
For detailed rules and examples, see [COMMIT_CONVENTIONS.md](COMMIT_CONVENTIONS.md)

Claude loads COMMIT_CONVENTIONS.md only when dealing with commits. Keep references one level deep — nested chains (A → B → C) get partially read.

Use scripts for deterministic tasks

Anything that should run the same way every time belongs in a script. They're more reliable than generated code, and more token-efficient since only the output enters context:

Run `bash scripts/check_diff.sh` to get a diff summary.

Build feedback loops

For quality-critical tasks, add validation:

1. Run `bash scripts/check_diff.sh`
2. If warnings found, fix them
3. Run again — only proceed when clean

Control the thinking effort

You can set how much reasoning Claude puts into your Skill via the effort field in the frontmatter:

---
name: reviewing-code
description: Reviews code changes and generates commit messages.
effort: max
---

Values: low, medium, high, max. Use max (opus only) for very complex tasks only because it consumes a lot of tokens. Use low for straightforward, mechanical operations like formatting or file renaming. This directly controls Claude's thinking depth when executing the Skill.

Delegate to a subagent

For complex Skills, you can have Claude spawn a subagent to handle the Skill in isolation. This keeps the main conversation's context clean and lets the Skill run with its own dedicated context window.

Configure it in the frontmatter:

---
name: reviewing-code
description: Reviews code changes and generates commit messages.
effort: high
model: claude-sonnet-4-6
allowed-tools: Read, Bash, Grep
---

When model and allowed-tools are specified, Claude delegates the task to a subagent running that model with only those tools. The main conversation receives the result without carrying the Skill's full execution context.

Anti-patterns to avoid

Time-sensitive info — "Before August 2025, use the old API" will rot. Use "current" and "legacy" sections.
Too many options — Pick a default tool/library, mention one alternative for edge cases.
Assuming packages exist — List install commands explicitly.
Deep reference chains — Keep everything one link from SKILL.md.

Complete example: a code review Skill

Here's a full Skill applying all the above practices.

Structure

code-review/
├── SKILL.md
├── COMMIT_CONVENTIONS.md
└── scripts/
    └── check_diff.sh

SKILL.md

---
name: reviewing-code
description: >
  Reviews code changes, generates commit messages, and validates
  diffs before committing. Use when the user asks to review code,
  prepare a commit, write a commit message, check a diff, or
  open a pull request.
effort: high
---

Below the frontmatter, the markdown body:

# Code Review Assistant

## Review process

1. Run `bash scripts/check_diff.sh` to get an overview
2. Analyze changes by category: breaking changes, new features,
   bug fixes, refactoring
3. For each file, check: unrelated changes mixed in? Error handling?
   Edge cases? Docs on public methods?

## Commit messages

Conventional Commits: `type(scope): description`
Types: feat, fix, refactor, docs, test, chore, ci.

For detailed rules, see [COMMIT_CONVENTIONS.md](COMMIT_CONVENTIONS.md).

## PR preparation

1. Run `bash scripts/check_diff.sh` and fix any issues
2. One logical change per commit
3. PR description explains the "why", not the "what"

COMMIT_CONVENTIONS.md

Loaded only when Claude needs to write or review commit messages:

# Commit Message Conventions

## Format

  type(scope): short description

  [optional body]
  [optional footer]

## Types

- feat: New user-visible feature
- fix: User-visible bug fix
- refactor: No behavior change
- docs: Documentation only
- test: Adding/updating tests
- chore: Build, tooling, dependencies
- ci: CI/CD changes

## Example

  feat(auth): add JWT token refresh endpoint

  Tokens auto-refresh 5 minutes before expiry.
  Closes #142

scripts/check_diff.sh

Executed by Claude — only the output enters context:

#!/bin/bash
echo "=== Staged changes summary ==="
git diff --cached --stat 2>/dev/null || git diff --stat

echo ""
echo "=== Looking for common issues ==="
if git diff --cached -G "(console\.log|debugger|print\()" --name-only 2>/dev/null | grep -q .; then
    echo "WARNING: Debug statements found in:"
    git diff --cached -G "(console\.log|debugger|print\()" --name-only
fi

git diff --cached --stat 2>/dev/null | awk '$3 > 500 {print "WARNING: Large change - " $0}'
echo "=== Done ==="

Getting started

Create a directory with a SKILL.md
Add YAML frontmatter (name, description, optionally effort)
Write concise instructions in the body
Drop into .claude/skills/ or upload as zip on claude.ai

Start with a real problem you face repeatedly. A focused Skill that does one thing well beats a sprawling one every time.

The official documentation covers the full spec, and the best practices guide goes deeper on advanced patterns.

If you found this helpful, you can buy me a coffee ☕.

I Built an Open-Source Mermaid Plugin for IntelliJ — Here's Why and What I Learned

AlexTDev — Mon, 16 Mar 2026 22:03:38 +0000

If you use Mermaid diagrams in JetBrains IDEs, you've probably noticed the official plugin hasn't kept up. Architecture diagrams, kanban boards, treemaps — a good chunk of the newer diagram types either render poorly or not at all.

I ran into this problem in my own workflow. I use Mermaid a lot for technical documentation, and I had some of my diagrams broken in the Markdown preview. So instead of waiting for a fix that wasn't coming, I built my own plugin.

Six weeks later, Mermaid Visualizer is on the JetBrains Marketplace at v1.4.0, open-source under Apache 2.0.

Why build yet another plugin?

I was looking for a concrete project to learn the IntelliJ plugin ecosystem from scratch. I had never built a plugin before, never touched JCEF, never published anything on the JetBrains Marketplace. Rather than building a throwaway exercise, I picked a real problem I was facing every day.

The existing landscape looked like this:

The official JetBrains Mermaid plugin — closed-source, not fully functional with the new diagrams
Mermaid Studio — active and feature-rich, but commercial and proprietary

There was a clear gap for an open-source, permissively licensed plugin running the latest version of Mermaid.js. That's the niche I went for.

What does it do?

Mermaid Visualizer embeds Mermaid.js v11.13.0 directly inside the IDE. No CDN, no external dependencies — everything works offline.

Markdown preview integration

Write a mermaid block in any Markdown file and it renders as a diagram in the built-in preview. All 24+ diagram types are supported: flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, architecture diagrams, kanban, mindmaps, and everything else Mermaid supports.

Dedicated editor for `.mmd` / `.mermaid` files

A split editor with live preview. You type on the left, the diagram updates on the right. Scroll sync keeps both sides aligned.

Export

Hover over any diagram (in the Markdown preview or the standalone editor) and an overlay toolbar appears. Copy as SVG, copy as PNG, or save to file.

Zoom and pan

Ctrl + Scroll to zoom, click and drag to pan, fit-to-window, 1:1 view. Works the same in both contexts.

Syntax highlighting

Keywords, diagram types, arrows, strings, comments, directives — all highlighted with configurable colors via the standard IntelliJ color scheme settings.

Settings

Under Settings > Tools > Mermaid: theme (auto/default/dark/forest/neutral), look (classic or hand-drawn), font family, max text size, debounce delay. Changes apply live without reloading.

Dark mode

Detected automatically. Switch your IDE theme and the diagrams follow.

How it works under the hood

The core idea is simple: let Mermaid.js do the rendering, inside the IDE's embedded Chromium browser (JCEF).

The plugin bundles mermaid.min.js (about 2.9 MB) and loads it into a JCEF browser instance via loadHTML(). When you edit your diagram, the Kotlin side encodes the Mermaid source in base64, sends it to the browser through executeJavaScript(), and Mermaid.js renders it to SVG. Communication back to Kotlin (for export, errors, scroll sync) goes through JBCefJSQuery callbacks.

Each rendered diagram lives inside a Shadow DOM to isolate its styles from the rest of the page. This matters especially in the Markdown preview where Mermaid's CSS could otherwise leak into your document.

For the Markdown integration specifically, the plugin hooks into the Markdown plugin's MarkdownBrowserPreviewExtension to inject its scripts and styles into the existing preview browser. It doesn't create a separate browser — it enhances the one that's already there.

The settings propagation has two different paths depending on the context. In the standalone editor, config changes trigger a re-render via an application-level message bus topic. In the Markdown preview, the new config is pushed through the Markdown plugin's BrowserPipe and JavaScript picks it up without a page reload.

What I learned

This was my first plugin, my first time publishing on the JetBrains Marketplace, and my first real encounter with several technologies. Here's what stood out.

JCEF is powerful but has sharp edges

The browser must be created on the EDT. loadHTML() is async, so you can't call executeJavaScript() right after — you need CefLoadHandler.onLoadEnd() to know when the page is ready. Resources loaded via file:// hit CORS restrictions, so inlining everything into loadHTML() turned out to be the most reliable approach. And onLoadEnd runs on CEF's IO thread, not the EDT, so you need to dispatch back for any shared state access.

The Markdown plugin's API requires some caution

The plugin integrates with the Markdown preview through browserPreviewExtensionProvider — the official extension point exposed by the Markdown plugin. This lets me inject scripts and styles into the existing preview browser without creating a separate one.

The approach is clean: the Markdown plugin renders `mermaid blocks as plain <code class="language-mermaid"> elements, and my JavaScript picks them up, feeds them to Mermaid.js, and replaces them with rendered SVG diagrams. No need to override the rendering pipeline itself.

I initially tried CodeFenceGeneratingProvider which seemed like the more direct approach — intercept the code block and generate HTML server-side. But its generateHtml() method is @ApiStatus.Internal and gets flagged by the plugin verifier. The JavaScript-based approach turned out to be both simpler and more robust: it works with IncrementalDOM (live updates as you type), handles theme changes dynamically, and doesn't depend on any internal API.

Shadow DOM saved me a lot of headaches

Mermaid.js generates SVGs with embedded <style> tags. Without isolation, these styles bleed into the Markdown preview and break the layout. Wrapping each diagram in a Shadow DOM solved this cleanly.

Publishing on the Marketplace is straightforward

The IntelliJ Platform Gradle Plugin handles most of the heavy lifting. Set up a PUBLISH_TOKEN, run ./gradlew publishPlugin, and you're live. The review process was quick. I automated releases with GitHub Actions: push a version tag, and CI builds, publishes, and creates a GitHub Release.

Keeping Mermaid.js up to date needs a strategy

The library is nearly 3 MB and gets frequent updates with new diagram types. I wrote a Gradle task (updateMermaid) that pulls the latest version from npm, and a GitHub Actions workflow that checks for updates and opens an issue when a new version is available.

What's next

The plugin covers the essentials — rendering, editing, export, zoom, settings. But there's more I want to build:

Code intelligence — Autocompletion for node names, diagram keywords, arrow types. Inspections for undefined nodes, unused nodes, invalid syntax. This means writing a proper Grammar-Kit parser for the main diagram types.
Navigation — Go-to-definition and Find Usages on node names. A Structure View showing the diagram hierarchy.
Live templates — Snippets for common diagram skeletons (mflow for flowchart, mseq for sequence, etc.).
ZenUML support — It requires a separate module that isn't included in the standard Mermaid bundle.

I don't know how far I'll get, but the roadmap is there and I'm working through it.

Try it out

If Mermaid is part of your workflow in a JetBrains IDE, give it a try:

JetBrains Marketplace: Mermaid Visualizer
GitHub: Alex9583/MermaidVisualizer

It works in any JetBrains IDE based on build 2025.3+ (IntelliJ IDEA, WebStorm, PyCharm, GoLand, etc.). Just install it and your mermaid blocks will start rendering.

It's open-source, it's free, and I'm actively working on it. If something is missing, broken, or could be better — open an issue or drop a comment. Your feedback helps me improve the plugin and learn the platform.

If you want to support the project, you can buy me a coffee ☕.

DEV Community: AlexTDev

How I Automated Mermaid.js Upgrades with a Claude Code Skill

The Plugin

The Problem

Why a Skill, Not a Prompt

Anatomy of the Skill

The Impact Classification

Precision in File Locations

The Verification Gate

Why It Works

What I Changed Along the Way

Results

Takeaways for Writing Your Own Skills

One Last Thing

Agent Client Protocol (ACP): A New Standard for Bringing AI Coding Agents into Your IDE

The problem ACP solves

Who's behind it

How ACP works under the hood

ACP vs MCP: complementary, not competing

Using ACP in JetBrains IDEs

From the ACP Registry (recommended)

Manual configuration

What's new in 2026.1 specifically

Using ACP in Zed

What this changes in practice

Getting started

How to Write Effective Agent Skills for Claude

What are Agent Skills?

How the loading works

The practices that matter most

Nail the description

Write for Claude, not for humans

Structure for progressive disclosure

Use scripts for deterministic tasks

Build feedback loops

Control the thinking effort

Delegate to a subagent

Anti-patterns to avoid

Complete example: a code review Skill

Structure

SKILL.md

COMMIT_CONVENTIONS.md

scripts/check_diff.sh

Getting started

I Built an Open-Source Mermaid Plugin for IntelliJ — Here's Why and What I Learned

Why build yet another plugin?

What does it do?

Markdown preview integration

Dedicated editor for .mmd / .mermaid files

Export

Zoom and pan

Syntax highlighting

Settings

Dark mode

How it works under the hood

What I learned

JCEF is powerful but has sharp edges

The Markdown plugin's API requires some caution

Shadow DOM saved me a lot of headaches

Publishing on the Marketplace is straightforward

Keeping Mermaid.js up to date needs a strategy

What's next

Try it out

Dedicated editor for `.mmd` / `.mermaid` files