ValarMindSkills

A library of reusable skills for AI agents. Each skill is a Markdown file with YAML frontmatter that can be invoked as a slash command within Claude Code CLI, Cursor IDE, Codex CLI, Antigravity IDE, or Zed IDE.

Quick install (recommended)

Run the unified installer to set up skills for Claude Code CLI, Codex CLI, Antigravity, Cursor IDE, and Zed IDE. The script is idempotent, so you can re-run it anytime to upgrade.

curl -fsSL https://raw.githubusercontent.com/Bruno-Cunha-Souza/ValarMindSkills/main/install.sh | bash

Token usage

The following table estimates token consumption per skill/context at session start. Values are approximate.

Scenarios

Context impact: 1,060 tokens ≈ 0.11% of a 1M context window or 0.40% of a 262k window.

Available skills

Installation on Claude Code CLI

Plugin install (manual, from source)

Registers the repository as a local Claude Code marketplace and installs valarmindskills@valarmindskills. Brings all 18 skills under the /valarmindskills:<slug> namespace and enables the obsidian-brain hooks (SessionStart detection + UserPromptSubmit toggle, ON by default).

git clone https://github.com/Bruno-Cunha-Souza/ValarMindSkills.git
cd ValarMindSkills
bash scripts/install-plugin-claude.sh

To install in Claude Code CLI, Codex CLI, Antigravity, Cursor IDE, and Zed IDE in one command, use the unified installer:

bash scripts/install-all.sh

To uninstall: claude plugins uninstall valarmindskills@valarmindskills && claude plugins marketplace remove valarmindskills.

Alternative: development load (no install)

# Reads the repo in place. Run /reload-plugins after edits.
claude --plugin-dir /path/to/ValarMindSkills

#### Obsidian Brain (on by default when vault detected)

Token-efficient session-memory for any project whose CLAUDE.md or AGENTS.md references an Obsidian vault. The SessionStart hook auto-detects the vault, writes a flag file at ~/.claude/.obsidian-brain-active, and injects a one-time digest pointing the agent at the brain index. With no vault detected, the hook silently clears the flag and the statusline badge hides — no posture, no noise.

• /valarmindskills:obsidian-brain on (or bare /valarmindskills:obsidian-brain) — re-enable for the current session
• /valarmindskills:obsidian-brain off — disable for the current session
• stop obsidian-brain / desativar obsidian-brain (natural language) — deactivate

Disable persistently via OBSIDIAN_BRAIN_DEFAULT_MODE=off in your environment, or with {"defaultMode": "off"} in ~/.config/obsidian-brain/config.json.

#### Statusline

The plugin ships a composable statusline that combines the obsidian-brain badge with the current context window usage (e.g. 42% 420k/1M, color-coded by threshold):

• [OBSIDIAN-BRAIN] — roxo (cor 99 ≈ #875FFF, próxima do roxo Obsidian), hidden when no vault is detected or the user opted out.

scripts/install-plugin-claude.sh configures it automatically: it adds statusLine to ~/.claude/settings.json (creating the file if needed, backing it up if it already exists). If statusLine is already set to a different command, the installer leaves it untouched and prints both values so you can choose. Set VALARMIND_SKIP_STATUSLINE=1 to opt out, or remove it manually. If the plugin was installed without the script and statusLine is missing, a SessionStart hook hands the agent this snippet so it can offer to set it up:

"statusLine": {
  "type": "command",
  "command": "bash \"/path/to/ValarMindSkills/hooks/statusline/statusline.sh\""
}

The statusline is built from independent segments under hooks/statusline/segments/ — additional segments can be added there without touching the hooks.

Installation on Antigravity IDE

Note: Antigravity does not load symlinks. Skills must be copied as real files.

Install script for Antigravity (recommended)

The repository includes a script that copies the skills to the global Antigravity directory:

git clone https://github.com/Bruno-Cunha-Souza/ValarMindSkills.git
cd ValarMindSkills
bash scripts/install-antigravity.sh

To install in Claude Code CLI, Codex CLI, Antigravity, Cursor IDE, and Zed IDE in one command, use the unified installer:

bash scripts/install-all.sh

After running the script, reload the VS Code window so the autocomplete picks up the new skills:

• Cmd + Shift + P > Reload Window

Re-run bash scripts/install-antigravity.sh (or bash scripts/install-all.sh) whenever you pull new changes or add/edit skills.

Per-project installation (optional)

To limit skills to a specific project, copy them into the project root:

mkdir -p .agent/skills
cp -r ValarMindSkills/skills/* .agent/skills/

Installation on Codex CLI

Plugin install (recommended)

Copies all skills to ~/.agents/skills/, copies the obsidian-brain hook scripts to ~/.codex/hooks/, and injects the corresponding [[hooks.SessionStart]] and [[hooks.UserPromptSubmit]] entries into ~/.codex/config.toml. Also writes a short skills note into ~/.codex/AGENTS.md. Both the config.toml block and the AGENTS.md block are wrapped in # >>> VALARMIND BEGIN/END (or <!-- VALARMIND BEGIN/END -->) markers, so re-running the installer rewrites the managed block in place without duplicating entries.

git clone https://github.com/Bruno-Cunha-Souza/ValarMindSkills.git
cd ValarMindSkills
bash scripts/install-plugin-codex.sh

Overrides:

• CODEX_HOME=/custom/path — config root for hooks, config.toml, AGENTS.md (default ~/.codex)
• CODEX_SKILLS_HOME=/custom/path — skills root (default ~/.agents/skills)

Skills path (changed): Codex discovers skills in $HOME/.agents/skills, in .agents/skills from the CWD up to the repo root, and in /etc/codex/skills — see the docs. ~/.codex/skills is not a discovery path, so earlier ValarMind releases installed into a directory Codex no longer scans. Both Codex installers now target ~/.agents/skills and delete the ValarMind copies left in ~/.codex/skills (skills you added there yourself are untouched). This matters because Codex does not merge same-named skills — "both can appear in skill selectors" — so stale copies would duplicate the catalog.

Skills-only install (lite)

For a setup without hooks or the AGENTS.md note (just the slash-command surface):

bash scripts/install-codex.sh

Restart Codex CLI after either script so the new skills and hooks are picked up.

Installation on Cursor IDE

Plugin install (recommended)

Copies all skills to ~/.cursor/skills/, copies hook scripts to ~/.cursor/hooks/, and merges ValarMind entries into ~/.cursor/hooks.json (sessionStart + beforeSubmitPrompt). Session-start hooks run through hooks/_cursor/wrap-session.sh, which adapts Claude-style plain-text output to Cursor's JSON additional_context format. Re-running the installer removes prior ValarMind hook entries before appending fresh ones (no duplicates).

git clone https://github.com/Bruno-Cunha-Souza/ValarMindSkills.git
cd ValarMindSkills
bash scripts/install-plugin-cursor.sh

Override the target directory with CURSOR_HOME=/custom/path bash scripts/install-plugin-cursor.sh.

Set VALARMIND_SKIP_HOOKS=1 to install skills only (no hooks.json changes).

Skills-only install (lite)

bash scripts/install-cursor.sh

Restart Cursor after either script. Check Settings → Hooks (or the Hooks output channel) if hooks do not load.

#### Modes in Cursor

Skills are invoked with @slug (e.g. @code-review). Obsidian-brain behaves like Codex/Claude: ON when the workspace CLAUDE.md or AGENTS.md references an Obsidian vault path. Override the default with OBSIDIAN_BRAIN_DEFAULT_MODE or ~/.config/obsidian-brain/config.json.

Cursor does not support the Claude Code statusline; obsidian-brain state is stored in a flag file under ~/.cursor/ (~/.cursor/.obsidian-brain-active).

#### Third-party Claude hooks (optional)

If you already use Claude Code hooks in ~/.claude/settings.json, you can enable Settings → Features → Third-party skills to load them in Cursor in parallel. The ValarMind Cursor installer uses native ~/.cursor/hooks.json and does not require this setting.

Installation on Zed IDE

Zed ships native Agent Skills — the same SKILL.md contract this repo already uses — plus Instructions for always-on context. It has no agent lifecycle hooks yet (zed-industries/zed#57943 is still a proposal), so the obsidian-brain hooks are not installed there.

Plugin install (recommended)

Copies all skills to ~/.agents/skills/ and writes a short skills note into ~/.config/zed/AGENTS.md (Zed's personal instructions file), wrapped in <!-- VALARMIND BEGIN/END --> markers so re-runs rewrite the block in place.

git clone https://github.com/Bruno-Cunha-Souza/ValarMindSkills.git
cd ValarMindSkills
bash scripts/install-plugin-zed.sh

Overrides:

• ZED_SKILLS_HOME=/custom/path — skills root (default ~/.agents/skills)
• ZED_CONFIG_HOME=/custom/path — config root (default ~/.config/zed)
• VALARMIND_SKIP_INSTRUCTIONS=1 — skills only, leave AGENTS.md untouched

Skills-only install (lite)

bash scripts/install-zed.sh

Per-project installation (optional)

Zed also reads <worktree>/.agents/skills/ for the open project (trusted worktrees only):

ZED_SKILLS_HOME="$PWD/.agents/skills" bash scripts/install-zed.sh

Safe pruning in a shared skills root

Unlike ~/.cursor/skills, ~/.agents/skills is a shared root: the Codex CLI installers write there too, and so may other agents. The Zed and Codex installers therefore prune from a manifest (~/.agents/skills/.valarmind-manifest) via scripts/_lib/agents-skills.sh: only slugs a previous ValarMind run recorded are removed when a skill is renamed or dropped upstream. Third-party skills in the same directory are never touched.

One consequence worth knowing: installing for Zed also surfaces the same skills in Codex CLI, and vice versa — same directory, one copy, no duplication.

#### Modes in Zed

Skills are invoked with /slug in the Agent Panel message editor (e.g. /code-review), with @skill to browse the catalog, or autonomously by the agent when the task matches a skill description. Manage them under Settings → AI → Skills (zed://settings/agent.skills).

• Obsidian-brain — no auto-detection without hooks; invoke /obsidian-brain when needed.

Because there is no hook layer, OBSIDIAN_BRAIN_DEFAULT_MODE does not apply here. Zed has no custom statusline either, so there is no badge.

Skills hot-reload (no restart). Instructions are read per thread, so open a new thread after install.

Precedence: a project-level instruction file in the open worktree (.rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md — first match wins) overrides the personal ~/.config/zed/AGENTS.md where the two conflict.

#### Tools (MCP)

Zed exposes external tools through MCP servers under the context_servers key in settings.json (docs). This repo ships skills and hooks only — no MCP server — so the installers leave context_servers alone.

#### Full hook parity via ACP (optional)

For the obsidian-brain vault detection that hooks provide, run Claude Code (or Codex) as an external agent inside Zed. External agents run as their own process and keep their own configuration, so the Claude Code plugin — hooks included — applies there:

bash scripts/install-plugin-claude.sh   # or install-plugin-codex.sh

Then pick the agent in the Agent Panel. The native Zed agent keeps using the skills + AGENTS.md install above.

Project structure

.claude-plugin/
  plugin.json               <- plugin manifest (name, hooks)
  marketplace.json          <- local marketplace manifest
hooks/
  obsidian-brain/
    obsidian-brain-activate.js      <- SessionStart hook (on when vault detected)
    obsidian-brain-mode-tracker.js  <- UserPromptSubmit hook
    obsidian-brain-config.js        <- shared helpers
  _cursor/
    wrap-session.sh                 <- Cursor sessionStart JSON adapter
  _lib/
    posture-intent.js               <- natural-language on/off matcher
  statusline/
    statusline.sh                   <- composer (entry registered in settings.json)
    statusline-nudge.js             <- SessionStart hint when statusLine is not configured
    segments/
      obsidian-brain.sh             <- obsidian-brain badge segment (roxo)
      context.sh                    <- context window usage segment
skills/
  <slug>/
    SKILL.md                <- skill definition (YAML frontmatter + Markdown instructions)
scripts/
  install-plugin-claude.sh  <- persistent plugin install for Claude Code CLI
  install-plugin-codex.sh   <- full plugin install for Codex CLI (skills + hooks + AGENTS.md)
  install-codex.sh          <- skills-only install for Codex CLI (no hooks)
  install-plugin-cursor.sh  <- full plugin install for Cursor IDE (skills + hooks.json)
  install-cursor.sh         <- skills-only install for Cursor IDE (no hooks)
  install-antigravity.sh    <- copies skills to Antigravity global directory
  install-plugin-zed.sh     <- full plugin install for Zed IDE (skills + AGENTS.md note)
  install-zed.sh            <- skills-only install for Zed IDE
  install-all.sh            <- runs all plugin installers (Claude + Codex + Antigravity + Cursor + Zed)
  _lib/
    ensure-rust.sh          <- rustup bootstrap + per-skill cargo build
    agents-skills.sh        <- ~/.agents/skills copy + manifest prune + legacy-dir migration
install.sh                  <- curl-bash bootstrap (downloads latest release, runs install-all.sh)

Each directory under skills/ represents a skill. The directory slug is the identifier used as a slash command.

Skill format

Each SKILL.md follows this format:

---
name: skill-name
description: Short description of when the skill should be triggered.
source: ValarMind Skills
---

Followed by Markdown sections:

• Goal — what the skill does
• Inputs — data the agent must collect before executing
• Procedure — step-by-step execution instructions
• Constraints — limits and rules
• Output format — how results should be presented

Contributing

1. Create a directory under skills/ with the new skill's slug
2. Add a SKILL.md file following the format above
3. Write instructions in English
4. Open a pull request

License

MIT