Tutorial 05
Give an AI agent warehouse access
Point Claude, Cursor or Codex at llms.txt and the shipped SKILL.md, give it a read-only profile, and let it answer stock questions safely.
Most APIs make an agent guess. Stockpilot publishes two machine-readable surfaces that are regenerated from the OpenAPI schema on every request, so they cannot fall out of date with the API they describe.
The two files that matter
| File | What it is | When to use it |
|---|---|---|
| llms.txt | Compact index: auth rules, conventions, and one line per operation grouped by tag | Cheap to load. Start here in a coding session. |
| llms-full.txt | Every operation with parameters, request bodies, response codes and real example payloads | When the agent needs to construct an exact request. |
Both are plain text. No SDK, no MCP server, no tool definitions to maintain. If your assistant can fetch a URL, it can use the Stockpilot API.
Try it in one prompt
Paste this into Claude Code, Cursor or any assistant that can read a URL:
Read https://api.stockpilot.dev/llms.txt
Using the Stockpilot API with the credentials in my environment
(SP_CLIENT_ID and SP_CLIENT_SECRET), list every SKU with less than
two weeks of stock cover, sorted by how soon it runs out.
The index tells it that authentication is two headers, that list endpoints paginate with page and page_size, and that GET /analytics/items/sales exists. That is usually enough for it to write and run a correct script on the first attempt.
Give an agent its own credential pair rather than sharing yours. Rate limits are applied per key, so a runaway loop then throttles only itself, and you can revoke that one pair without disturbing your other integrations.
Make it read-only first
Before you let an agent loose, decide whether it needs to write at all. Most useful agent work is reading: which SKUs are short, what sold last month, which orders are stuck.
stockpilot login --read-only
A read-only profile refuses every request that is not a GET, and it refuses before any network call is made. Enforcement sits in the API client rather than in each command, so a newly added command cannot forget it.
Check what a profile is set to, and what is actually in effect:
stockpilot access
Access: read-only
Effective: read-only
To tighten one invocation without changing the saved profile, set the environment variable:
STOCKPILOT_READ_ONLY=1 stockpilot orders cancel 512 # refused
That direction only tightens. A read-only profile cannot be widened by the environment. When you do want writes back:
stockpilot access set full
This is a guardrail against mistakes, not a security boundary. The config file belongs to whoever runs the CLI, and an agent with shell access can edit it. If you need a hard limit, issue API credentials that lack write permission.
Add the CLI for write access
Reading is one thing. If you want an agent to actually fulfil orders or adjust stock, install the CLI and let it shell out rather than hand-rolling HTTP calls:
curl -fsSL https://stockpilot.dev/install | sh
stockpilot login
Every command supports --json, which is what makes it agent friendly. The output is stable, parseable and pipes into jq:
stockpilot inventory list --json | jq '.[] | select(.quantity < 5)'
stockpilot orders list --status open --json | jq 'length'
Hand it the skill file
The CLI repository ships skills/SKILL.md, a written brief for agents. It covers where credentials live, the rule to always pass --json when parsing, a goal to command lookup table, and four worked workflows:
- Check stock for pending orders
- Find slow and fast movers
- Fulfil an order end to end
- Replenish low stock
Drop it into your agent’s context, or into a skills/ directory if your tool supports them, and the agent stops guessing at flags.
curl -fsSL https://raw.githubusercontent.com/StockpilotHQ/stockpilot-cli/main/skills/SKILL.md \
-o .claude/skills/stockpilot/SKILL.md
Formats it needs to know
Three conventions trip up agents that were not told about them:
- Product lookup takes exactly one of
id,skuorbarcode. Passing two is an error, passing none is an error. - Locations are hierarchical bins written
A1-001-01. - Thresholds are either units (
5u) or weeks of cover (33w).
All three are stated in llms.txt and in SKILL.md, which is the point: the agent reads them rather than learning by failing.
What it cannot do
Be honest with your users about the boundary. There is no OAuth flow and no app install, so an agent always acts as whoever issued the credential pair. There is no per-key scoping either, so a key that can read inventory can also fulfil orders. If you are building something a customer will run, ask each merchant for their own pair and store it the way you would store any other secret.
For the full picture of how credentials behave, read the authentication guide.
