insforge-debug skill (InsForge): diagnose errors in an InsForge project

InsForge's own skill that has a coding agent diagnose InsForge errors, slow queries and failed deploys using logs, metrics and advisor scans.

Installs: 58.7K; on skills.sh
Stars: 47; on GitHub
Files: 10; besides SKILL.md
Updated: Oct 2026; last repo commit

insforge-debug makes your coding agent work through an InsForge problem step by step: read the error, pick the right log source, then check database health, advisor findings, RLS policies and deploy state. It has 15 recipes for symptoms such as RLS denials, slow queries, gateway timeouts and failed deploys, plus a pre-launch audit.

Most steps only read data from your project through the InsForge CLI. A few recipes send a description to InsForge's debug agent or run an instance upgrade, which changes your bill. Needs an InsForge project and, for audits, a platform login.

Good for

Developers building an app on InsForge's Postgres-based backend
Developers who hit a 4xx or 5xx, an RLS denial or a failed function deploy
Teams doing a security, performance or pre-launch check of an InsForge project

Install insforge-debug

Claude Code

Copy this prompt.

Install the insforge-debug skill in Claude Code. Run this command:

/plugin marketplace add InsForge/insforge-skills
/plugin install insforge@insforge

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both. The skills CLI asks which skills to take: pick insforge-debug. SKILL.md does not need the other three to run. The plugin route installs all 4. The skills run the InsForge CLI with npx, which needs Node.js 18 or newer, and you need an InsForge account and project. The README lists /install-skills under Claude Code. It is not a documented Claude Code built-in and we have not confirmed it works, so prefer the plugin or the skills CLI.

Built from the package data we hold. Not yet tested by us. Source.

What's in the skill

When it loads

Use when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denial, realtime channel issues, slow query on one endpoint, edge function or Vercel deploy failure), proactive audits (security/RLS review, performance/index review, system health check, pre-launch readiness), or when the user has an error but doesn't know where to start.

Sections in SKILL.md

Fastest Path: AI-Assisted Triage
Debug Primitives
Symptom Recipes
Recipe: SDK returned { data: null, error: { code, message } }
Recipe: HTTP 4xx/5xx response on a specific request
Recipe: RLS access issue (403 on write, or empty result on read)
Recipe: Login fails / OAuth callback errors / token expired
Recipe: Edge function runtime error / timeout
Recipe: functions deploy failed
Recipe: deployments deploy failed (Vercel)
Recipe: Single slow query / one endpoint slow
Recipe: "Memory is at ~80% but nothing is slow"
Recipe: All responses slow / high CPU/memory (active incident)
Recipe: Realtime channel won't connect / messages missing
Recipe: 429 rate limit
Recipe: Gateway timeout (502 / 503 / 504) on a specific URL

Key facts

Author: InsForge (vendor's own repo, README and plugin manifests)
License: Apache 2.0 (LICENSE file, README, SKILL.md and both plugin manifests agree)
Installs on skills.sh: 58,681 as of 2026-11-02
GitHub stars: 47 for the whole insforge-skills repo, 2026-11-02
What is inside: 11 files including SKILL.md: 9 reference guides, one per debug source, plus agents/openai.yaml. It bundles no scripts.
Last change to this skill: 2026-08-10
Part of: The insforge plugin (4 skills) in the insforge marketplace
Needs: Node.js 18 or newer for @insforge/cli, run through npx, and an InsForge project

What it includes

Hands a concrete error to InsForge's debug agent
npx -y @insforge/cli diagnose --ai "<issue>". SKILL.md says it returns suggestions, so check them against the other sources before acting.
Try: “My InsForge function times out. Find out why.”
Runs code · AI-assisted triage
Event streams from 5 backend sources
logs <source> reads insforge.logs, postgREST.logs, postgres.logs, function.logs or function-deploy.logs. diagnose logs aggregates across them.
Runs code · Logs
CPU, memory, disk and network over 1h to 7d
diagnose metrics --range 1h, 6h, 24h or 7d. A recipe explains that steady high memory on a dedicated Postgres instance is normal.
Runs code · Metrics
Seven named Postgres checks
diagnose db with connections, slow-queries, bloat, size, index-usage, locks and cache-hit.
Runs code · DB health
Security, performance and health findings
diagnose advisor --json lists issues with ruleId, affectedObject and recommendation. It needs a platform login.
Runs code · Advisor
Active RLS rules and a dump of backend state
db policies lists policies; metadata --json dumps auth config, tables, buckets, functions, AI models and realtime channels.
Runs code · Policies and metadata
Route an SDK or HTTP error to the right log; read deploy history
Maps SDK error codes and HTTP statuses to log sources, and reads frontend deployments and function deploy logs.
Runs code · Error objects and deploy state
15 step-by-step recipes for known symptoms and audits
Covers SDK errors, HTTP errors, RLS access, login failures, function errors, failed deploys, slow queries, memory, active incidents, realtime, 429s, gateway timeouts, a pre-launch audit and not knowing where to start.
Runs code · Symptom recipes
Checks for out-of-memory crashes, then resizes the instance
diagnose incident gives a verdict. If it points to out-of-memory, the fix is projects upgrade-instance, which restarts the project and changes the bill; SKILL.md says to get your go-ahead first.
Runs code · Gateway timeout recipe

From the official docs

Permissions

Medium risk

Most of this skill reads logs and settings from your project, but one recipe runs an instance upgrade that restarts the project and changes the bill. Approve that step yourself.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

One recipe resizes the instance
The gateway-timeout recipe ends in projects upgrade-instance, which restarts the project and changes the bill. SKILL.md says to get your go-ahead and then run it with --yes; decline unless you want it. github.com
diagnose --ai sends your issue text to InsForge
The text goes to InsForge's debug agent. Leave secrets and user data out of the description, and verify its suggestions. github.com
The service-role query reads real rows
The RLS recipe runs db query as service role, which bypasses row-level security. Check the SQL before you approve it. github.com
Bug reports go to InsForge
When the root cause is InsForge itself, SKILL.md tells the agent to report it with npx -y @insforge/cli feedback while the evidence is in hand. It needs no login, and SKILL.md says common PII patterns are redacted locally but pattern-based, so keep user data out of the report text. Say no if you do not want a report sent. github.com
The InsForge CLI sends usage events to PostHog
The CLI source says each command emits one PostHog event with non-sensitive properties, and uses an anonymous ID when no project is linked. The skill runs the CLI through npx, so those events come with it. github.com
The plugin route installs all 4 skills
The Claude and Codex plugin manifests cover the whole skills folder, which holds 4 skills, and the git tree has no hooks or MCP config. The Codex marketplace file sets authentication to ON_INSTALL. github.com
agents/openai.yaml holds interface settings
Each skill folder includes an agents/openai.yaml with a display name, short description, brand color and a default prompt. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Talks to	api.insforge.dev and your InsForge project URL. InsForge's debug agent (diagnose --ai)
Sign-in and keys	Some commands need a platform login, and the audit recipe is not available when the project is linked with an API key.
Scopes	Runs npx -y @insforge/cli diagnose, logs, metadata, db policies and deployments commands Runs db query as service role to check whether rows exist (RLS recipe) Sends an issue description to InsForge's debug agent with diagnose --ai Can run projects upgrade-instance, with --yes after your go-ahead Can send a bug report to InsForge with the feedback command

Questions

What does the insforge-debug skill do?

It guides your coding agent through diagnosing an InsForge problem: it reads the error, checks logs, metrics, database health, advisor findings, RLS policies and deploy state, then narrows down the cause.

How do I install insforge-debug?

Use the install box at the top of this page. insforge-debug does not need the other InsForge skills to run, so with the skills CLI you can pick just it; the plugin route installs all 4. You also need Node.js 18 or newer and an InsForge project.

Does insforge-debug fix problems for me?

Partly. The README says it does not give fix suggestions, but SKILL.md says the AI-assisted step returns suggestions and some recipes end in a fix, such as an instance upgrade. Treat what the sources show as the truth, and the suggestions as hints.

Does it need a login or API key?

It needs access to your InsForge project through the CLI. The pre-launch audit needs a platform login and does not work when the project is linked with an API key.

Is insforge-debug safe?

Read each command before you approve it. Most steps read logs and settings through the CLI, but SKILL.md also has the agent run SQL as service role, send your issue text to InsForge's debug agent, run an instance upgrade in one recipe, and file bug reports with the feedback command.

Is this the official InsForge skill?

Yes. It is in InsForge's own insforge-skills repo, and the plugin manifests name InsForge as author.

insforge-debug or insforge-cli?

insforge-debug is for finding why something fails: it is a set of diagnostic recipes. insforge-cli is the full command reference for managing projects, and it can also change and delete things. The debug recipes call the same CLI.

Information

updated Nov 2, 2026

Repository: insforge/insforge-skills
Folder: skills/insforge-debug

insforge/insforge-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

marketplace.json · github.com
README.md · github.com
README.md · github.com
plugin.json · github.com
SKILL.md · github.com
command-telemetry.ts · github.com