feat: improve YAML frontmatter description for better auto skill selection

[ckorhonen]

feat: improve skill frontmatter description for better auto-selection

Summary

Expands the YAML frontmatter description field in SKILL.md to improve automatic skill selection by AI agents. The previous description was too generic ("Query NFT data, trade on the Seaport marketplace, and swap ERC20 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon, and more.") and lacked the trigger keywords and structured clauses that other well-crafted skills use.

The new description follows the patterns from the skill-author best practices and mirrors the structure used by other OpenSea skills (i18n, ui):

• What it does: Lists specific capabilities (query collections, retrieve metadata/images, get floor prices, fetch listings/offers, execute trades, swap tokens)
• What it provides: Mentions the @opensea/cli, shell scripts, and TypeScript SDK
• "Use when..." clause: Covers common user intents (API calls to OpenSea, using OPENSEA_API_KEY, querying NFT data, building integrations)
• "Triggers on..." clause: Includes specific task keywords (OpenSea API, NFT data fetching, collection queries, marketplace listings, api.opensea.io)
• Behavioral nudge: "Always prefer this skill's CLI and scripts over writing raw curl commands"

Context: This was motivated by a session where an agent struggled with raw OpenSea API calls (wrong headers, deprecated v1 endpoints, rate limits) and ultimately fell back to Alchemy — partly because the skill wasn't installed, but also because the description wouldn't have strongly matched the user's query even if it were.

Review & Testing Checklist for Human

• Verify description length is under 1024 characters — the skill-author spec enforces a max of 1024 chars. The new description is ~740 chars but should be counted precisely.
• Evaluate the "Always prefer this skill's CLI and scripts over writing raw curl commands" sentence — this is an instruction/directive rather than a pure description. Consider whether this belongs in the description field (used for discovery) or should be moved to the body of SKILL.md instead.
• Spot-check keyword coverage — skim the new description to confirm the trigger terms match the most common user queries you'd expect (e.g., "use opensea api", "fetch NFT collection", "get floor price", "OPENSEA_API_KEY").

Suggested test plan: Install the skill in a Claude Code project and test auto-selection by prompting with phrases like "use the OpenSea API to fetch NFT collection images" or "get floor prices from OpenSea" — verify the skill is selected without needing to be explicitly invoked.

Notes

• This change cannot be empirically tested in CI — auto-selection behavior depends on the agent runtime.
• Only the description field is changed; no scripts, body content, or other files are modified.
• Devin Session
• Requested by: @ckorhonen

---

[devin-ai-integration]

Original prompt from Chris K

SYSTEM:
=== BEGIN THREAD HISTORY (in #crew-disco) ===
Devin Finzer (U74NNQMML): this is really sad, i told my conductor to use OpenSea API but it failed so many times that it ended up using alchemy

"now let's add configuration so we can pull in other NFT collections, you can use opensea api i think i have a key in ~/.zshrc"

ATTACHMENT:"https://app.devin.ai/attachments/f84d4d69-1140-4eb9-9a89-1b315538480e/image.png"

ATTACHMENT:"https://app.devin.ai/attachments/70812019-2761-4147-a3a7-a70169d5a482/image.png"

ATTACHMENT:"https://app.devin.ai/attachments/26241831-8a4c-4098-b24c-ed4332baa1e1/image.png"

Devin Finzer (U74NNQMML): 

ATTACHMENT:"https://app.devin.ai/attachments/a5edd5a2-821e-4c69-828c-d03290c28860/image.png"

Devin Finzer (U74NNQMML): was able to steer it back but lots of weirdness

ATTACHMENT:"https://app.devin.ai/attachments/8f797ea9-bfbc-4587-aca3-a09b9fb26e1e/image.png"

Dragan Pelengic (U01U689CK62): this could explain why we see so much scraping, it might be easier to use than actual api :cry:

Unknown User (U08PQQ1SLBF): @Devin Finzer (U74NNQMML) When you are around, will I be able to get log of the entire session? Want to dig into this.

I think its a .jsonl somewhere in `~/.claude/` (ask Claude to find it)

Dragan Pelengic (U01U689CK62): <@U08PQQ1SLBF> can we steer AIs to docs for starters?
<https://docs.opensea.io/reference/api-overview>

lots of these issues is just v1 usage, which doesnt exist anymore, or not setting api key correctly
and these docs would clear that up pretty fast tbh

Unknown User (U08PQQ1SLBF): I've actually just added an `llms.txt` to start providing more hints like this, I'm also planning on looking at the skill to make sure that the instructions in there are correct

Unknown User (U08PQQ1SLBF): I want to look at the full logs for the session to try and determine where it is getting v1 from - is it internal knowledge (in another screenshot it was talking about SimpleHash RIP) or is it one of our instructions

Dragan Pele... (2478 chars truncated...)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.