NpgsqlRest

Appearance

Comments

Claude Code Skill ​

NpgsqlRest ships an official Claude Code skill that teaches the agent how to build with NpgsqlRest: both endpoint sources (database routines and .sql files), the full annotation vocabulary, configuration, HTTP custom types, proxy, caching, auth, SSE, MCP, client code generation, the SQL test runner, and watch mode.

Without it, an AI assistant guesses annotation names and configuration keys from training data — often from an older version, or just wrong. With it, Claude works from the exact reference for the current release and knows to verify against your installed binary.

What's in the Skill ​

A skill is a folder of instructions and reference files that Claude Code loads on demand. This one lives in the main repository at .claude/skills/npgsqlrest/ and contains three files:

FileWhat it is
SKILL.mdThe working knowledge: mental model, both endpoint sources, an annotation cheat-sheet, HTTP custom types, proxy, auth patterns, caching, testing, and the common gotchas
annotations-reference.mdEvery comment annotation with syntax, aliases, and description
configuration-reference.jsoncThe complete appsettings.json with every option and inline comments

The two reference files are generated from npgsqlrest --annotations and npgsqlrest --config, so they match the release they ship with.

Installation ​

The skill can be installed per project (committed to the repository, so the whole team gets it) or per user (available in every project on your machine). Claude Code discovers skills in both places: the project's .claude/skills/ folder and your personal ~/.claude/skills/.

Per Project ​

From the project root:

bash
mkdir -p .claude/skills/npgsqlrest
for f in SKILL.md annotations-reference.md configuration-reference.jsonc; do
  curl -fsSL "https://raw.githubusercontent.com/NpgsqlRest/NpgsqlRest/master/.claude/skills/npgsqlrest/$f" \
    -o ".claude/skills/npgsqlrest/$f"
done
powershell
New-Item -ItemType Directory -Force -Path .claude\skills\npgsqlrest | Out-Null
foreach ($f in 'SKILL.md', 'annotations-reference.md', 'configuration-reference.jsonc') {
  Invoke-WebRequest "https://raw.githubusercontent.com/NpgsqlRest/NpgsqlRest/master/.claude/skills/npgsqlrest/$f" `
    -OutFile ".claude\skills\npgsqlrest\$f"
}

Commit the three files — everyone working on the repository, including any CI or cloud agent, gets the same skill automatically.

Per User ​

bash
mkdir -p "$HOME/.claude/skills/npgsqlrest"
for f in SKILL.md annotations-reference.md configuration-reference.jsonc; do
  curl -fsSL "https://raw.githubusercontent.com/NpgsqlRest/NpgsqlRest/master/.claude/skills/npgsqlrest/$f" \
    -o "$HOME/.claude/skills/npgsqlrest/$f"
done
powershell
$dir = "$env:USERPROFILE\.claude\skills\npgsqlrest"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
foreach ($f in 'SKILL.md', 'annotations-reference.md', 'configuration-reference.jsonc') {
  Invoke-WebRequest "https://raw.githubusercontent.com/NpgsqlRest/NpgsqlRest/master/.claude/skills/npgsqlrest/$f" `
    -OutFile "$dir\$f"
}

The bash variant also works in WSL and Git Bash on Windows.

How It Activates ​

There is nothing to configure. Claude Code matches each request against the skill's description and loads it automatically when the work touches NpgsqlRest: writing endpoint SQL or annotations, editing appsettings.json, generating clients, or running and troubleshooting the npgsqlrest server. You can also invoke it explicitly by typing /npgsqlrest in the prompt, or just asking Claude to use it.

Cookbook ​

Once installed, describe endpoints instead of writing them. Some prompts to steal:

Building:

  • "Add a GET /api/top-customers endpoint: top 20 by revenue, managers only, cached 5 minutes keyed on the region parameter."
  • "Create a SQL file endpoint returning monthly order totals between two date parameters."
  • "Expose this function as an MCP tool with no public HTTP route."
  • "Add an HTTP custom type that calls the weather API, with the key from an allowlisted environment variable."

Debugging:

  • "My @cached endpoint returns the same data for every user — why?" (the skill knows the bare-@cached gotcha)
  • "This endpoint returns 404 — check how the URL path is derived from the function name."
  • "Startup fails describing one of my .sql files — find and fix it."

Configuration:

  • "Set up cookie auth with a login function and map user claims to function parameters."
  • "Enable the TypeScript client with React Query hooks, but only in the development config."

Testing and verifying — the skill tells Claude to use the binary itself rather than guess: npgsqlrest --validate checks connectivity and that all endpoints build, --test runs SQL test files, --annotations and --config are the authoritative reference for the installed version, and debug logging confirms each annotation parsed as intended.

Keeping It Current ​

The skill files are updated with each release. When you upgrade NpgsqlRest, re-run the install command above to pull the matching skill. If the versions ever drift, no harm done — the skill instructs Claude to trust the output of your installed binary over the bundled references.

Comments