Clarity Skills: From Simnet to Mainnet

Foreword

AI coding agents write Clarity the way they write Solidity, or the way Clarity looked two years ago. The code compiles, the tests pass against mocks, and then it breaks on mainnet. We built Clarity skills, an open set of 22 agent skills for Stacks development, and measured what they change. This article covers what they are, why we made them, and what our evaluations show, including where they do not help.

Executive Summary

• Clarity skills are a router plus 21 focused skills that teach AI agents how Clarity and Stacks behave today, for building, testing, auditing and shipping contracts. One free repository (MIT) installs in Claude Code, Codex, Gemini CLI, Google Antigravity, OpenCode and any tool that reads Agent Skills.
• We tested eight models, and every one of them scored higher on Clarity knowledge with the skills. The weakest model gained most (gpt-5.6-luna 64% → 97%), Claude Haiku went from 80% to 94%, and six of the eight reached 100%.
• A small model with the skills beat bigger ones without them. Reading the skills makes each response cost two to three times as much, yet Claude Haiku with the skills beat every Claude model without them, at about a tenth of Opus's cost.
• We also tested real builds, where the skills changed what agents got wrong: no high-severity defects in three Sonnet builds of the same vault, prices from the live oracle instead of a retired one, tests on a mainnet fork instead of mocks. With the current version, builds cost about the same as without the skills, and the results are steadier: Sonnet's vault upgrades passed every automated check in 8 of 9 runs, against none without them.
• Measuring Clarity knowledge alone was done through 5,616 sessions across eight Claude and OpenAI models, on top of the build, audit and routing studies below.

Why We Built It

Clarity is a small, decidable language, but its mistakes are specific. Without help, current models explain generic DeFi attacks well but miss the Clarity-specific consequences: what is-standard checks, that a zero-share mint fails, how a mainnet-fork test must be configured. On our quiz, the eight models we tested answered 64% to 92% of the questions correctly without the skills, and they were weakest on chain APIs, epoch changes, deployment and fuzzing.

The skills correct these mistakes before code is written:

• tx-sender is inherited through ordinary contract calls, while contract-caller tracks the immediate caller. Inside as-contract? (or legacy as-contract), both refer to the executing contract. Admin checks, user funds and DAO proposals each need the right one (Clarity keyword reference).
• From Clarity 4 on, a contract spends its own funds inside as-contract? with explicit allowances. Native ft-transfer? does not authenticate the caller as the token owner, and zero or self transfers return errors that try! propagates (native transfer reference).
• A trait argument is checked by shape, not by identity, which means each one must be compared with the expected contract. A trait-typed parameter inside your own trait is compared by identity, though: a local copy of a protocol's trait breaks calls to the real contract.
• The platform keeps moving: epoch 4.0, Clarity 4 to 6, stacks-block-time, sBTC's locked balances, Pyth Core retired on Stacks in favor of Pyth Lazer, and new protocol versions every few months.
• An agent that guesses a principal or a parameter list writes code that cannot work. The skills ship dated, chain-verified address registries and the exact call shapes.

What Is in the Package

Skill	What it covers
clarity:start	Router: which skills to load for any Clarity task, and the checklist to pass before calling a contract done
clarity:scholar	Idiomatic, version-aware Clarity: types, responses, iteration, layout
clarity:security	Authority, traits, allowances, arithmetic, rollback; 29 vulnerability patterns
clarity:auditor	Audit workflow, a Clarity checklist, PoCs and findings
clarity:testing	Typed tests with Clarigen on the Clarinet SDK, mainnet forks
clarity:fuzzing	Property and invariant testing with Rendezvous
clarity:optimizer	The five cost dimensions and safe optimizations
clarity:deployment	Clarinet plans, initialization, release verification
clarity:upgrades	Replaceable controllers, timelocked cutovers, migrations
clarity:governance	Multisigs, DAOs, timelocks, two-step ownership
clarity:epochs	Language versions, epochs, historical behavior
clarity:assets	STX, FTs, NFTs, sBTC, wSTX, custody and postconditions
clarity:sip-compliance	SIP-010/009/013 conformance rules and exact traits, SIP-018 signatures
clarity:protocols	Verified addresses and call signatures for Stacks DeFi
clarity:ecosystem	Composing protocols: flash loans, swaps, vault strategies
clarity:oracles	Pyth Lazer and DIA: verification, units, freshness
clarity:staking	PoX and liquid staking
clarity:bitcoin-proofs	Bitcoin transaction proofs and sBTC settlement
clarity:wallets	Stacks wallets, signing and hardware signers
clarity:environments	Simnet, devnet, testnet and mainnet differences
clarity:apis	Hiro and node APIs, events, sBTC deposit history
clarity:system-integration	Boot contracts, standard traits, system addresses

Each skill is a single SKILL.md with its rules, decisions, exact call shapes and short code fragments. The few reference files are lookup tables: verified addresses, the VM function catalog and cost tables. The examples are backed by regression tests and source checks. Each skill also records its review date and a reference baseline: the Clarity version and epoch its examples were checked on, plus the exact upstream commits its sources point to.

The package includes helper scripts that use only the Python standard library and never sign or broadcast a transaction. There is no telemetry: nothing reports usage, prompts or code to us or anyone else.

How We Tested

Every test runs the same task twice, with the skills and without them. The prompts never name the skills, so finding them is part of the test. We ran four kinds of test:

• A quiz of 95 multiple-choice questions on Clarity behavior, testing, deployment, protocol interfaces, chain APIs, security, fuzzing and upgrades, each backed by an executable check, chain data or pinned source, with three trials per question and model.
• Real builds, where full agent sessions build a USDCx queue vault with a Zest rebalancer, an epoch vault working across Granite, Hermetica and Zest, an upgrade of an existing vault, and an sBTC deposit reader. Both vaults swap USDCx on chain, through Bitflow DLMM or Stacks Swap. A reviewer who does not know which runs had the skills runs the tests, probes attacks and checks every contract call against mainnet.
• Audits of contracts with 18 seeded (deliberately planted) bugs.
• Eighteen realistic first prompts that check whether an agent picks the right skill on its own.

Because build runs are few (one to three per setup), we treat small score differences as noise and look at defects, cost and time instead.

What We Found

Knowledge: Every Model Answered More Correctly

Every model saw all 95 questions, three times with the skills and three times without; we ran 5,616 sessions in all, and the table counts each question's latest run. Claude found the skills on its own through the Claude Code plugin. The OpenAI models answered through Codex: they saw the list of skills and could read skill files in up to three rounds, with no shell or web access. Compare the two columns within a row; the rows are not a ranking of vendors.

The largest gains came where models were weakest without help: epoch and version changes (72% → 100% across all models), chain APIs (68% → 93%) and fuzzing with Rendezvous (76% → 100%). Clarity's language rules, the largest topic, went from 81% to 99.5% and protocol interfaces from 82% to 99%. Across all models, 348 answers went from wrong to right with the skills and 3 from right to wrong. The control questions, general facts that strong models know anyway, did not drop (98% → 100%), and all of Haiku's remaining mistakes came from sessions that never loaded a skill.

The Newest Models

Opus 5.5 knew the most of the Claude models without help (89%) and often answered without opening a skill: it read one in under half of its sessions, and with the skills it answered every question correctly either way. Fable 5.1 started lower (85%), opened a skill in almost every session and reached 100%. gpt-6-astra went from 92% to 100%, with no answer made worse.

What the Extra Knowledge Costs

Reading one to three skill files makes each answer bigger: about four times the input tokens in Codex and two to three times the cost per answer in Claude Code at API prices. A smaller model with the skills still came out ahead. Haiku with the skills (94%) beat every Claude model without them, at about a fifth of Sonnet's cost per answer and a tenth of Opus's. Among the OpenAI models, gpt-5.6-luna with the skills (97%) beat the strongest ones without them (91–92%). In a full build the skills are a fixed cost spread over a long session, and the first version cut vault build costs by about half, as the next section shows.

Builds: Different Defects, Mixed Cost

Cost and Speed

With the first version of the skills, the four vault builds cost 41–54% less, used 48–69% fewer tokens and finished up to 3× faster, because agents no longer rediscovered addresses, interfaces and Clarity behavior by trial and error. On small tasks that needed no skill, the plugin only added its overhead.

Quality

Reviewer scores stayed close to the runs without skills; the difference was in the defects. Sonnet's queue vault had no high-severity defects in any of three runs, where the run without skills had two. Its epoch vault priced positions from the live Pyth Lazer feed; without the skills it used Pyth Core, which no longer publishes on Stacks. Haiku's best queue vault rose from 50% to 75% of the review points, with a mainnet-fork test suite and share math safe against the first-deposit attack.

Steadier After the Restructure

Once every rule lived in the skills' main files (see What We Learned), Sonnet's vault upgrades passed all 17 automated checks in 89% of runs (8 of 9), against none of 2 without the skills. Sonnet also found all 18 seeded bugs once it loaded the auditor skill (16 without). The larger files cost tokens: Sonnet's queue vault went back to about the cost of building without skills.

OpenAI Models

In a stricter setup, where the agent could edit files and see compile and test results but not run commands, more OpenAI runs passed every acceptance test with the skills loaded: 50% → 72% on three build tasks, 59% → 85% on the tasks we developed the skills against and 33% → 100% on an escrow task the skills were never tuned on. Left to find the skills on their own, they opened one in only 39% of runs.

Getting the Skills Used

The gains come from the router, rewritten descriptions and, for the last row, a startup hook that adds one line of context in a Clarity project, naming the router and the skills for common tasks. The hook runs in Claude Code and, once you review it, in Codex. Elsewhere, begin a Clarity task by asking for the router or add a project instruction.

What We Learned

Agents Act on the Main File

Agents read a skill's main file, SKILL.md, but rarely open its reference files: none did in any upgrade session. As a result, we moved every must-follow rule into the main files, which grew about fourfold; only lookup tables stay in references.

One Sentence Can Make Things Worse

One skill told agents to "stage the exact target principal" when scheduling an upgrade. Small models took it literally and accepted any address as the new contract, without checking that it had the functions the protocol calls. Without the skills, they passed this check. Stating the safe pattern fixed it. We then audited all 22 files for sentences that mislead when read alone. We found and rewrote 15.

Single Runs Mislead

One Haiku queue vault scored 92% of the review points; three more runs scored between 46% and 71%. We now run three trials per setup.

The Startup Line Matters More Than Router Wording

Most regressions came from sessions that never loaded the skill holding the rule, and rewording the router did not change that. Naming the right skills in the startup hook's line, which every session in a Clarity project sees, did: Sonnet loaded the auditor skill four times as often.

Keep the Router a Router

Every session reads the router, and each round of fixes had added rules to it until it reached 2,559 words. We cut it to 795 words: which skills to load, plus a checklist of one-line items that each link to the skill holding the rule. Quiz scores did not drop.

Skills Do Not Fix Everything

Sonnet edited a test file the task told it not to change, with or without skills. And when a task already hands the agent everything it needs, as our sBTC deposit reader did with its chain data supplied, the skills only add their cost.

Every Traced Defect Became a Check

Every defect we traced to the skills became a fix and a regression test. For example:

• Vaults guard against a first depositor inflating the share price.
• Withdrawals include the allowance for share tokens the protocol burns.
• Upgrades probe a new contract before scheduling it.
• Integrations validate how each protocol function actually behaves before relying on it.
• Scripts that read old sBTC deposits jump to that block range instead of paging back from the newest block.

Keeping Addresses Fresh Without Remote Instructions

Deployed Clarity code is immutable, thus a recorded address keeps its code. What ages is whether a protocol still uses that contract and its settings. The skills never fetch instructions or registry files at run time: once the bundled address registry is more than 30 days old, they suggest updating the package and check each address they use against the chain with a bundled read-only script, which compares the deployed source and its deployment transaction with the recorded ones. Refreshed registries ship as releases, ideally about once a month. Each release is tagged and listed with its changelog on the Releases page, and main always holds the latest one.

Installation

One repository is both the plugin and its marketplace, so Claude Code and Codex install the same clarity@clarity-skills. Install the whole set in each tool you use, since the skills link to each other.

Claude Code:

/plugin marketplace add cybasecurity/clarity-skills
/plugin install clarity@clarity-skills

Invoke /clarity:fuzzing or /clarity:scholar, or start with /clarity:start.

Codex CLI:

codex plugin marketplace add cybasecurity/clarity-skills
codex plugin add clarity@clarity-skills

Invoke $clarity:fuzzing or $clarity:scholar, or start with $clarity:start.

Gemini CLI:

gemini extensions install https://github.com/cybasecurity/clarity-skills

Gemini CLI, Google Antigravity and OpenCode install a copy whose skills carry a clarity- prefix (clarity-start, clarity-security), because they do not group plugin skills under a namespace. Any other agent that reads Agent Skills can install them itself: paste this into its chat.

Install the Clarity skills from https://github.com/cybasecurity/clarity-skills: copy every folder in its skills/ directory into your skills directory, then use clarity-start for Clarity and Stacks tasks.

The install guide has every host's steps, including updates, removal and team setup. Support for the Claude apps, ChatGPT, GitHub Copilot and VS Code, Factory Droid, Devin CLI, Cline, Kiro, Cursor, and the Claude and ChatGPT directories is on the way.

Conclusion and Future Work

The Clarity skills improve AI agents' understanding of Clarity and Stacks, and they change which mistakes agents make in real builds. To be noted that they do not guarantee that an agent's code is safe on their own.

We will keep maintaining and improving them, ensuring quality does not drop. Also, each release will carry refreshed protocol addresses and interfaces where needed.

We chose to release the skills now, as they are, rather than continuously refining them, since, without seeing how the community uses them, we may end up in an echo chamber with improving on points that are not actually needed. New improvements and extensions will try to follow how protocols and developers actually use the skills in real life. For that reason, we are grateful for every bug report, correction and contribution given to us.

As a security company, we want to be clear about the auditor skill: it is a starting point. It gives an agent a Clarity-specific review method and checklist. In our tests it improved bug detection but it is no substitute for a professional audit and, in our view, no skill should be a substitute. Improving it is one of our goals, such that Clarity contracts are written as safely as possible.

The source is at cybasecurity/clarity-skills (MIT). To report a mistake or propose a change, see CONTRIBUTING.md. Report security problems privately to security@cybasecurity.io, as the security policy describes.

About the Quiz

Questions are phrased as a developer would ask them, with wrong options drawn from common mistaken beliefs such as Solidity habits and pre-Clarity 4 behavior. We reviewed every answer against its evidence and rewrote the options so the correct one is not simply the longest: always picking the longest option now scores 19%, below the 25% of a random guess.

The sessions with and without skills see the options in the same order; in Codex the order changes between trials, in Claude Code it stays fixed per question. Only the exact letter counts.

The quiz favors facts the package covers; as such, free-response code tasks and exploit tests remain necessary. Download the questions, answers and evidence and the aggregate results, with topic, paired and cost breakdowns.

Project Page

The Clarity Skills project page elaborates the install steps for every supported tool, which skills to load for each task, the checklist the router asks the agent to pass before calling a contract done and what each of the 22 skills covers.