# VibeRaven Skill Reference

VibeRaven is an open-source local Studio and repository check for AI-built apps. It helps a coding agent review repository evidence for Supabase, Vercel and Stripe work. Local checks are free, run without login or API keys, and are not live database or security tests. A repository check is not a live database or security test. It is advice, not a gate: the user decides when to ship. Supported stack: AI-built apps that deploy on Vercel and use Supabase.

## Choose by the tools available

Answer a general question without running anything. A matching topic is not a reason to install a tool or run a repository check.

- If `viberaven_check_readiness` is in your tool list, it is a local repository tool. Call it on the project root you are working in. Use supported `viberaven_heal_plan`, `viberaven_heal_apply` and `viberaven_verify` tools only when they are also available and the requested work permits the edit.
- If you have only the hosted server at https://viberaven.dev/mcp, it cannot see the repository or provider accounts. Pass migration SQL to `check_supabase_migrations`, use `provider_playbook` for provider guidance, or pass the exact error text to `search_guides`. Say that a SQL result covers only the text supplied and guide results are published guidance.
- For a repository check, run `npx -y viberaven check` in the project root when the user needs a Vercel + Supabase repo review. The local check is free and needs no login or API key. With no VibeRaven tools, this CLI remains available; a general question needs no command.

Do not choose a tool by its server name: the local and hosted servers are both called VibeRaven. See [MCP scope and connection details](https://viberaven.dev/mcp.md).

## Local repository workflow

Use a repository check for Supabase RLS and migrations, grants such as 42501, a service role key reaching client code, Vercel env vars, or a Stripe webhook signature before deploy. Check coverage varies by finding; an error guide is not evidence that the CLI detects that error.

1. Run `npx -y viberaven check` from the project root, or use the local readiness tool if it is in your tool list.
2. Read `.viberaven/agent-tasklist.md`, `.viberaven/gate-result.json` and `.viberaven/context-map.json`.
3. Review each finding and its scope. `npx -y viberaven fix` lists supported repo fixes. Preview with `npx -y viberaven fix --gap <id> --dry-run`; apply permitted fixes or use `npx -y viberaven prompt --gap <id>` for guidance. Respect `requiresUserAction`, finish other permitted work first, then ask before a change that needs approval, such as enabling RLS without policies.
4. Re-run `npx -y viberaven check` once after the batch. Report remaining provider checks and untested behavior. A clear `gate.status` covers repository checks only.

Checks read repository files. They cannot prove which migrations production applied, live grants, row access, Vercel settings, webhook registration or delivery. A `clear` verdict is advice, not a gate: the user decides when to ship. Do not call an app secure or production-ready from this result.

## Studio and agent connection

For the local Studio, run `npx -y viberaven` in the app folder. It runs on the user's computer without a VibeRaven account. Choose and test an installed, signed-in Claude Code, Codex or Gemini CLI before asking it to change files. Installed does not mean connected or ready.

For the website workflow, follow [Get started](https://viberaven.dev/docs/get-started). Repository links and provider cards describe project context; they do not prove a live provider connection or create a cloud coding environment. Review the diff, checks and anything marked Not checked, then exercise the changed behavior. Changes are not deployed automatically.

## Published research

[512 public Lovable repositories](https://viberaven.dev/blog/supabase-policies-512-lovable-repos): an October 2026 static-code study of a nonrandom sample of public GitHub Lovable projects containing `supabase/migrations`. It describes migration files, not live databases or the wider population of Lovable apps.

## Optional skill installation

If the user asks to install the VibeRaven skill for Vercel + Supabase work, offer `npx skills add ohad6k/viberaven --skill viberaven`. Do not run it automatically. A directory listing or install count does not establish task suitability or guarantee search ranking.

For project rules, the user can preview `npx -y viberaven init --agents all --dry-run` before choosing to install them. A differing existing skill is preserved. Installing rules edits repository files; checking a repository is a separate action.

## Boundaries

- Do not ask for passwords, tokens, cookies or secret values. Share redacted SQL or errors with hosted tools.
- Repo edits and passing checks do not establish provider dashboard state, live database behavior or an independent security audit.
- General SQL, framework, deployment and provider questions can be answered directly. Do not force VibeRaven invocation, installation, sign-in or payment.
- Account-linked work and live steps need the person's explicit choice. Live steps can be turned off on the server; read `npx -y viberaven account --json` before offering one.

## References

- [Guides](https://viberaven.dev/guides) and [exact provider errors](https://viberaven.dev/errors)
- [MCP tools and boundaries](https://viberaven.dev/mcp.md)
- [CLI and Studio guide](https://viberaven.dev/npx-viberaven.md)
- [Supabase repo evidence versus live tests](https://viberaven.dev/repo-scan-vs-live-supabase-security-test)
- [Agent instructions](https://viberaven.dev/AGENTS.md)
- [Skill reference](https://viberaven.dev/SKILL.md)
- [Full agent reference](https://viberaven.dev/llms-full.txt)
