Skip to content

SKILL.md

Latest commit

 

History

History
166 lines (123 loc) · 5.35 KB

SKILL.md

File metadata and controls

166 lines (123 loc) · 5.35 KB
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
  • Line numbers: clj-lsp-client uses 1-based line numbers and 0-based column numbers (matching Emacs conventions)
  • Always use heredoc for clj-nrepl-eval: <<'EOF' ... EOF — never use quoted argument style