Agent Skill

@earnforge/skill follows the Agent Skill standard. It bundles a SKILL.md file plus 5 reference files that any coding agent (Claude Code, Cursor, Windsurf, Aider, etc.) can read to understand the LI.FI Earn API and use EarnForge correctly.

Installation

The quickest way: installs into whichever agent you use, and works with Claude Code, Cursor, Codex, Gemini CLI and a dozen others:

npx skills add FarseenSh/earnforge

Or as an npm dependency, if you want it pinned in a project:

npm i @earnforge/skill

It is also served over MCP as resources under skill://earnforge/*, so connecting to the MCP server gives an agent the tools and these instructions over one connection. No install at all.

The installed package contains:

@earnforge/skill/
  SKILL.md
  references/
    pitfalls.md
    protocols.md
    chains.md
    examples.md
    strategies.md

What is SKILL.md?

SKILL.md is a structured file that agents read to learn what tools are available and how to use them. It contains:

1. Frontmatter – Machine-readable name and description
2. Commands – Every CLI command with full usage and flags
3. Rules – Critical integration rules the agent must follow
4. References – Links to detailed reference files

Frontmatter

---
name: earnforge
description: >
  Discovers, compares, risk-scores, and builds unsigned deposit and withdrawal
  quotes for DeFi yield vaults across every chain indexed by the LI.FI Earn API.
  Surfaces LI.FI's undocumented verificationStatus signal, which flags roughly
  9% of vaults as suspect. Handles all 24 known API pitfalls by default.
---

---

Commands in SKILL.md

The skill documents the CLI’s full surface: 19 commands, all accepting --json.

Vault Discovery

Command	Description
earnforge list [--asset] [--chain] [--min-tvl] [--strategy]	List vaults with filters
earnforge top --asset <sym> [--chain] [--limit] [--strategy]	Top vaults by APY
earnforge vault <slug>	Single vault, full detail
earnforge compare <slug> <slug>	Side-by-side comparison

Analysis

Command	Description
earnforge risk <slug>	Seven-dimension risk breakdown and flags
earnforge apy-history <address> <chainId>	30-day APY history from DeFiLlama
earnforge suggest --amount <n> [--asset] [--strategy]	Portfolio allocation
earnforge portfolio <wallet>	Current wallet positions

Deposit and Withdraw

Command	Description
earnforge quote --vault <slug> --amount <n> --wallet <addr>	Build a deposit quote
earnforge withdraw --vault <slug> --amount <n> --wallet <addr>	Build a redeem quote
earnforge allowance / earnforge approve	ERC-20 allowance check and approval tx
earnforge simulate --vault <slug> --amount <n> --wallet <addr>	Simulate against the chain head via Composer

Safety and Monitoring

Command	Description
earnforge doctor --vault <slug>	Run 22 checks: 18 pitfall guards plus 4 environment checks
earnforge preflight <slug> <wallet>	Pre-deposit validation
earnforge watch <slug> [--apy-drop] [--tvl-drop]	Monitor APY/TVL changes

Reference Data

Command	Description
earnforge chains	Every chain with an indexed vault
earnforge protocols	Every indexed protocol, with risk tiers
earnforge init <name>	Scaffold a project with EarnForge wired up

---

Rules

SKILL.md defines 12 rules agents must follow. The ones that most often go wrong:

1. Never submit transactions. Only build unsigned quotes; the user signs.

2. Check ERC-20 allowance before depositing, using the quote’s approvalAddress as spender.

3. Check isTransactional before quoting a deposit, and isRedeemable before quoting a withdrawal.

4. Risk thresholds are 8 / 6: >= 8 low, 6–7.9 medium, < 6 high. Always show the score and its flags alongside APY.

5. Never recommend a verification-flagged vault without saying so. LI.FI flags roughly 9% of vaults. A flagged vault can never reach 8, so it can never read as low risk, and suggest excludes them by default.

6. APY is already a percentage (3.84 = 3.84%). Do not multiply by 100. LI.FI’s own spec and quickstart say to, and they are wrong; doing so overstates every yield 100×.

7. Never hardcode a protocol id. A stale one returns 200 with zero results rather than an error, so the failure is silent. Resolve via earnforge protocols.

8. Cross-chain deposits need an explicit --from-token, and are not atomic: a bridge can succeed while the destination deposit fails.

apy.reward is three-valued

Earlier guidance here said to normalise apy.reward to 0. That is wrong and has been corrected in the skill: null means the protocol reported nothing, 0 means it reported no incentives, and collapsing the two destroys the only signal separating organic yield from an emission that ends.

---

Reference Files

references/pitfalls.md

All 23 API pitfalls with descriptions and fixes. Agents reference this when debugging integration issues or understanding why certain guards exist.

references/protocols.md

The 27 protocols with risk tiers. Used by agents to understand protocol maturity when making recommendations.

references/chains.md

All 17 chains with chainId mappings. Agents use this to convert between chain names and numeric IDs.

references/examples.md

8 worked examples showing common workflows:

• Find top USDC yield on Base
• Compare two vaults
• Build a deposit quote
• Get a diversified allocation
• Run doctor checks
• Monitor a vault
• Cross-chain gas optimization
• Portfolio lookup

references/strategies.md

The 4 yield strategy presets with their filter configs, sort behavior, and recommended use cases.

---

Using the Skill

In Claude Code

Place the skill package in your project’s dependencies. Claude Code will automatically discover the SKILL.md and reference files.

In Cursor / Windsurf

Point your agent to the SKILL.md file:

@earnforge/skill/SKILL.md

The agent will read the file and understand all available commands, rules, and references.

In Custom Agents

Read SKILL.md as part of your system prompt or tool documentation:

import { readFileSync } from 'fs';
import { resolve } from 'path';

const skillPath = resolve('node_modules/@earnforge/skill/SKILL.md');
const skill = readFileSync(skillPath, 'utf-8');
// Include `skill` in your agent's context