yaohuangguanyaohuangguan/agent-playbook/skills/use-external-api/SKILL.md

use-external-api

Skill1 starsChanged 2 days agoMITView on GitHub

Use a library, SDK, CLI or web API correctly by checking the installed version and real docs instead of relying on memory. Use this whenever code calls a third-party package or service, when you are unsure of a method or parameter name, or when an API call fails. It prevents invented methods and outdated usage.

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Find the existing usage: Search this repository first, and copy how it creates clients, handles errors and sets timeouts.
line 18
Distinctive:
Confirm that each name exists: Search the installed package for each method and parameter you plan to use.
line 40
Distinctive:
Handle real conditions: Check each of these:
line 46
Distinctive:
Isolate the integration: Keep calls to the service in one place, so that tests can stub the network and upgrades touch one file.
line 54
Very specific:
Finish: Follow verify-and-report, and state which docs or version you used.
line 60
Distinctive:
Ask first if the task did not call for one.
line 64

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Use an external API

Your memory of an API may be wrong or out of date, and invented method names often look correct. The installed code and current docs are the truth.

When to use

Any time you call something you did not write, unless the same call already exists in this repository.

Steps

Find the existing usage. Search this repository first, and copy how it creates clients, handles errors and sets timeouts.
Find the exact version.
Stack Check
JavaScript The lockfile, or node_modules/<pkg>/package.json
Python pip show <pkg>
Go go.mod, or go list -m <module>
Rust Cargo.lock
Java mvn dependency:tree
Read the source of truth. In order of trust:
1. Types or source of the installed package
2. Official docs for that version
3. The official changelog or migration guide
Blog posts and forum answers can show you where to look, but confirm with one of these.
Confirm that each name exists. Search the installed package for each method and parameter you plan to use. If you cannot find it, do not use it.
Run a small check. Try the call in a small script or test, using a sandbox or test key. Do not use production data or paid operations for this.
Handle real conditions. Check each of these:
- Timeouts on every network call
- Rate limits, and which errors can be retried
- Pagination, so that you do not read only the first page
- Idempotency keys for writes that may be retried
- Partial failure, and a response in an unexpected shape
Isolate the integration. Keep calls to the service in one place, so that tests can stub the network and upgrades touch one file.
Test it. Stub at the network, with responses taken from real docs or real sandbox calls. Follow write-tests.
Finish. Follow verify-and-report, and state which docs or version you used.

Adding a dependency

Ask first if the task did not call for one. Check that it is maintained, its license suits the project, and the standard library or an existing dependency cannot do the job. Confirm the exact package name from its official source, because similar names can be malicious. Pin it with the lockfile.

Stop and ask when

The call needs real credentials you do not have.
The call costs money, sends messages or changes real data.
Docs and installed code disagree, and you cannot tell which is right.

Common mistakes

Tempting move	Why it fails	Do this instead
Write the call from memory	Names and defaults change	Check the installed version
Retry on any error	A repeated write can duplicate an effect	Retry only safe errors
Read only the first page	Silently loses data	Follow pagination
Use `latest`	Builds change without notice	Pin the version
Fake a response from your imagination	The test passes and production fails	Base it on a real response
Put an API key in the code	It leaks through history	Read it from the environment

Report

Package or API: <name, version>
Source checked: <installed types or docs URL>
Check run: <what you called, and the result>
Handles: <timeouts, retries, pagination, idempotency>
Not verified: <anything not exercised for real>

Download now (ZIP)

Other versions2 projects use a version of this.
Word for word · 2
Remote-Arc/remote-arc★ 5100% same
yaohuangguan/remote-arc★ 5100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- audit-test-suiteSkill
- change-data-safelySkill
- debug-failureSkill
- fix-flaky-testSkill
- hand-off-workSkill
- implement-changeSkill
- orient-in-codebaseSkill
- refactor-safelySkill
- review-codeSkill
- secure-changeSkill
- verify-and-reportSkill
- write-pull-requestSkill
- write-testsSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free