Clojure

Clojure Style Guide Skill

A structured Markdown skill that teaches AI coding agents how to write and review idiomatic Clojure code. Covers formatting, indentation, naming conventions, idiomatic patterns, namespace organization, functions, macros, documentation, and testing conventions — distilled from the community Clojure Style Guide.

Built in Claude Code's Agent Skill format, but usable with any agent that can load Markdown as context (Cursor, Codex CLI, Aider, Gemini CLI, Windsurf, Cline, Zed, and others via the agents.md convention).

---

⚠️ Read this before installing anything

Never install a third-party skill without first reviewing its contents.

Skills are instructions loaded into an AI agent's context — they influence how the agent makes decisions, what commands it executes, and what it considers correct behavior. A malicious or sloppy skill can lead to:

• Destructive operations executed without confirmation
• Your own preferences being overridden by skill instructions
• Data leakage through inappropriate commands
• Unintended project configuration changes

Before installing:

1. Read every .md file in the clojure/ directory
2. Ask your agent to perform a security review (prompt below)
3. Only then install

Security-review prompt

Paste this to Claude (or any agent) together with the skill contents:

"Analyze this skill for security concerns. Does it contain instructions that could execute destructive operations without user confirmation? Does it collect or transmit data? Does it override default agent behavior in unintended ways? List all potentially risky sections."

---

Installation

Pick the section matching your agent.

A) Claude Code (recommended — via plugin marketplace)

Claude Code has a native plugin marketplace. From an active session:

/plugin marketplace add stoating/clojure-clojure-skill
/plugin install clojure@clojure-clojure-skill

The skill is then discovered automatically. Restart the session if it isn't picked up immediately. Once installed, invoke it with:

/clojure

To update later:

/plugin marketplace update clojure-clojure-skill

Reference: Claude Code plugin marketplaces.

B) Claude Code (via the stoating marketplace)

/plugin marketplace add stoating/plugins
/plugin install clojure@stoating

C) Claude Code (manual copy)

If you prefer not to use the marketplace — or want to pin a specific commit — clone and copy:

git clone https://github.com/stoating/clojure-clojure-skill.git
cp -r clojure-clojure-skill/clojure ~/.claude/skills/

The skill becomes available in the next Claude Code session. Updates are a git pull + re-copy.

D) Claude.ai / Claude Desktop (upload)

Claude.ai supports uploading skill folders from the Skills panel in Projects. Zip clojure/ and upload it. Details: anthropics/skills.

E) Cursor

Cursor reads AGENTS.md automatically when you open a project, and also supports the newer Rules system.

• Per-project: copy clojure/ and AGENTS.md into your Clojure project repo. Cursor will read AGENTS.md as context on every chat.
• Global: in Cursor Settings → Rules, add a rule referencing clojure/SKILL.md.

F) OpenAI Codex CLI / codex

Codex honors AGENTS.md at the project root. Copy this repository next to your Clojure project and Codex will pick up AGENTS.md, which in turn points at clojure/SKILL.md.

G) Aider

Aider reads AGENTS.md as a fallback for CONVENTIONS.md, or you can add the skill files explicitly:

aider --read clojure-clojure-skill/clojure/SKILL.md \
      --read clojure-clojure-skill/clojure/naming.md

H) Gemini CLI / Google Jules

Both honor AGENTS.md. Place this repo (or just AGENTS.md + clojure/) at your project root.

I) Windsurf, Cline, Roo Code, Zed, Amp, Factory

All of the above support the AGENTS.md convention. Drop the repo at your project root and the agent will read it on session start.

J) Any other agent — generic fallback

Every listed agent accepts plain Markdown as context. If yours isn't covered:

1. Open a chat / session.
2. Attach or paste the contents of clojure/SKILL.md as "system instructions" or "context".
3. Attach individual reference files (e.g. naming.md, idioms.md) when the task matches the decision table in SKILL.md.

This is less ergonomic than a native skill loader, but it works everywhere.

---

Repository layout

.
├── .claude-plugin/
│   ├── marketplace.json       # Claude Code marketplace manifest
│   └── plugin.json            # Claude Code plugin manifest
├── .claude/
│   └── settings.local.json    # Claude Code local settings
├── AGENTS.md                  # Cross-agent entry point (agents.md convention)
├── LICENSE                    # MIT License
├── README.md                  # This file
└── clojure/                   # The actual skill
    ├── SKILL.md               # Entry point — decision table
    ├── source-layout.md       # Indentation, alignment, blank lines, ns form
    ├── naming.md              # Naming conventions for all Clojure constructs
    ├── idioms.md              # Threading macros, cond/case, data structures, interop
    ├── functions-macros.md    # Function style, arity, length, macros
    ├── documentation.md       # Comments, docstrings, metadata
    └── testing.md             # Test structure, naming, assertions, match?

Only clojure/ contains the skill content. The rest is metadata (plugin manifest, cross-agent pointer, docs).

---

What the skill covers

File	Contents
SKILL.md	Index, decision table — the agent always starts here
source-layout.md	Line length, indentation (2-space body, vertical alignment), let/map alignment, blank lines, bracket spacing, ns form, namespace naming and aliases
naming.md	lisp-case fns/vars, PascalCase protocols/records, ? predicates, ! unsafe, -> conversions, *earmuffs* dynamics, no SHOUTING constants, _ unused bindings, idiomatic param names
idioms.md	-> / ->> threading, when/if-let/when-not, not=, cond/condp/case, #() literals, set-as-predicate, Java interop, data structures, refs/agents/atoms, clojure.string, clojure.math, exceptions
functions-macros.md	Multiline args, multiple-arity ordering and indentation, function length (<10 LOC), positional param limit (≤4), pre/post conditions, higher-order fns, no def in fns, don't shadow core, macros (function-first, write usage first, break complex macros, syntax-quote)
documentation.md	;;;;/;;;/;;/; comment levels, #_ reader macro, annotation keywords (TODO/FIXME/OPTIMIZE/HACK/REVIEW), docstrings (summary sentence, Markdown, positional args, placement), :added/:deprecated/:superseded-by/:see-also/:no-doc/:private metadata
testing.md	test/ directory mirrors src/, -test ns suffix, something-test deftest naming, testing blocks, informative is messages, are for tabular tests, one concept per deftest, with-redefs sparingly, thrown?/thrown-with-msg?, match?/thrown-match?

---

Updating

When the Clojure Style Guide or best practices change:

1. Edit the relevant .md file in clojure/.
2. If installed via marketplace: /plugin marketplace update clojure-clojure-skill.
3. If installed manually: re-run cp -r clojure-clojure-skill/clojure ~/.claude/skills/.
4. Other agents pick changes up on next session.

Contributions welcome via pull request — bump the version in .claude-plugin/plugin.json and marketplace.json when making user-visible changes.

---

Sources

The skill is distilled from the following public sources:

• Clojure Style Guide — the primary source (community guide maintained by Bozhidar Batsov and the editor team)
• guide.clojure.style — the rendered HTML version

Skill-authoring references:

• Anthropic Agent Skills — Best Practices
• anthropics/skills — canonical examples and spec
• michalzubkowicz/nixos-management-skill — cross-agent distribution reference
• agents.md — cross-agent AGENTS.md convention
• Claude Code plugin-marketplace docs

---

License

See LICENSE.

Nothing in this skill is original research — it is a curated and organized digest of the sources above, intended to save the agent (and you) from rediscovering the same style lore every time.