feat: add defi-cli agent skill for Claude Code

README.md

@@ -83,6 +83,16 @@ Verify install:
 defi version --long
 ```
 
+## Agent Skill (Claude Code / Cursor / Codex)
+
+If your AI agent uses [Claude Code](https://claude.com/claude-code), [Cursor](https://cursor.com), or another agent that supports [open skills](https://agentskills.io), install the bundled skill to teach the agent how to use defi-cli correctly — including exact field names, execution patterns, and common gotchas:
+
+```bash
+npx skills add ggonzalez94/defi-cli
+```
+
+Or install manually: copy `skills/defi-cli/` from this repo to `~/.claude/skills/defi-cli/`.
+
 ## Signing Backends
 
 Execution commands (`plan`, `submit`, `status`) support two signing backends:

docs/agents/overview.mdx

@@ -3,6 +3,20 @@ title: Agent Overview
 description: Build robust agent workflows on top of deterministic CLI contracts.
 ---
 
+## Install the agent skill
+
+If you use Claude Code, Cursor, Codex, or another AI coding agent that supports [open skills](https://agentskills.io), install the defi-cli skill to give your agent precise knowledge of every command, flag, output field, and gotcha:
+
+```bash
+# Install the CLI
+curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh
+
+# Install the agent skill
+npx skills add ggonzalez94/defi-cli
+```
+
+The skill teaches agents correct field names for `--select` and `jq`, the plan/submit/status execution pattern, OWS wallet usage, and pitfalls like the missing `health_factor` field in position data.
+
 ## Why agents like defi-cli
 
 - Stable envelope schema (`version`, `success`, `error`, `meta`)

docs/installation.mdx

@@ -36,6 +36,16 @@ defi version --long
 defi --help
 ```
 
+## Agent skill (optional)
+
+If you use Claude Code, Cursor, Codex, or another AI agent that supports [open skills](https://agentskills.io), install the bundled skill to teach the agent how to use defi-cli:
+
+```bash
+npx skills add ggonzalez94/defi-cli
+```
+
+See [Agent Overview](/agents/overview) for details.
+
 ## Optional shell completion
 
 ```bash