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

npm i @earnforge/skill

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:

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

Frontmatter

---
name: earnforge
description: >
  Discovers, compares, risk-scores, and builds unsigned deposit quotes for
  623+ DeFi yield vaults across 16 chains via the LI.FI Earn API.
  Handles all 18 known API pitfalls by default.
---

Commands in SKILL.md

The skill defines these command groups:

Vault Discovery

Command	Description
`earnforge list [--asset] [--chain] [--min-tvl] [--strategy] [--json]`	List vaults with filters
`earnforge top [--asset] [--chain] [--limit] [--strategy] [--json]`	Top vaults by APY
`earnforge get <slug> [--json]`	Single vault by slug

Comparison and Analysis

Command	Description
`earnforge compare <slug1> <slug2> [--json]`	Side-by-side vault comparison
`earnforge risk <slug> [--json]`	Full risk score breakdown
`earnforge history <address> <chain-id> [--json]`	30-day APY history

Portfolio and Suggestions

Command	Description
`earnforge suggest <amount> <asset> [--max-vaults] [--max-chains] [--strategy] [--json]`	Portfolio allocation
`earnforge portfolio <wallet> [--json]`	Current wallet positions

Deposit and Withdraw

Command	Description
`earnforge quote <slug> <amount> <wallet> [--from-chain] [--slippage] [--json]`	Build deposit quote
`earnforge withdraw <slug> <amount> <wallet> [--json]`	Build withdraw quote
`earnforge gas-optimize <slug> <amount> <wallet> [--from-chains] [--json]`	Compare cross-chain deposit costs

Safety and Monitoring

Command	Description
`earnforge doctor <slug> [--wallet] [--json]`	Run pitfall checks
`earnforge watch <slug> [--apy-drop] [--tvl-drop] [--json]`	Monitor APY/TVL changes

Reference Data

Command	Description
`earnforge chains [--json]`	List 16 supported chains
`earnforge protocols [--json]`	List 11 protocols
`earnforge strategies [--json]`	List 4 strategy presets

Rules

The SKILL.md defines 9 rules that agents must follow:

Never submit transactions. Only build unsigned quotes. The user signs and broadcasts.
Always check isTransactional before quoting. Non-transactional vaults cannot accept deposits.
Use vault.address as toToken, not the underlying token address. This is Pitfall #5.
Filter stablecoins by the stablecoin tag, not by token symbol.
Risk score thresholds: >= 7 is low risk, 4-6.9 is medium, < 4 is high risk.
TVL is a string in USD. Parse with parseTvl() before comparing.
APY fields (apy1d, apy7d, apy30d) can be null. Use the fallback chain.
apy.reward is null for some protocols. Normalize to 0 before summing.
Use chainId (number), not chain name (string), in all API calls.

Reference Files

references/pitfalls.md

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

references/protocols.md

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

references/chains.md

All 16 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