clojure-skills

name	clojure-skills
description	Clojure/ClojureScript/ClojureDart development skill. Activates when working with .clj, .cljs, .cljc, .cljd, .edn, .bb files. Provides parenthesis repair tools, REPL evaluation via nREPL, and code navigation (diagnostics, references, definition) via clojure-lsp.
compatibility	REPL evaluation and code navigation work with any agent that has shell access. Optional paren-repair hooks require Claude Code.
globs	["**/*.clj","**/*.cljs","**/*.cljc","**/*.cljd","**/*.edn","**/*.bb"]
user-invocable	false
hooks	{"Stop":[{"hooks":[{"type":"command","command":"clj-lsp-client stop 2>/dev/null; true"}]}]}

Clojure Development Skill

Dependency Check

!which bb 2>/dev/null && echo "✓ bb" || echo "✗ bb MISSING — install: brew install borkdude/brew/babashka (https://github.com/babashka/babashka#installation)" !which bbin 2>/dev/null && echo "✓ bbin" || echo "✗ bbin MISSING — install: bb install io.github.babashka/bbin (https://github.com/babashka/bbin)" !which clj-paren-repair-claude-hook 2>/dev/null && echo "✓ clj-tools" || echo "✗ clj-tools MISSING — install: cd ~/.claude/skills/clojure-skills && bb install" !which clojure-lsp 2>/dev/null && echo "✓ clojure-lsp" || echo "✗ clojure-lsp MISSING (optional) — install: brew install clojure-lsp/brew/clojure-lsp-native (https://clojure-lsp.io/installation/)"

If any required dependency (bb, bbin, clj-tools) shows ✗ MISSING:

1. Show the user the exact install command from the line above
2. After install, tools will be available

clojure-lsp is optional — without it, diagnostics/references/definition are unavailable but paren repair and REPL evaluation still work.

Parenthesis Repair

By default, parenthesis repair does not run automatically. Users can opt in via bb install-hooks to register PreToolUse/PostToolUse hooks.

Manual repair (always available)

clj-paren-repair <files...>
clj-paren-repair path/to/file1.clj path/to/file2.clj

IMPORTANT: Do NOT try to manually repair parenthesis/bracket/brace errors yourself. If you encounter unbalanced delimiters, run clj-paren-repair on the file. If the tool doesn't fix it, report to the user that they need to fix the delimiter error manually.

REPL Evaluation

The command clj-nrepl-eval evaluates Clojure code via nREPL.

Discover nREPL servers

clj-nrepl-eval --discover-ports

This scans .nrepl-port file and running JVM/Babashka processes to find nREPL servers.

Evaluate code

IMPORTANT: ALWAYS use heredoc syntax to avoid zsh ! escaping issues. Do NOT use clj-nrepl-eval -p PORT "code" style — it will break on strings containing !.

clj-nrepl-eval -p <port> <<'EOF'
(+ 1 2 3)
EOF

With timeout (milliseconds):

clj-nrepl-eval -p <port> --timeout 5000 <<'EOF'
(Thread/sleep 10000)
EOF

Multi-line code:

clj-nrepl-eval -p <port> <<'EOF'
(require '[my.namespace :as ns] :reload)
(ns/my-function 42)
EOF

Session persistence

The REPL session persists between evaluations — namespaces and state are maintained. Always use :reload when requiring namespaces to pick up code changes:

(require '[my.namespace :as ns] :reload)

Other commands

clj-nrepl-eval --connected-ports    # List active connections
clj-nrepl-eval -p PORT --reset-session  # Reset persistent session

Code Navigation (clojure-lsp)

If clojure-lsp is installed, use clj-lsp-client for code intelligence. The bridge auto-starts per project when you first query with --file.

Project root is auto-detected from the --file path by walking up to find deps.edn, project.clj, bb.edn, or shadow-cljs.edn. This works across multiple projects added via /add-dir.

Diagnostics

clj-lsp-client diagnostics                        # All files (current project)
clj-lsp-client diagnostics --file src/my/ns.clj   # Single file (auto-detects project)

Find references

clj-lsp-client references --file src/my/ns.clj --line 10 --col 5

Go to definition

clj-lsp-client definition --file src/my/ns.clj --line 10 --col 5

Hover information

clj-lsp-client hover --file src/my/ns.clj --line 10 --col 5

Bridge management

clj-lsp-client start                             # Start bridge for CWD project
clj-lsp-client start --project-root /path/to/project  # Start for specific project
clj-lsp-client stop                              # Stop bridge
clj-lsp-client status                            # Check bridge status

The bridge is automatically stopped on Stop via hooks.

Important Notes

• All Clojure variants supported: .clj, .cljs, .cljc, .cljd, .edn, .bb, .lpy
• ClojureDart (.cljd): Reader conditionals with :cljd feature are fully supported
• Parenthesis repair is opt-in: Run bb install-hooks to enable automatic hooks, or use clj-paren-repair manually
• REPL state persists: Each host:port has its own persistent session. Use --reset-session to start fresh
• LSP bridge is per-project: Each project gets its own bridge instance, auto-detected from file paths
• Coordinates: clj-lsp-client uses 1-based line AND column numbers (editor-style Ln:Col). Input --line/--col and the line:col in output are both 1-based.
• Jar definitions: when definition/references point into a dependency jar, the path is shown as /abs/to/foo.jar:inner/ns.clj:LINE:COL
• Always use heredoc for clj-nrepl-eval: <<'EOF' ... EOF — never use quoted argument style