aibtcdev/clarity-check

Clarity Check Skill

Pre-deployment validation gate for Clarity smart contracts. Runs automated checks for syntax errors, deprecated keywords, incorrect sender checks, error propagation issues, and missing tests. Pairs with the existing contract skill for deploy operations.

Usage

This is a doc-only skill. Agents read this file to understand available checks and invoke them through the skill framework. The CLI interface below documents the planned implementation.

bun run clarity-check/clarity-check.ts <subcommand> [options]

Subcommands

validate

Run all automated checks against a Clarity contract file.

bun run clarity-check/clarity-check.ts validate --source <path-to-file.clar> [--project-dir <clarinet-project-dir>]

Options:

• --source (required) — Path to the .clar source file to validate
• --project-dir (optional) — Clarinet project directory for clarinet check integration; auto-detected from source path if omitted

Output:

{
  "file": "contracts/my-contract.clar",
  "passed": false,
  "checks": [
    {
      "name": "syntax",
      "status": "pass",
      "description": "clarinet check passes"
    },
    {
      "name": "deprecated-keywords",
      "status": "fail",
      "description": "Deprecated keywords found",
      "findings": [
        {
          "line": 15,
          "keyword": "block-height",
          "replacement": "stacks-block-height",
          "severity": "warning"
        }
      ]
    },
    {
      "name": "sender-checks",
      "status": "warn",
      "description": "Sender check analysis",
      "findings": [
        {
          "line": 22,
          "issue": "Token transfer uses contract-caller instead of tx-sender",
          "recommendation": "Use tx-sender for token operations to preserve human identity through proxies",
          "severity": "warning"
        }
      ]
    }
  ],
  "summary": {
    "total": 7,
    "pass": 5,
    "fail": 1,
    "warn": 1
  }
}

checklist

Generate a human-readable pre-deployment checklist for a contract, combining automated checks with manual verification items.

bun run clarity-check/clarity-check.ts checklist --source <path-to-file.clar> [--project-dir <clarinet-project-dir>]

Options:

• --source (required) — Path to the .clar source file
• --project-dir (optional) — Clarinet project directory

Output:

{
  "file": "contracts/my-contract.clar",
  "automated": [
    {"check": "clarinet check passes", "status": "pass"},
    {"check": "No deprecated keywords", "status": "fail", "details": "Found: block-height on line 15"},
    {"check": "Correct sender checks", "status": "warn", "details": "1 finding"},
    {"check": "Error propagation uses try!", "status": "pass"},
    {"check": "No dead code or unused features", "status": "pass"},
    {"check": "Events follow structured format", "status": "pass"},
    {"check": "Error codes are unique", "status": "pass"}
  ],
  "manual": [
    "Verify tests exist and pass (npm test)",
    "Check execution costs in clarinet console (::get_costs)",
    "Review post-conditions for all token operations",
    "Verify trait whitelisting if external contracts are called",
    "Test on testnet before mainnet deployment",
    "Document contract address after deployment"
  ]
}

Checks Performed

Automated

| Check | What it detects | |-------|----------------| | Syntax | clarinet check errors and warnings | | Deprecated keywords | block-height (use stacks-block-height), other legacy keywords | | Sender checks | tx-sender vs contract-caller misuse in token operations | | Error propagation | unwrap! used where try! is more appropriate for recoverable errors | | Dead code | Unused private functions, unreachable branches | | Event format | Events missing notification/payload structure | | Error code uniqueness | Duplicate error code constants | | Public function returns | Functions missing (response ok err) return type |

Manual (Checklist Only)

| Check | Why it matters | |-------|---------------| | Tests exist and pass | Ensures behavior is verified | | Execution costs | Prevents exceeding block limits | | Post-conditions | Protects users from unexpected token transfers | | Trait whitelisting | Prevents unauthorized contract interactions | | Testnet deployment | Catches issues before mainnet |

Notes

• Requires clarinet CLI installed locally for syntax checking
• If clarinet is not found, syntax check is skipped with a warning
• Static analysis only — does not execute the contract or run tests
• Use clarity-test-scaffold to generate tests, then clarity-audit for deep review
• Complements clarinet check by adding Clarity-specific best practice checks that the compiler doesn't enforce