sn-api-example — The Skills Way

No server, no SDK, no CLI: an AI agent + raw REST + a great AGENTS.md. This repo gives an agent direct access to any ServiceNow instance through the Table API (/api/now/table/...) — full CRUD, encoded queries, dot-walking, pagination — and the guardrails to do it safely.

Part of the "AI Engineer 3 Ways" talk:

Way	What the AI gets	Repo
The MCP Way	Curated, typed, documented tools	sn-mcp-example
The Skills Way	Raw REST + a great AGENTS.md + skill	this repo
The CLI Way	A lifecycle-driven CLI (sndev)	sndev.io

Why this works

The Table API is small — six methods, one URL shape, any table — and this repo packages the two things an agent actually needs to wield it:

• AGENTS.md — the standing brief: workflow (discover → query → act → verify), safety rules, and the gotchas that would otherwise cost debugging rounds (display values vs sys_ids, silently-invalid query fields, dotenv quoting).
• .agents/skills/servicenow-table-api/ — a progressive-disclosure skill: the agent loads SKILL.md on demand for the workflow and cURL patterns, and dips into references/ only for the endpoint table or encoded-query syntax.
• .dev.vars — gitignored dotenv with instance + basic-auth credentials. The agent sources it; the values never enter git or the conversation.

The bet: a CRUD API this regular plus a well-briefed agent ≈ the MCP experience, with zero deployed infrastructure. Compare it to sn-mcp-example on the same instance and judge for yourself.

Quick start

cp .dev.vars.example .dev.vars      # fill in your instance + credentials

Open your agent in this directory (pi, Claude Code, Codex — anything that reads AGENTS.md and loads .agents/skills/) and just ask:

• "How many active P1 incidents do we have?" → encoded query + count
• "Create a high-urgency incident for the VPN outage and assign it to Network" → discover sys_user_group sys_id, POST, verify
• "Close INC0010002 with work notes" → PATCH + confirm

Credential gotcha (read this if every call 401s)

.dev.vars is parsed dotenv-style and unquoted values are silently truncated at the first # ($ also gets variable-expanded). Generated ServiceNow passwords usually contain #, $, or = — so single-quote every value:

SN_INSTANCE='https://dev000000.service-now.com'
SN_USERNAME='admin'
SN_PASSWORD='p@ss w1th #$pecial chars'

Security notes

• Use a dedicated service account, not your personal admin login. Admin is fine for local dev; for anything shared, go least-privileged — the Table API enforces the credential's ACLs per table, so a scoped role scopes the agent.
• .dev.vars is gitignored; .dev.vars.example is the only credential-shaped file in git. Never echo the real values into scripts, logs, or commits.
• DELETE is irreversible — the skill makes the agent confirm table + sys_id with you first. Keep it that way.

License

MIT — see LICENSE.