scoping
starsforks
How to install scoping?
shurikentrade/shuriken-skills/scoping
$npx -y skills add ShurikenTrade/shuriken-skills --skill scopingUse when a user asks what an agent key can do, how Shuriken permissions work, or which scopes they need for a given integration.
SKILL.md
| 1 | # Scoping an agent key |
| 2 | |
| 3 | Every agent key carries a set of scopes. A scope is a capability grant — read tokens, execute trades, read positions, deliver notifications. The server enforces scopes on every tool call and API endpoint; a call outside the granted scope fails with a structured authorization error. |
| 4 | |
| 5 | ## Best practice: grant the minimum scopes the agent key actually needs |
| 6 | |
| 7 | This is the single most important rule for agent-key scoping. For every agent key, grant **only** the scopes the integration actively uses — nothing speculative, nothing "just in case," nothing broader than the job requires. |
| 8 | |
| 9 | Concretely: |
| 10 | |
| 11 | - Start from what the integration does on its hot path, and enumerate only those capabilities. |
| 12 | - When in doubt, grant less and widen later if the integration errors on a missing scope. |
| 13 | - Create a separate agent key per integration (or per purpose) rather than one fat key reused everywhere — that way each key's scope surface stays tight. |
| 14 | - If a scope is required for a one-off setup step but not for steady-state operation, consider doing the setup with a broader key and then running with a narrower one. |
| 15 | |
| 16 | Broader scopes are a liability: a leaked key is only as dangerous as the capabilities it carries. |
| 17 | |
| 18 | ## Principles |
| 19 | |
| 20 | - **Separate read from write.** Read scopes are generally safe; write/execute scopes move money or send messages and deserve more scrutiny. |
| 21 | - **Per-integration, not per-user-role.** A scope is a capability, not a persona. Reason about what the integration *does*, not who the user is. |
| 22 | |
| 23 | ## Scope categories |
| 24 | |
| 25 | Authoritative scope names live in the docs; these are the categories to reason about: |
| 26 | |
| 27 | - **Read scopes** — querying token info, positions, wallet balances, alpha signals. Safe for analytics and display use cases. |
| 28 | - **Trading scopes** — planning trades, executing trades, cancelling orders. Required for any integration that moves funds. |
| 29 | - **Delivery scopes** — sending notifications (Telegram, email) on behalf of the user. Rate-limited. |
| 30 | - **Administrative scopes** — managing the user's agent keys themselves, linked wallets, etc. Typically not needed by third-party integrations. |
| 31 | |
| 32 | Fetch `https://docs.shuriken.trade/llms.txt` for the current authoritative scope list and the exact names to pass when minting a key. |
| 33 | |
| 34 | ## Common scope combinations |
| 35 | |
| 36 | - *Read-only analytics dashboard*: read scopes only. |
| 37 | - *Automated trading bot*: read scopes + trading scopes. |
| 38 | - *Notification/alert service*: read scopes + delivery scopes. |
| 39 | - *Full-service trading + notifications*: read scopes + trading scopes + delivery scopes. |
| 40 | |
| 41 | ## When a call fails on scope |
| 42 | |
| 43 | The error response names the missing scope. Two valid responses: |
| 44 | 1. If the scope is genuinely needed, guide the user to rotate the key with the added scope. |
| 45 | 2. If the scope should not be needed (the call is read-only but erroring on a write scope), something in the integration is calling the wrong endpoint — investigate before granting. |
| 46 | |
| 47 | ## Pointers |
| 48 | |
| 49 | - Platform documentation (including scope reference): fetch `https://docs.shuriken.trade/llms.txt` and search for "scopes" |
| 50 | - Related skills: `shuriken:agent-keys`, `shuriken:api-integration` |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
