Skip to content

Add read-only db-debug agent skill wrapping scripts/db-debug.sh#3957

Open
TaprootFreak wants to merge 4 commits into
developfrom
feat/db-debug-skill
Open

Add read-only db-debug agent skill wrapping scripts/db-debug.sh#3957
TaprootFreak wants to merge 4 commits into
developfrom
feat/db-debug-skill

Conversation

@TaprootFreak

@TaprootFreak TaprootFreak commented Jun 22, 2026

Copy link
Copy Markdown
Collaborator

What

Adds a read-only db-debug agent skill that wraps the existing scripts/db-debug.sh CLI, so any
agent (and any teammate) gets the documented query modes and database schema without re-explaining
them each session. The script itself is unchanged and stays usable directly on the shell.

The skill follows the open Agent Skills SKILL.md standard and is
tool-neutral: frontmatter is limited to the portable core (name, description), and the body
uses repository-relative paths only.

It also documents three companion balance-forensics scripts (compare-balance-logs.sh,
inspect-asset-balance.sh, sum-asset-balances.sh) as part of the same skill.

Why fold them in rather than make a second skill: all three use the byte-identical
DEBUG_ADDRESS/DEBUG_SIGNATURE/.env auth and the same /gs/debug endpoint as db-debug.sh,
and operate on the same log / FinancialDataLog balancesTotal snapshot structure that
reference.md already documents. A separate "balance-forensics" skill would split the same
interpretation rules across two places; documenting them as modes of db-debug keeps the knowledge
in one location. This directly serves the recurring total-balance-step investigations.

Why this location

.claude/ and CLAUDE.md are git-ignored in this repo, so shared, version-controlled skills live
in a neutral top-level skills/ directory instead. Each developer points their own agent at it
(per-developer agent config stays local). This is documented in a new Agent skills section in
CONTRIBUTING.md.

Files

  • skills/db-debug/SKILL.md — modes, invocation, and the liquidity_balance snapshot query
  • skills/db-debug/reference.md/gs/debug semantics, FinancialDataLog / balancesTotal, and
    the liquidity_balance schema (loaded on demand)
  • CONTRIBUTING.md — new Agent skills section

Notes

  • Read-only only: the skill documents SELECT-only usage; /gs/debug already enforces this
    server-side through SQL AST validation.
  • No secrets committed — DEBUG credentials stay in each developer's local .env.
  • An optional pre-execution guard that blocks write statements is left as a possible follow-up
    (defense in depth).

PR completeness

  • Migration: N/A (no entity/column changes)
  • Environment / Infrastructure: N/A
  • Service updates: N/A (no DTO/interface changes)
  • Frontend synchronization: N/A (no API contract changes)

Closes #3955. Related: #3956 (db-debug.sh efficiency improvements).

@TaprootFreak TaprootFreak marked this pull request as ready for review June 22, 2026 15:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Skill dfx-debug wrappt db-debug.sh für Claude Code (statt MCP-Server)

1 participant