Align skills with Anthropic's 500-line guidance and add evals

[oceans404]

Context

We audited the skills against Anthropic's authoring guidance (Claude Code skills docs, skill authoring best practices). Most practices are already followed: descriptions state what and when in third person with concrete triggers, names are valid and consistent, references are one level deep, and smart-contracts is a textbook progressive-disclosure layout (router SKILL.md plus companion files).

Two gaps remain. Mechanical fixes from the same audit already landed in #41.

Gap 1: four SKILL.md bodies exceed the recommended 500 lines

Anthropic recommends keeping the SKILL.md body under 500 lines and moving detail into companion files that load only when needed.

Skill	Lines	Proposed split
standards	791	SKILL.md keeps the SEP/CAP routing map (~150 lines). Part 2 becomes ecosystem.md, Part 3 becomes resources.md.
dapp	694	SKILL.md keeps SDK setup, wallet connection, and tx build/submit. React components, passkeys/smart accounts, and fee sponsorship move to companion files.
agentic-payments	626	SKILL.md keeps the protocol decision table and shared testnet runbook. Part 1 becomes x402.md, Part 2 becomes mpp.md.
data	550	Borderline. Move the Horizon legacy section to horizon.md, or trim in place.

This is the same treatment #32 applied to the old soroban skill (2,580 lines to a 193-line router plus three companions), so the pattern and precedent already exist in the repo.

Per-skill checklist:

• Split standards
• Split dapp
• Split agentic-payments
• Split or trim data
• Each router SKILL.md gets a task-to-file routing table like smart-contracts/SKILL.md
• Keep all references one level deep from SKILL.md
• Update site/src/data/skills.ts sources and confirm copy-skills.mjs and generate-llms-txt.mjs handle the new files
• Descriptions stay unchanged unless a split changes what a skill covers

Gap 2: no evaluations

The best-practices doc recommends evaluation-driven development: representative task scenarios per skill, so regressions get caught before publish. #41 fixed several compile-breaking example snippets that evals would have caught.

• Add an evals/ directory with roughly 3 scenarios per skill (query, files if needed, expected behavior). Full proposed scenario set, grading tiers, and an example file: see the eval proposal comment below
• Start with the highest-traffic paths: dapp payment flow, x402 seller/buyer setup, contract deploy and test
• Document how to run them in CONTRIBUTING or the README

Out of scope

• Frontmatter changes (user-invocable: true is redundant with the default but harmless and consistent)
• Description rewrites (all seven pass the guidance)

Sequencing

Do Gap 1 as one PR per skill or one PR for all four, whichever reviews easier. Gap 2 can proceed in parallel and should land before or with the splits so the splits are verified by evals.

[oceans404]

Proposed eval set for Gap 2

Design principle: each eval encodes a mistake Claude actually makes without the skill. Several come from real failure modes (the #41 compile bugs, documented pitfalls in agentic-payments, the ZK curve trap), not imagined ones.

Grading tiers

1. Machine-checkable (strongest, run in CI): generated Rust compiles with cargo build --target wasm32-unknown-unknown, generated TypeScript passes tsc, CLI commands match real stellar syntax. This tier alone would have caught every snippet bug fixed in Fix example code bugs, stale link labels, and duplicated reference content #41.
2. Behavior assertions: expected_behavior strings graded by an LLM judge (Anthropic's eval format).
3. Trigger checks: the right skill loaded, the right companion file was read, and no skill loads for off-topic queries.

Scenarios (3 per skill)

smart-contracts

1. "Write a token contract with an admin who can mint" → __constructor (not guarded initialize), typed DataKey enum, require_auth on mint, checked arithmetic, code compiles.
2. "Add tests including authorization" → env.register with constructor-args tuple, mock_auths or mock_all_auths paired with an env.auths() assertion, reads testing.md.
3. "My contract calls fail after weeks of inactivity, data seems missing" → diagnoses TTL/archival, recommends extend_ttl in hot paths.

dapp

1. "Next.js page that connects Freighter and sends XLM" → error-object freighter-api pattern, network passphrase validation, TypeScript compiles.
2. "Invoke a contract method from the browser" → simulate, assembleTransaction, sign, poll getTransaction.
3. "Set up config for testnet and mainnet" → runs on testnet without the mainnet env var set, throws on unknown network names (the exact bug class from Fix example code bugs, stale link labels, and duplicated reference content #41).

data

1. "Get an account's transactions from 3 months ago" → recognizes RPC's 7-day window, routes to Horizon, Hubble, or getLedgers.
2. "Watch live payments to an address" → Horizon streaming or RPC polling, tradeoff stated.
3. "Read a value from contract storage" → getLedgerEntries with a contractData LedgerKey and scValToNative.

assets

1. "Issue a stablecoin we can freeze" → separate issuer/distributor accounts, AUTH_REQUIRED + AUTH_REVOCABLE, stellar.toml.
2. "My USDC payment fails with op_no_trust" → diagnoses missing trustline, adds check-before-send.
3. "Use USDC inside my contract" → SAC, asset.contractId(), token::Client, does not reinvent a token.

agentic-payments

1. "Monetize my Express API for AI agents" → picks x402 via the decision table, requires OZ_API_KEY, payTo is a G... address with a trustline, $0.001 converts at 7 decimals (not 6).
2. "My agent makes 500 calls per session" → MPP Channel mode, cumulative commitment amounts, warns about Store.memory() in production.
3. "createEd25519Signer throws 'encoded argument must be of type String'" → raw S... secret plus CAIP-2 ID, no Keypair.fromSecret wrapping.

zk-proofs

1. "Verify a Circom Groth16 proof on Stellar" → compiles with -p bls12381, not the default bn128; cites CAP-0059 availability.
2. "Verify my Noir proof on-chain" → correctly says not natively possible today; offers the attestation pattern or a Circom/BLS switch. Highest-value eval in the set: an unskilled model confidently hallucinates a yes here.
3. "Design a private airdrop" → validates public-input semantics, nullifier set for anti-replay, verifier/policy split.

standards

1. "Which SEP for a fiat on-ramp with KYC?" → SEP-6 or SEP-24 plus SEP-12, API-vs-hosted distinction.
2. "Is there an NFT standard and is it final?" → SEP-50, Draft, says to verify current status rather than asserting.
3. "What indexers can I use for contract events?" → Mercury/SubQuery/Goldsky plus the indexer directory link.

Cross-skill routing (catches gaps no single-skill eval sees)

1. "Build a dapp where users pay per API call" → loads both agentic-payments and dapp.
2. "Tokenize a real-world asset with compliance controls" → assets first, standards for SEP-57, not a custom contract by default.
3. Negative control: "help me parse this PDF" → no Stellar skill loads.

Example scenario file

{
  "skills": ["zk-proofs"],
  "query": "I have a Noir circuit that proves age >= 18. Verify the proof on-chain on Stellar.",
  "expected_behavior": [
    "States that Noir's UltraHonk/BN254 output is not natively verifiable on Stellar today",
    "Does not generate a fake on-chain UltraHonk verifier",
    "Offers the attestation-oracle pattern with its trust assumption stated explicitly, or proposes re-expressing the statement as a Circom Groth16 circuit compiled with -p bls12381"
  ]
}

Process

• Run every scenario without the skills first and keep the baseline failures in the repo. That proves each eval discriminates, and tells us which evals to retire as base models improve.
• Tier 1 (compile checks) in CI on every PR; tiers 2 and 3 as a manually triggered workflow to keep costs sane.