Clarity Skills

Build, improve, test and secure Clarity smart contracts with your AI agent.

Clarity Skills give your agent a router plus 21 focused skills for building, testing, auditing and shipping Clarity smart contracts on Stacks. They also correct what agents get wrong: left alone, an agent writes Clarity the way it writes Solidity, or the way Clarity looked two years ago. The code compiles, the tests pass against mocks, and it breaks on mainnet.

Claude Code

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

Then describe your task. Using Codex or another tool? See every install option.

Skills

Agent platforms

MIT

License

What Models Get Wrong

Clarity is small and decidable, but its mistakes are specific. Asked unaided, current models explain generic DeFi attacks well and miss the Clarity-specific consequences.

Authority

tx-sender is inherited through ordinary contract calls; contract-caller tracks the immediate caller. Inside as-contract?, both refer to the executing contract. Admin checks, user funds and DAO proposals each need the right context.

Assets

In Clarity 4+, a contract spends its own funds inside as-contract? with explicit allowances. Native ft-transfer? does not authenticate the caller as the token owner. Zero and self transfers return errors, which try! propagates.

Traits

A trait argument is checked by shape, not identity, so every one must be compared with the contract expected for its role.

A Moving Ecosystem

Epoch 4.0, Clarity 4 to 6, stacks-block-time, sBTC locked balances, Pyth Core retired in favor of Pyth Lazer, new protocol versions every few months.

Addresses and Interfaces

An agent that guesses a principal or a parameter list writes code that cannot work. The skills ship dated, chain-verified registries and exact call shapes.

Clarity Knowledge

Every model we tested scored higher on Clarity knowledge with the skills.

The article explains how we measured it.

Model	Without Skills	With Skills	Gain
Claude Fable 5.1	85%	100%	+15 pts
Claude Haiku 5.5	80%	94%	+14 pts
Claude Sonnet 5.5	86%	100%	+14 pts
Claude Opus 5.5	89%	100%	+11 pts
gpt-5.6-luna	63.6%	97.2%	+34 pts
gpt-6-astra	92%	100%	+8 pts
gpt-6-sol	83%	100%	+17 pts
gpt-6.1-sol	91%	100%	+9 pts

Start here

One Router, the Right Skills

clarity:start guides the agent to the skills its task needs. Routing and the finish checklist are instructions for the agent; they are not automated enforcement or a guarantee that every check passes.

Session Starts

In Claude Code, a one-line startup hook names the router and common skills when it detects a Clarinet or Stacks project. On other hosts, invoke the router explicitly or add a project instruction.

Route

clarity:start tells the agent which skills to load for the request before writing, reviewing or explaining code.

Apply

The loaded skills hold the rules, exact call shapes and verified addresses, so the agent works from them instead of from memory.

Finish

The router asks the agent to check the work and fix failing items before finishing. Each item links to the relevant rule and test guidance.

Load by Task

Task	Relevant Skills
How Clarity code behaves: what returns, aborts or rolls back	Scholar Security
Write or refactor a contract	Scholar Security Assets
Tests, project setup, coverage, invariants	Testing Fuzzing
Integrate Zest, Granite, Bitflow, Stacks Swap, Hermetica, USDCx, Pyth Lazer and others	Protocols Ecosystem Oracles
Deploy, publish, initialize	Deployment Environments
Audit, review, find bugs	Auditor Security Assets
Upgradeable design, controller replacement, v2 migration	Upgrades Governance
DAO, multisig, admin roles, timelocks	Governance
Execution cost, block limits	Optimizer
Language versions, epochs, compile errors on a keyword	Epochs
SIP-010/009/013 tokens, SIP-018 signatures	SIP Compliance
Off-chain scripts, events, indexers, sBTC deposit history	APIs
Bitcoin transaction proofs, sBTC settlement	Bitcoin Proofs
PoX staking	Staking
Wallet connection, frontends, Ledger	Wallets
Boot contracts, SIP trait addresses, chain mechanics	System Integration

Before Calling a Contract Done

Each item addresses a defect seen in real builds. The router asks the agent to fix failing items before finishing.

Trait arguments match the stored principal
Upgrade targets typed and probed first
Privileged setters checked and logged
Outflows capped by exact as-contract? allowances
Zero, self and dust amounts handled
Assets valued at a verified price
Pyth Lazer prices fully verified
Share mints resist first-deposit inflation
Signers choose minimums and deadlines
Capital in other protocols never blocks claims
Protocol calls match the deployed contracts
Every position has a tested exit
Tested on a pinned mainnet fork
Tests call through attacker contracts
A scripted, resumable release

The Skills

Each skill is one SKILL.md with its rules, decisions, exact call shapes and short code fragments backed by regression tests and source checks. Shared facts live in one owning skill and are linked from the others.

Write

Writing and changing contract code.

Scholar

Writes idiomatic Clarity for the version you deploy: types, responses, error handling, loops and contract layout.

clarity:scholar

Security

Keeps funds and admin roles safe: who is calling, trait checks, asset allowances, arithmetic and rollbacks, with 29 known vulnerability patterns.

clarity:security

Assets

Moves and holds STX, tokens, NFTs and sBTC correctly, including locked balances and wallet post-conditions.

clarity:assets

SIP Compliance

Builds tokens and NFTs that match the SIP-010, SIP-009 and SIP-013 standards exactly, and signed structured data (SIP-018).

clarity:sip-compliance

Optimizer

Cuts execution cost: how Clarity measures cost, block and tenure budgets, and optimizations that keep behavior the same.

clarity:optimizer

Epochs

Picks the right Clarity version and explains what changed between Stacks epochs, including functions that were added or removed.

clarity:epochs

Test and Audit

Proving a contract does what it should, and finding where it does not.

Testing

Sets up and writes typed tests with Clarigen and the Clarinet SDK, from fixtures to tests against a copy of mainnet.

clarity:testing

Fuzzing

Finds edge cases with property and invariant tests in Rendezvous, then replays any failure it finds.

clarity:fuzzing

Auditor

Runs a security review: threat model, a Clarity checklist, proof-of-concept exploits and findings rated by severity.

clarity:auditor

Ship and Operate

Getting contracts on chain and running them safely.

Deployment

Plans and scripts releases to testnet and mainnet: deployment plans, initialization calls, keys, nonces and checks afterwards.

clarity:deployment

Upgrades

Makes immutable contracts upgradable: replaceable controllers, timelocked switch-overs, and moving state and tokens to a new version.

clarity:upgrades

Governance

Designs who controls the protocol: multisigs, DAOs, proposals, timelocks and two-step ownership transfer.

clarity:governance

Environments

Explains why code behaves differently in simnet, devnet, testnet and mainnet, and where to test what.

clarity:environments

Wallets

Connects apps to Leather, Xverse and Ledger to call contracts and sign messages, with post-conditions.

clarity:wallets

Integrate

Working with the rest of Stacks, and with Bitcoin.

Protocols

Verified addresses and exact function signatures for Stacks DeFi protocols such as Zest, Granite, Bitflow and Hermetica.

clarity:protocols

Ecosystem

Combines several protocols in one contract: flash loans, liquidations, swaps and vault strategies in a single transaction.

clarity:ecosystem

Oracles

Reads prices safely from Pyth and DIA: signature checks, units, staleness and confidence.

clarity:oracles

Bitcoin Proofs

Verifies Bitcoin transactions from Clarity with Merkle proofs, checks BTC payments and settles sBTC deposits and withdrawals.

clarity:bitcoin-proofs

Staking

Stakes STX through PoX: staking and unstaking, signers, reward cycles, delegation and liquid staking.

clarity:staking

APIs

Reads chain data from scripts and indexers: Hiro and node APIs, events, balances and sBTC deposit history.

clarity:apis

System Integration

Finds standard Stacks system contracts and trait addresses, and explains blocks, tenures and transactions.

clarity:system-integration

Install

The skills link to each other: install the whole set, never a single folder. One repository is both the plugin and its marketplace, so Claude Code and Codex install the same clarity@clarity-skills. Install it separately in each tool you use.

Full install guide on GitHub

Claude Code

CLI · IDE · Desktop

Terminal

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

Or in one step, from your shell

claude plugin install clarity --marketplace cybasecurity/clarity-skills

Skills appear as clarity:*. Describe the task, or start with /clarity:start.
A startup hook adds about 200 tokens in Clarity and Stacks projects, naming the router and the skills for common tasks; elsewhere it prints nothing.
Update with claude plugin update clarity@clarity-skills.
Remove with claude plugin uninstall clarity@clarity-skills.

Codex

CLI

Terminal

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

Or install from /plugins in Codex. The Codex IDE extension does not load plugins.
Invoke $clarity:start or any skill, such as $clarity:auditor. Codex asks you to review the startup hook before it runs.
Update with codex plugin marketplace upgrade clarity-skills.
Remove with codex plugin remove clarity@clarity-skills.

Gemini CLI

CLI

Terminal

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

Skills appear as clarity-start, clarity-security and so on. Instead of a startup hook, the extension loads the router into every session.
Update with gemini extensions update clarity.
Remove with gemini extensions uninstall clarity.

Google Antigravity

CLI · App

Terminal

agy plugin install https://github.com/cybasecurity/clarity-skills

Each skill is also a slash command: /clarity-start, /clarity-security.
Remove with agy plugin uninstall clarity; to update, install again.

OpenCode

CLI · Desktop

Terminal

git clone https://github.com/cybasecurity/clarity-skills.git ~/clarity-skills

~/.config/opencode/opencode.json

{
  "skills": { "paths": ["~/clarity-skills/skills"] }
}

OpenCode loads all 22 skills from the clone; check with opencode debug skill. Update with git pull in the clone.
Skills appear as clarity-start, clarity-security and so on, and the startup hook does not run: ask for clarity-start to begin.

Claude Apps

Coming soon

Claude apps support is on the way.

Claude Apps

Web · Desktop · Cowork

Open Customize > Plugins, select Add > Add marketplace, enter cybasecurity/clarity-skills and add clarity.
Needs a Pro, Max, Team or Enterprise plan, with code execution turned on in Settings > Capabilities. The plugin follows your account into Cowork and Claude Code.
In chat, type / and pick a clarity: skill. Team and Enterprise Owners can install it for the whole organization.

ChatGPT Workspaces

Coming soon

ChatGPT workspace support is on the way.

GitHub Copilot

Coming soon

GitHub Copilot support is on the way.

GitHub Copilot

CLI · VS Code

Terminal

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

In VS Code, with agent plugins on, run Chat: Install Plugin From Source and enter https://github.com/cybasecurity/clarity-skills.
Copilot lists the skills as clarity-start, clarity-security and so on, and does not run the startup hook: ask for clarity-start to begin.

Factory Droid

Coming soon

Factory Droid support is on the way.

Factory Droid

CLI

Terminal

droid plugin marketplace add cybasecurity/clarity-skills
droid plugin install clarity@clarity-skills --scope user

Update with droid plugin update clarity@clarity-skills.
Remove with droid plugin uninstall clarity@clarity-skills.

Devin CLI

Coming soon

Devin CLI support is on the way.

Cline

Coming soon

Cline support is on the way.

Cline

CLI · VS Code

Terminal

cline skill add https://github.com/cybasecurity/clarity-skills/tree/main/skills --skill '*' -g

Installs all 22 skills into ~/.agents/skills, which the Cline CLI and the VS Code extension both read; check with cline config skills.
Skills appear as clarity-start, clarity-security and so on, and the startup hook does not run: ask for clarity-start to begin.
Update with npx skills update -g.

Kiro

Coming soon

Kiro support is on the way.

Kiro

IDE · CLI

Terminal

npx skills add https://github.com/cybasecurity/clarity-skills/tree/main/skills --skill '*' -a kiro-cli -g

Installs all 22 skills into ~/.kiro/skills, which the Kiro IDE and CLI both read. Each skill is also a slash command: /clarity-start, /clarity-security.
Or, in the IDE, add it as a power: Powers > Add Custom Power > Import power from GitHub, then enter https://github.com/cybasecurity/clarity-skills.
Update with npx skills update -g.

Cursor

Coming soon

Cursor support is on the way.

ChatGPT

Coming soon

Clarity skills is on its way to the ChatGPT Plugins directory.

Other Agents

Any Agent Skills tool

Skills CLI

npx skills add https://github.com/cybasecurity/clarity-skills/tree/main/skills --skill '*'

Or ask your agent

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.

Or point AGENTS.md at the router, in a clone

Before writing, testing or reviewing Clarity contracts, read /path/to/clarity-skills/skills/clarity-start/SKILL.md and the skills it names for the task.

The repository's skills/ folder holds every skill with a clarity- prefix, so it sits next to other Agent Skills sets without clashes. Install all 22: they link to each other.
Point the skills CLI at skills/, not the repository root, or copy every skills/clarity-* folder into your tool's skills directory.

Try It

After loading the router, describe the task in your own words. You can also invoke a specific skill using the examples above.

Example prompts

Build a USDCx vault with a 7-day withdrawal queue and tests.
Review contracts/vault.clar for security issues.
Make this vault upgradable without migrating user funds.
Integrate a Zest flash loan to liquidate an unhealthy position, then deposit the surplus in Hermetica.
Deploy this project to mainnet; it depends on sBTC.

Addresses That Stay Fresh

Deployed Clarity code is immutable, so a recorded address keeps its code. What ages is whether a protocol still uses that contract and its settings.

Address registries carry the date they were verified against the chain.
After 30 days, the skills suggest updating the package and verify each address an agent will use with a bundled, read-only script.
The skills never fetch instructions or registry files at run time. Refreshed registries ship as releases, ideally about once a month.
Roles and parameters are always read from the protocol before deploying or signing.

Contributing

Corrections Need a Source

Open an issue or pull request with a minimal example, the affected Clarity version and epoch, and a link to the implementation, specification or chain evidence.

Open an issue

Write-up

How We Built and Measured Them

Why the skills exist, how we evaluated them with and without the plugin, and where they help and where they do not.

Read the article

Clarity audits

Shipping Clarity to Mainnet?

Skills make an agent's first draft better. Before mainnet, get a security review from the team that wrote them.

MIT License · Changelog · llms.txt