Agent skill

gv ships a skill: a SKILL.md and three reference files that teach a coding agent to search, read and update Grepvine indexes with gv. The agent loads it when you mention Grepvine, gv or an index, or ask it to search a large collection of text or code.

Choose the skill or the MCP server.

Both give an agent the same indexes, with your roles. They differ in where the agent runs and what it can do:

	Agent skill	MCP server
Needs	A shell, with `gv` installed and signed in.	An MCP client and an API key.
Works in	Claude Code, Codex and other agents that read skills or run commands.	Claude Desktop, Claude Code, DeepAgents and other MCP clients.
Can do	Everything `gv` can: search, read, upload directories and S3 prefixes, sync repositories, and manage indexes, members and keys.	Seven tools: list, read and create indexes, search, list and read documents, and store up to 256 text documents per call.

Use the skill when the agent works in a terminal next to your files, for example to sync the repository it’s editing. Use the MCP server when there’s no shell, or when you want the agent limited to a fixed set of tools.

Install the skill.

gv skills install

This installs it for Claude Code in ~/.claude/skills/grepvine-cli and for Codex in ~/.agents/skills/grepvine-cli, so every project sees it. Other agents that read ~/.agents/skills pick it up too. To install it somewhere else:

gv skills install --scope project                   # .claude/skills and .agents/skills in the current git repository
gv skills install --agent claude --scope project    # Claude Code only
gv skills install --dir ~/.config/agent/skills      # any other skills directory

A project install can be committed, so everyone who works on the repository gets the skill. Each of them still needs gv installed and signed in. If an agent has the skill at both scopes, gv warns you, because the agent would see two copies.

For an agent with no skills directory, gv skills show prints SKILL.md, and gv skills show references/search.md prints a reference file, so you can add them to the agent’s instructions.

Install it as a Claude Code plugin.

The CLI repository is also a Claude Code plugin marketplace. In a Claude Code session:

/plugin install grepvine-cli --marketplace grepvine-ai/grepvine-cli

The plugin carries the skill from the repository’s default branch rather than from your gv release. Claude Code doesn’t update plugins from third-party marketplaces automatically; run claude plugin update grepvine-cli@grepvine after you upgrade gv.

Keep the skill current.

The skill describes the commands of the gv release that installed it. After you upgrade gv, run gv skills install again. gv skills ls shows each location and its state:

$ gv skills ls
AGENT   SCOPE    STATUS                                                      PATH
claude  user     installed, current (v0.3.0)                                 /Users/you/.claude/skills/grepvine-cli
codex   user     installed, from gv v0.2.0; run gv skills install to update  /Users/you/.agents/skills/grepvine-cli
claude  project  not installed                                               /Users/you/src/monorepo/.claude/skills/grepvine-cli
codex   project  not installed                                               /Users/you/src/monorepo/.agents/skills/grepvine-cli

gv replaces or removes only a copy that it installed and nobody has changed since. For a copy you edited, or a directory of the same name that gv didn’t install, gv skills install and gv skills uninstall stop with an error. Pass --force to replace or remove an edited copy anyway. gv skills uninstall takes the same --agent, --scope and --dir flags as install.

What the skill tells the agent.

You can read the whole skill with gv skills show. It tells the agent to:

Check the setup first. Run gv whoami --json, and ask you to run gv login if it isn’t signed in, since that needs you at a browser. Find the default organization with gv config get organization.
Pick an index by its description. List indexes with gv index ls --json and read an index’s description and git.commit tag before searching it. Describe every index so the agent picks the right one.
Bound every search. Always pass --json and --max-results, start with -F where it can, and treat exit status 1 as “no match”.
Read around a match. Use gv get to read the document, with --range for part of a large one.
Preview a sync. Run gv sync --dry-run --json and show you the deletions before syncing.
Ask before changing access or deleting. Get your confirmation, naming the exact target, before gv delete, any rm, gv org transfer, gv key create, gv member add or gv member set-role, and pass --force only after you’ve confirmed that command.
Keep keys secret. Never print, log, store or commit an API key, and never read the configuration file to find one.

The agent runs gv as you, so its commands have your role in each organization. To limit what it can change, set GREPVINE_API_KEY in the agent’s environment to a key whose user has the reader role.