Tooling freshness, cross-skill handoffs, and multi-agent discoverability

.cursor/rules/starknet-skills.md

@@ -0,0 +1,34 @@
+---
+name: cursor-starknet-skills
+description: Router and enforcement rules for using starknet-skills in Cursor.
+---
+
+# Starknet Skills for Cursor
+
+This project provides Cairo/Starknet skills for AI coding agents. When working on Cairo contracts, load the appropriate skill from this repository.
+
+## Skill Router
+
+Each skill is at `<skill-name>/SKILL.md`. Read it and follow its orchestration steps.
+
+| Task | Skill to load |
+|------|---------------|
+| Write a new Cairo contract | `cairo-contract-authoring/SKILL.md` |
+| Add tests to a contract | `cairo-testing/SKILL.md` |
+| Optimize gas/steps | `cairo-optimization/SKILL.md` |
+| Security review | `cairo-auditor/SKILL.md` |
+| Deploy/declare/verify | `cairo-toolchain/SKILL.md` |
+
+## Current Tooling (March 2026)
+
+- Scarb >= 2.14.0 (recommended 2.16.x)
+- Starknet Foundry 0.57.0
+- OpenZeppelin Cairo 3.0.0
+
+## Security Rules (always enforced)
+
+1. Every storage-mutating external has explicit access posture: guarded or documented-public.
+2. Constructor validates all critical addresses are non-zero.
+3. Upgrade flows reject zero class-hash values.
+4. Timelock checks read from `get_block_timestamp()`, never from caller arguments.
+5. Anti-pattern/secure-pattern pairs enforced — the anti-pattern is never written.

AGENTS.md

@@ -1,3 +1,47 @@
-# starknet-skills
+---
+name: repo-agent-instructions
+description: Top-level guidance for agents using starknet-skills modules.
+---
 
-Canonical router: [SKILL.md](./SKILL.md)
+# Agent Instructions
+
+This repository contains Cairo/Starknet skills for AI coding agents. Each skill is a prescriptive orchestrator — it tells you exactly what to load, what to check, and in what order.
+
+## Available Skills
+
+| Skill | Use when | Entry point |
+|-------|----------|-------------|
+| **cairo-auditor** | Security review of Cairo contracts | `cairo-auditor/SKILL.md` |
+| **cairo-contract-authoring** | Writing new contracts or modifying existing ones | `cairo-contract-authoring/SKILL.md` |
+| **cairo-testing** | Writing unit, integration, fuzz, or regression tests | `cairo-testing/SKILL.md` |
+| **cairo-optimization** | Profiling and optimizing gas/steps | `cairo-optimization/SKILL.md` |
+| **cairo-toolchain** | Build, declare, deploy, verify operations | `cairo-toolchain/SKILL.md` |
+| **account-abstraction** | Account abstraction patterns and risks | `account-abstraction/SKILL.md` |
+| **starknet-network-facts** | Starknet network constraints and semantics | `starknet-network-facts/SKILL.md` |
+
+## Recommended Flow
+
+For new contract work, use this sequence:
+
+1. `cairo-contract-authoring` — write the contract
+2. `cairo-testing` — add tests
+3. `cairo-optimization` — optimize hot paths (if needed)
+4. `cairo-auditor` — security review
+
+## How to Use
+
+Each `SKILL.md` file contains:
+- **When to Use / When NOT to Use** — scope boundaries
+- **Quick Start** — 5-step summary
+- **Orchestration** — turn-by-turn instructions with exact tool calls
+- **Security-Critical Rules** — non-negotiable constraints
+- **References** — links to detailed reference material
+
+Read the `SKILL.md` for the task at hand. Follow its orchestration steps. Load references only when the orchestration tells you to — this keeps context focused.
+
+## Tooling Versions (March 2026)
+
+- Scarb: >= 2.14.0 (recommended 2.16.x)
+- Starknet Foundry (snforge/sncast): 0.57.0
+- OpenZeppelin Cairo: 3.0.0
+- Cairo edition: 2024_07

README.md

@@ -1,3 +1,8 @@
+---
+name: starknet-skills
+description: Cairo/Starknet skills for AI coding agents with router and module links.
+---
+
 # starknet-skills
 
 <p align="center">
@@ -78,13 +83,27 @@ Audit src/contract.cairo using the cairo-auditor skill
 
 ### Cursor
 
-Clone the repo and add it as a context directory in Cursor settings (or load the router URL directly):
+Clone the repo:
 
 ```bash
 git clone https://github.com/keep-starknet-strange/starknet-skills.git
 ```
 
-Open the cloned directory in Cursor (or add it as a context directory in settings). Then try:
+Option 1: add the cloned repo as a context directory in Cursor settings.
+
+Option 2: copy the rule file and selected skills into your project.
+Run the following from your project root and replace `/path/to/starknet-skills` with your clone path:
+
+```bash
+cd /path/to/your/project
+mkdir -p .cursor/rules .cursor/skills
+cp /path/to/starknet-skills/.cursor/rules/starknet-skills.md .cursor/rules/
+cp -r /path/to/starknet-skills/cairo-auditor .cursor/skills/cairo-auditor
+cp -r /path/to/starknet-skills/cairo-testing .cursor/skills/cairo-testing
+cp -r /path/to/starknet-skills/cairo-contract-authoring .cursor/skills/cairo-contract-authoring
+```
+
+Then try:
 
 ```text
 Write an ERC20 token contract following the cairo-contract-authoring skill

SKILL.md

@@ -29,4 +29,7 @@ For new contract work, use this sequence:
 
 1. [cairo-contract-authoring](cairo-contract-authoring/SKILL.md)
 2. [cairo-testing](cairo-testing/SKILL.md)
-3. [cairo-auditor](cairo-auditor/SKILL.md)
+3. [cairo-optimization](cairo-optimization/SKILL.md) (if performance matters)
+4. [cairo-auditor](cairo-auditor/SKILL.md)
+
+`cairo-contract-authoring`, `cairo-testing`, and `cairo-optimization` output a **Handoff Block** at the end of their workflows — a structured summary (files touched, security posture, test status) that can be passed as input to the next skill. See [references/skill-handoff.md](references/skill-handoff.md) for the format.

cairo-contract-authoring/SKILL.md

@@ -33,7 +33,8 @@ You are a Cairo contract authoring assistant. Your job is to understand what the
 2. Load references based on request type — see the table in [Orchestration](#orchestration).
 3. Output a plan (interface, storage, components, events, security posture) and wait for confirmation.
 4. Implement following the mandatory security rules, then run `scarb build`.
-5. Verify every external function's access posture, then suggest `cairo-testing` and `cairo-auditor`.
+5. Verify every external function's access posture.
+6. Emit a handoff block using `../references/skill-handoff.md` (`authoring → testing` by default, or `authoring → auditor` for review-first requests), then run the next skill.
 
 ## Rationalizations to Reject
 
@@ -122,7 +123,8 @@ These are non-negotiable. Every contract you write must satisfy all of them:
 - Language fundamentals: [language.md](references/language.md)
 - Contract patterns and OZ components: [legacy-full.md](references/legacy-full.md)
 - Anti-pattern/secure-pattern pairs: [anti-pattern-pairs.md](references/anti-pattern-pairs.md)
-- Authoring to audit handoff: [audit-handoff.md](references/audit-handoff.md)
+- Cross-skill handoff format (canonical for all handoffs): `../references/skill-handoff.md`
+- Legacy authoring-to-audit handoff reference (superseded by canonical format): [audit-handoff.md](references/audit-handoff.md)
 - Module index: [references/README.md](references/README.md)
 
 ## Workflow

cairo-contract-authoring/references/legacy-full.md

@@ -1,3 +1,8 @@
+---
+name: cairo-contract-authoring-legacy-full
+description: Comprehensive reference for Cairo contract structure, components, and security hardening patterns.
+---
+
 # Cairo Contract Authoring
 
 Reference for writing Cairo smart contracts on Starknet. Covers structure, storage, events, interfaces, components, and OpenZeppelin v3 patterns.
@@ -61,6 +66,38 @@ Reject zero class hash in both schedule and immediate-upgrade flows:
 assert!(new_class_hash != 0, "class_hash_zero");
 ```
 
+## Recommended Scarb.toml
+
+Use these versions for new projects (as of March 2026):
+
+```toml
+[package]
+name = "my_contract"
+version = "0.1.0"
+edition = "2024_07"
+
+[dependencies]
+starknet = "^2.16.0"
+openzeppelin_access = "3.0.0"
+openzeppelin_introspection = "3.0.0"
+openzeppelin_token = "3.0.0"
+openzeppelin_upgrades = "3.0.0"
+openzeppelin_security = "3.0.0"
+
+[dev-dependencies]
+snforge_std = "0.57.0"
+
+[cairo]
+sierra-replace-ids = true
+
+[[target.starknet-contract]]
+
+[tool.scarb]
+allow-prebuilt-plugins = ["snforge_std"]
+```
+
+> **Version pinning:** This template targets Scarb **2.16.x** with `starknet = "^2.16.0"` and `snforge_std = "0.57.0"`. If you use an older toolchain, pin compatible versions from the release matrix before production use. Check [scarbs.dev](https://scarbs.dev) for updates.
+
 ## Contract Structure
 
 Every Starknet contract follows this skeleton:
@@ -311,7 +348,7 @@ mod MyComponent {
 
 ```toml
 [dependencies]
-starknet = ">=2.12.0"
+starknet = "^2.16.0"
 openzeppelin_access = "3.0.0"
 openzeppelin_token = "3.0.0"
 openzeppelin_upgrades = "3.0.0"

cairo-optimization/SKILL.md

@@ -33,7 +33,9 @@ You are a Cairo optimization assistant. Your job is to profile existing code, id
 2. Profile hot paths with `python3 scripts/profile.py profile`.
 3. Load references based on optimization type — see the table in [Orchestration](#orchestration).
 4. Apply one optimization class at a time, re-test after each.
-5. Compare before/after profiles, then run `cairo-auditor` to check for security regressions.
+5. Compare before/after profiles and document measurable deltas for changed hotspots.
+6. Encode stable optimization regressions in `../evals/cases/contract_skill_benchmark.jsonl` to prevent benchmark drift.
+7. Emit a handoff block using `../references/skill-handoff.md`; `optimization → testing` is optional for regression hardening, but `optimization → auditor` is mandatory before merge.
 
 ## Rationalizations to Reject
 
@@ -139,8 +141,10 @@ These are non-negotiable. Every optimization you apply must satisfy all of them:
 - Optimization rules and BoundedInt: [legacy-full.md](references/legacy-full.md)
 - Profiling CLI and troubleshooting: [profiling.md](references/profiling.md)
 - Optimization anti-pattern pairs: [anti-pattern-pairs.md](references/anti-pattern-pairs.md)
+- Cross-skill handoff format: `../references/skill-handoff.md`
 - Module index: [references/README.md](references/README.md)
 
 ## Workflow
 
 - Main optimization flow: [default workflow](workflows/default.md)
+- Mandatory pre-merge chain: `optimization → auditor` (with `optimization → testing` only as an optional regression-hardening pass before auditor).

cairo-testing/SKILL.md

@@ -33,6 +33,7 @@ You are a Cairo testing assistant. Your job is to understand what the user needs
 3. Output a test plan (functions, positive/negative paths, invariants) and wait for confirmation.
 4. Implement tests following snforge patterns, then run `snforge test`.
 5. Verify coverage: every external tested? auth paths? negative cases? events?
+6. Emit a handoff block using `../references/skill-handoff.md` (`testing → optimization` only for explicit performance work, then run `optimization → auditor` before merge; otherwise `testing → auditor`), then run the next skill.
 
 ## Rationalizations to Reject
 
@@ -140,6 +141,7 @@ These are non-negotiable. Every test suite you write must satisfy all of them:
 ## References
 
 - Testing patterns and snforge API: [legacy-full.md](references/legacy-full.md)
+- Cross-skill handoff format: `../references/skill-handoff.md`
 - Module index: [references/README.md](references/README.md)
 - Security regression recipes: `../datasets/distilled/test-recipes/`
 

cairo-testing/references/legacy-full.md

@@ -1,3 +1,8 @@
+---
+name: cairo-testing-legacy-full
+description: Detailed snforge testing reference for Cairo contracts, including unit, integration, fuzz, and fork patterns.
+---
+
 # Cairo Testing
 
 Reference for testing Cairo smart contracts with Starknet Foundry (snforge).
@@ -28,14 +33,17 @@ For security regression tests, prefer templates under:
 
 ```toml
 [dev-dependencies]
-snforge_std = "0.56.0"
+snforge_std = "0.57.0"
+
+[tool.scarb]
+allow-prebuilt-plugins = ["snforge_std"]
 
 [[target.starknet-contract]]
 sierra = true
 casm = true
 ```
 
-> **Note:** snforge 0.56.0 requires Scarb >= 2.12.0. Check [scarbs.dev/packages/snforge_std](https://scarbs.dev/packages/snforge_std) for the latest version.
+> **Note:** snforge 0.57.0 requires Scarb >= 2.12.0 (recommended: 2.16.x). Check [scarbs.dev/packages/snforge_std](https://scarbs.dev/packages/snforge_std) for the latest version.
 
 ### Running Tests
 
@@ -46,7 +54,10 @@ snforge test
 # Run specific test by name
 snforge test test_transfer
 
-# Run tests matching a pattern
+# Run tests matching a pattern (if your snforge build supports --filter)
+snforge test --filter test_erc20
+
+# Run tests matching a pattern (positional fallback)
 snforge test test_erc20
 
 # Filter to a single test function (exact match)

cairo-toolchain/references/legacy-full.md

@@ -1,3 +1,8 @@
+---
+name: cairo-toolchain-legacy-full
+description: Deployment and operational reference for Cairo contracts with sncast and Starknet Foundry.
+---
+
 # Cairo Toolchain
 
 Reference for deploying Cairo smart contracts to Starknet using sncast (Starknet Foundry).
@@ -22,20 +27,20 @@ Reference for deploying Cairo smart contracts to Starknet using sncast (Starknet
 ```bash
 # Install via asdf (recommended for version pinning)
 asdf plugin add starknet-foundry
-asdf install starknet-foundry 0.56.0
-asdf global starknet-foundry 0.56.0
+asdf install starknet-foundry 0.57.0
+asdf global starknet-foundry 0.57.0
 ```
 
 ### .tool-versions
 
 Pin versions for reproducible builds:
 
 ```text
-scarb 2.15.1
-starknet-foundry 0.56.0
+scarb 2.16.1
+starknet-foundry 0.57.0
 ```
 
-> **Note:** Starknet Foundry 0.56.0 requires Scarb >= 2.12.0. Check [github.com/foundry-rs/starknet-foundry/releases](https://github.com/foundry-rs/starknet-foundry/releases) for the latest.
+> **Note:** Starknet Foundry 0.57.0 requires Scarb >= 2.14.0 (recommended: 2.16.x). Check [github.com/foundry-rs/starknet-foundry/releases](https://github.com/foundry-rs/starknet-foundry/releases) for the latest.
 
 ## Build
 
@@ -248,7 +253,7 @@ Verify source code on Voyager or Starkscan:
 # https://app.walnut.dev
 ```
 
-> **Note:** In Starknet Foundry 0.56.0+, `sncast verify` supports both Walnut and Voyager backends (for example, `sncast verify --verifier voyager`). Starkscan verification still uses its web UI.
+> **Note:** In Starknet Foundry 0.57.0+, `sncast verify` supports both Walnut and Voyager backends (for example, `sncast verify --verifier voyager`). Starkscan verification still uses its web UI.
 
 ## Upgradeable Contracts
 

evals/contracts/insecure_math_patterns/Scarb.toml

@@ -7,7 +7,7 @@ edition = "2024_07"
 starknet = ">=2.14.0"
 
 [dev-dependencies]
-snforge_std = "0.56.0"
+snforge_std = "0.57.0"
 
 [cairo]
 sierra-replace-ids = true

evals/contracts/insecure_owned_vault/Scarb.toml

@@ -7,7 +7,7 @@ edition = "2024_07"
 starknet = ">=2.14.0"
 
 [dev-dependencies]
-snforge_std = "0.56.0"
+snforge_std = "0.57.0"
 
 [cairo]
 sierra-replace-ids = true

evals/contracts/insecure_upgrade_controller/Scarb.toml

@@ -7,7 +7,7 @@ edition = "2024_07"
 starknet = ">=2.14.0"
 
 [dev-dependencies]
-snforge_std = "0.56.0"
+snforge_std = "0.57.0"
 
 [cairo]
 sierra-replace-ids = true

evals/contracts/secure_math_patterns/Scarb.toml

@@ -7,7 +7,7 @@ edition = "2024_07"
 starknet = ">=2.14.0"
 
 [dev-dependencies]
-snforge_std = "0.56.0"
+snforge_std = "0.57.0"
 
 [cairo]
 sierra-replace-ids = true

evals/contracts/secure_owned_vault/Scarb.toml

@@ -7,7 +7,7 @@ edition = "2024_07"
 starknet = ">=2.14.0"
 
 [dev-dependencies]
-snforge_std = "0.56.0"
+snforge_std = "0.57.0"
 
 [cairo]
 sierra-replace-ids = true

evals/contracts/secure_upgrade_controller/Scarb.toml

@@ -7,7 +7,7 @@ edition = "2024_07"
 starknet = ">=2.14.0"
 
 [dev-dependencies]
-snforge_std = "0.56.0"
+snforge_std = "0.57.0"
 
 [cairo]
 sierra-replace-ids = true