feat: bootstrap production-grade starknet-skills foundation

.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "starknet-skills",
+  "version": "0.1.0",
+  "description": "Cairo/Starknet reasoning and audit-quality skills",
+  "author": "keep-starknet-strange"
+}

.gitignore

@@ -0,0 +1,19 @@
+.DS_Store
+*.swp
+*.swo
+
+# Local tooling
+.venv/
+.env
+.env.*
+!.env.example
+
+# Python cache
+__pycache__/
+*.pyc
+
+# Local audit ingest artifacts
+datasets/audits/raw/*
+!datasets/audits/raw/.gitkeep
+datasets/audits/extracted/*
+!datasets/audits/extracted/.gitkeep

CLAUDE.md

@@ -0,0 +1,19 @@
+# Repo Context
+
+This repository is for reasoning-grade Cairo/Starknet skills.
+
+## Hard Boundary
+
+- Keep operational SDK/protocol usage content out of this repo.
+- Keep this repo focused on correctness, security patterns, and evaluation-backed guidance.
+
+## Editing Rules
+
+- Keep root skill modules concise.
+- Move large details to `references/` and `workflows/`.
+- Do not expand scope without accompanying eval updates.
+
+## Evaluation Rules
+
+- Detection quality changes must add or update evaluation cases.
+- Prefer held-out regressions from `datasets/audits/`.

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+## Quality Bar
+
+Every change must satisfy both tests:
+
+1. Would a strong stock model still get this wrong without this content?
+2. Does this change improve deterministic quality outcomes (fewer misses, fewer false positives, better remediation quality)?
+
+If both answers are not yes, do not add the content.
+
+## Required Structure in Skill Files
+
+Each `SKILL.md` must include:
+
+- `When to Use`
+- `When NOT to Use`
+
+Security/audit skills must also include:
+
+- `Rationalizations to Reject`
+
+Keep entry skills short and link one level deep to `references/` and `workflows/`.
+
+## Evaluation-Driven Changes
+
+Skill changes that affect detection or remediation quality must include one of:
+
+- New/updated case in `evals/cases/`
+- Updated benchmark scorecard in `evals/scorecards/`
+
+No merge without green quality gates:
+
+- formatting/build/tests
+- static analysis where applicable
+- evaluator pass threshold
+
+## Audit Data Handling
+
+When ingesting external audits into `datasets/audits/`:
+
+- redact confidential or client-identifying material
+- preserve technical root cause and exploitability detail
+- tag confidence and provenance for every finding

README.md

@@ -1 +1,37 @@
 # starknet-skills
+
+Production-grade skills for high-quality Cairo and Starknet security engineering.
+
+This repository is focused on reasoning quality, audit rigor, and deterministic quality gates.
+Operational SDK and protocol execution playbooks belong in `starknet-agentic` / `starkzap`.
+
+## Scope Boundary
+
+- In scope: Cairo correctness, security review patterns, Starknet architectural facts, testing and hardening workflows.
+- Out of scope: runtime tool execution guides (MCP tool usage, SDK call recipes, protocol operation runbooks).
+
+## Modules
+
+- `cairo-auditor/` — flagship workflow skill for Cairo security review.
+- `cairo-contract-authoring/` — contract structure and implementation patterns.
+- `cairo-testing/` — Starknet Foundry testing and fuzzing workflows.
+- `cairo-optimization/` — performance and low-level Cairo optimization rules.
+- `cairo-toolchain/` — build/declare/deploy/verification and release operations.
+- `account-abstraction/` — Starknet account abstraction and account-security semantics.
+- `starknet-network-facts/` — network-level constraints and chain behavior guardrails.
+- `openzeppelin-cairo/` — OpenZeppelin Cairo composition and hardening patterns.
+
+## Data + Evals
+
+- `datasets/` stores the full audit-to-skills pipeline (`ingest -> segment -> normalize -> distill`).
+- `evals/` stores held-out evaluation cases and scorecards.
+
+Do not merge skill changes without updating or passing the corresponding evaluation set.
+
+## Initial Source Imports
+
+v0.1 seeds several modules from existing `starknet-agentic` skills and then constrains them to this repo boundary.
+
+## License
+
+MIT

SKILL.md

@@ -0,0 +1,25 @@
+---
+name: starknet-skills
+description: Router skill for Cairo/Starknet high-quality coding and auditing. Use this first to pick a focused module.
+---
+
+# Starknet Skills Router
+
+Use this file to choose the smallest relevant module.
+
+## Start Here
+
+- For contract security review: `cairo-auditor/SKILL.md`
+- For writing new contracts: `cairo-contract-authoring/SKILL.md`
+- For testing and fuzzing: `cairo-testing/SKILL.md`
+- For gas/perf optimization: `cairo-optimization/SKILL.md`
+- For build/declare/deploy/release operations: `cairo-toolchain/SKILL.md`
+- For account abstraction rules and risks: `account-abstraction/SKILL.md`
+- For Starknet network constraints: `starknet-network-facts/SKILL.md`
+- For OpenZeppelin Cairo usage and footguns: `openzeppelin-cairo/SKILL.md`
+
+## Routing Policy
+
+- Prefer one module first.
+- Add a second module only when blocked.
+- Keep context narrow and evidence-based.

account-abstraction/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: account-abstraction
+description: Starknet account abstraction correctness and security guidance for validate/execute paths, nonces, signatures, and session policies.
+---
+
+# Account Abstraction
+
+## When to Use
+
+- Reviewing account contract validation and execution paths.
+- Designing session-key policy boundaries.
+- Validating nonce and signature semantics.
+
+## When NOT to Use
+
+- General contract authoring not involving account semantics.
+
+## Core Focus
+
+- `__validate__` constraints and DoS resistance.
+- `__execute__` policy enforcement correctness.
+- Replay protection and domain separation.
+- Privileged selector and self-call protection.

account-abstraction/references/README.md

@@ -0,0 +1,3 @@
+# References
+
+Account abstraction threat models, selector policy examples, and replay-protection references.

cairo-auditor/README.md

@@ -0,0 +1,11 @@
+# cairo-auditor
+
+Flagship security workflow module for Cairo/Starknet auditing.
+
+- `SKILL.md` contains orchestration policy and output contract.
+- `references/vulnerability-db/` stores generalized vulnerability patterns.
+- `datasets/normalized/findings/` is the canonical store for normalized findings.
+- `references/audit-findings/` is legacy/imported reference material.
+- `workflows/` contains runbooks for default/deep/targeted operation.
+- `agents/` contains agent-specific instructions for parallel scans.
+- `scripts/` contains extraction and normalization utilities.

cairo-auditor/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: cairo-auditor
+description: Security audit workflow for Cairo/Starknet contracts. Use for pre-merge and pre-release vulnerability discovery, triage, and remediation planning.
+allowed-tools: [Bash, Read, Glob, Grep, Task]
+---
+
+# Cairo Auditor
+
+Workflow skill for systematic Cairo contract security review.
+
+## When to Use
+
+- Reviewing contract changes before merge.
+- Performing release-gate security checks.
+- Triaging suspicious Cairo/Starknet patterns from code review or incidents.
+
+## When NOT to Use
+
+- Writing new contract features from scratch.
+- Deployment-only tasks.
+- SDK or protocol operation guides.
+
+## Rationalizations to Reject
+
+- "Tests pass so this is safe."
+- "This pattern is standard in EVM so it is safe in Cairo."
+- "The edge case is impossible in production."
+- "We can skip replay/domain checks because signatures are temporary."
+
+## Modes
+
+- `default`: whole-package review using scoped file discovery.
+- `deep`: default + adversarial reasoning pass + strict false-positive gate.
+- `targeted`: explicit file-path review for fast PR iteration.
+
+## Workflow
+
+1. Discover in-scope Cairo files.
+2. Run vectorized scans using vulnerability patterns in `references/vulnerability-db/`.
+3. Correlate with historical findings in `../datasets/normalized/findings/`.
+4. Prefer distilled classes from `../datasets/distilled/vuln-cards/` when available.
+5. Merge and deduplicate findings by root cause.
+6. Run false-positive verification gate.
+7. Emit prioritized report with remediation guidance and test requirements.
+
+## Reporting Contract
+
+Each finding must include:
+
+- `finding_id`
+- `source_audit_id`
+- `project`
+- `auditor`
+- `date`
+- `severity_original`
+- `severity_normalized`
+- `status`
+- `contracts`
+- `functions`
+- `root_cause`
+- `exploit_path`
+- `trigger_condition`
+- `vulnerable_snippet`
+- `fixed_snippet`
+- `recommendation`
+- `test_that_catches_it`
+- `false_positive_lookalikes`
+- `tags`
+- `source_pages`
+- `confidence`
+- `evidence_strength`
+- `reproducibility`
+- `notes`
+
+## Evidence Sources
+
+- canonical patterns: `references/vulnerability-db/`
+- audit-derived records: `../datasets/normalized/findings/`
+- distilled security cards: `../datasets/distilled/vuln-cards/`
+- evaluator regressions: `../evals/cases/`
+
+## Output Rule
+
+Only report actionable findings with confidence >= medium unless `deep` mode is requested.

cairo-auditor/VERSION

@@ -0,0 +1 @@
+0.1.0

cairo-auditor/agents/adversarial.md

@@ -0,0 +1,4 @@
+# Adversarial Agent
+
+Construct concrete exploit paths for candidate findings.
+Reject findings that cannot produce a realistic attack path under stated assumptions.

cairo-auditor/agents/vector-scan.md

@@ -0,0 +1,4 @@
+# Vector Scan Agent
+
+Scan assigned files for pattern matches against `../references/vulnerability-db/`.
+Do not report stylistic issues. Report only security-relevant findings.

cairo-auditor/references/audit-findings/README.md

@@ -0,0 +1,13 @@
+# Audit Findings Corpus
+
+This directory stores imported/legacy notes.
+
+Canonical normalized findings now live under:
+
+- `../../../datasets/normalized/findings/`
+
+Canonical distilled cards now live under:
+
+- `../../../datasets/distilled/vuln-cards/`
+
+Do not store confidential client identifiers in either location.