gear-foundationgear-foundation/vara-skills/skills/gear-gstd-api-map/SKILL.md

gear-gstd-api-map

Skill17 starsChanged 7 months agoMITView on GitHub

Use when a builder needs to choose the right gstd API for messaging, execution, reservations, async reply flows, or program creation, and trace that API to gcore or gsys when behavior must be confirmed. Do not use for Vara.eth or ethexe-first work, non-Gear repositories, or broad runtime-maintenance tasks.

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.

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

Common
Distinctive
Very specific

Very specific:
Keep design work API-first: start from gstd, then drop to gcore or gsys only when you need to confirm limits, gas shape, or low-level …
line 10
Distinctive:
Start from builder intent, not from raw syscalls.
line 29
Distinctive:
Prefer the highest-level API that preserves the contract: typed send and reply first, bytes only for intentional raw payload paths or codec …
line 31
Distinctive:
Check design constraints: block-delayed execution, reply deposit, reservation lifetime, waitlist exposure, gas budget, and Sails Header …
line 32
Very specific:
Prefer gstd as the default public API for standard Gear/Vara builders.
line 46
Very specific:
Treat raw gsys::gr_* names as confirmation tools, not the first design vocabulary.
line 47
Distinctive:
Keep design notes phrased in message flow, replies, blocks, and contracts, not in syscall sequences.
line 48
Distinctive:
If a Sails route depends on generated clients, preserve that route contract even for delayed or self-messaging paths.
line 49
Distinctive:
Stop if the task is really about runtime benchmarking, syscall-maintenance coverage, or ethexe-only behavior.
line 50

≈ “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

Gear gstd API Map

Goal

Keep design work API-first: start from gstd, then drop to gcore or gsys only when you need to confirm limits, gas shape, or low-level behavior.

Inputs

../../references/gear-execution-model.md — execution model and block lifecycle
../../references/gear-messaging-and-replies.md — message flow and reply semantics
../../references/gear-gas-reservations-and-waitlist.md — gas reservations and waitlist
../../references/gear-gstd-api-and-syscalls.md — full API surface and syscall mapping

Route Here When

a spec or architecture note needs to know whether a Gear program can send, await replies, self-schedule, reserve gas, or create child programs
a builder is choosing between typed payloads, raw bytes, staged push-plus-commit, or input-forwarding APIs
a design depends on #[gstd::async_main], _for_reply flows, delayed work, ReservationId, or prog::*
a debugging pass needs to confirm which gr_* syscall family a high-level API actually reaches
a send_for_reply targets a hardcoded non-program ActorId (staking, proxy, BLS12-381, ETH bridge); route to gear-builtin-actors for the per-actor request shape and reply decoding

Working Model

Start from builder intent, not from raw syscalls.
Choose the gstd family: msg, exec, prog, reservations, or async helpers.
Prefer the highest-level API that preserves the contract: typed send and reply first, bytes only for intentional raw payload paths or codec debugging.
Check design constraints: block-delayed execution, reply deposit, reservation lifetime, waitlist exposure, gas budget, and Sails Header routing stability for Sails clients.
Drop to gcore to confirm wrapper behavior and to gsys only when you need exact syscall names, fallibility, or control-vs-get distinctions.

API Quick Reference

Module	Key APIs	When to Use
`msg`	`send`, `reply`, `send_delayed`, `send_for_reply`, `send_bytes`, push-plus-commit	Sending messages, replying, delayed dispatch, awaiting replies
`exec`	`gas_available`, `block_height`, `wait`, `wait_for`, `wake`, `reply_deposit`, `exit`	Reading execution context, parking in waitlist, waking actors
`prog`	`create_program`, `create_program_bytes`, create-for-reply	Creating child programs with optional delay and gas limits
reservations	`ReservationId::reserve`, `.unreserve`, reservation pools	Future-block work that must keep a gas budget alive

Guardrails

Prefer gstd as the default public API for standard Gear/Vara builders.
Treat raw gsys::gr_* names as confirmation tools, not the first design vocabulary.
Keep design notes phrased in message flow, replies, blocks, and contracts, not in syscall sequences.
If a Sails route depends on generated clients, preserve that route contract even for delayed or self-messaging paths.
Stop if the task is really about runtime benchmarking, syscall-maintenance coverage, or ethexe-only behavior.

Download now (ZIP)

In this repository27 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- vara-skillsSkill
- vara-skillsSkill
- awesome-sails-vftSkill
- gear-architecture-plannerSkill
- gear-builtin-actorsSkill
- gear-message-executionSkill
- gtest-tdd-loopSkill
- idea-to-specSkill
- sails-architectureSkill
- sails-dev-envSkill
- sails-ethexe-architectureSkill
- sails-ethexe-implementerSkill
- sails-feature-workflowSkill
- sails-frontendSkill
- sails-gtestSkill
- sails-idl-clientSkill
- sails-indexerSkill
- sails-local-smokeSkill
- sails-new-appSkill
- sails-program-evolutionSkill
- sails-rust-implementerSkill
- ship-sails-appSkill
- task-decomposerSkill
- vara-skills-upgradeSkill
- vara-walletSkill

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