skills

Scaffolds an "AI Operating System" project structure into any project, non-destructively — adds only missing pieces, never removes or overwrites anything that already exists. Creates: CLAUDE.md (memory layer), docs/architecture.md + docs/decisions/ + docs/runbooks/ (documentation), tools/scripts/ and tools/prompts/ (utilities), and .claude/ with two example skills (new-adr, clean-tests), six hooks (guard-secrets, branch-guard, auto-format, typecheck, n+1-guard, audit-log), and a read-only docs-auditor subagent — all wired via .claude/settings.json. Requires only Python 3 and bash; no external dependencies. Use when asked to "init Claude Code project structure", "scaffold the AI-OS layers", "add CLAUDE.md hooks subagents to this project", "set up the Claude Code layers", "initialize ai-os", "add the AI operating system structure", "scaffold this project for Claude Code", or "add skills hooks agents here". Safe to re-run — idempotent. Not for non–Claude-Code agents (it scaffolds Claude Code's .claude/ layer) an

Comparison-shops any product across many online stores, finds the genuinely cheapest option after discounts, surfaces working coupons, and checks whether each seller is safe to buy from — for one product or a whole shopping list, any store, any region. Use this whenever the user wants to buy something online, asks where to buy a product or for the best/cheapest price, compares prices across stores (Noon, Amazon, Amazon.sa, Jarir, extra, Namshi, AliExpress, eBay, …), hunts for discount or promo codes (including first-order and social-media codes), asks whether a store/seller is legit or a scam, or hands over a shopping list to price out. It runs a 4-step pipeline per item — find sellers, rank by effective price (price − coupon + shipping), judge seller safety (Trusted / Mixed / Risky), and find working coupons — then prints a comparison table, a best-buy recommendation, and (for lists) a consolidated cart with a single-store bundle tip. Trigger even when the user does not say "shop-scout": e.g. "is aliexpress

Comprehensive SQLAlchemy 2.0+ async + PostgreSQL patterns — declarative models, relationships, type-safe Mapped[ columns, querying, eager loading, transactions, and Alembic migrations. Use when working with SQLAlchemy; to write a model, declarative model, or ORM model; add a column, mapped_column, or Mapped[ annotation; define a relationship, foreign key, or index on a table; choose selectinload, joinedload, or load_only; configure an async session or call session.execute; fix N+1 queries; do a bulk insert or upsert; use JSONB or a PostgreSQL type; count rows; write a migration model; or write any SQLAlchemy query. Not for SQLAlchemy 1.x, non-async (sync) codebases, or non-PostgreSQL databases (MySQL, SQLite, etc.).

Produces three grounded deliverables for ANY codebase by reading it (source unchanged), written into the project under docs/system-flow/: SYSTEM_FLOW.md (deep technical reference), system-flow.html (jargon-free offline companion for non-technical readers), and system-flow-technical.html (interactive offline reference for engineers: searchable endpoint cards, actor sidebar, sequence diagrams, light/dark toggle). Detects project type first and routes to the right playbook (backend/API, frontend/SPA, full-stack/monorepo, Pulumi, Flux/GitOps, or generic IaC). Use this whenever the user wants to "map the flow", "understand how this project works", "document the system", "draw the request/response flow", "diagram the architecture", "trace how data moves", "explain the request lifecycle", "show what each user/role can do", or "onboard me to this codebase" — across frontend, backend, full-stack, or infrastructure-as-code repositories, even if they don't name these files explicitly. Prefer this skill over ad-hoc explo

Audits and refactors existing test files for quality — removes brittle assertions, fixes implementation coupling (mocking internals), improves test names, eliminates duplication, and enforces behavior-over-implementation testing. Does NOT write new tests (use /tdd for that). Use when asked to "clean up the tests", "improve test quality", "fix brittle tests", "refactor the test suite", "tests keep breaking on refactor", "tests are a mess", or "make the tests better".

Creates a new Architecture Decision Record (ADR) in docs/decisions/. Auto-numbers the file based on the highest existing ADR number. Use when asked to "create an ADR about X", "record the decision to use X", "document the architecture decision for X", "add to the decision log", "write an ADR for X", or "record why we chose X".