Agent skill

Gram Functions

by speakeasy-api in speakeasy-api/gram

A walkthrough of the Gram Functions feature in this codebase

AGPL-3.0Auto-check passedBackend & APIs

Install Gram Functions

skills CLI
$ npx skills add speakeasy-api/gram --skill gram-functions -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install speakeasy-api/gram gram-functions --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/speakeasy-api/gram.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/gram-functions .claude/skills/gram-functions && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
gram-functions
GitHub stars
272
Token cost
~2k tokens
SKILL.md length
733 words
Files
1
Skills in repo
39
Repo updated
First seen
Licence
AGPL-3.0

At a glance

A walkthrough of the Gram Functions feature in this codebase

  • Works in 3 steps: gram-runner -init -language -… → su-exec gram - Drops privileges to… → gram-runner -language - Starts HTTP…
  • Backend & APIs work in your project
  • SKILL.md covers Key Server Packages, Key Files, Function Runner OCI Images… and Database Tables, plus 3 more sections
  • Calls node and python

What it does

Gram Functions is an agent skill from speakeasy-api/gram. A walkthrough of the Gram Functions feature in this codebase

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs. The repository describes itself as: Securely scale AI usage across your organization. A single stack to Connect, Secure, Observe and Distribute agents, MCPs, and Skills within your company. The licence is AGPL-3.0.

When your agent uses it

  • Backend & APIs work in your project

Example prompts

  • “/gram-functions”

Requirements

  • Python 3
  • Node.js

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. gram-runner -init -language - Initializes filesystem, unzips user code
  2. su-exec gram - Drops privileges to non-root gram user (UID 10000)
  3. gram-runner -language - Starts HTTP server on port 8888

What it can do on your machine

Read from SKILL.md and the folder at commit ad78247. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • node
    • python

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Gram Functions loads about 2k tokens when it runs. Until then it costs about 19 tokens; SKILL.md has 733 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~19
When it runs · the whole SKILL.md, loaded when a task matches
~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from speakeasy-api/gram at commit ad78247, republished under its AGPL-3.0 licence (© speakeasy-api). 733 words, ~2,039 tokens.

Download SKILL.mdSave it as .claude/skills/gram-functions/SKILL.md (or your agent's skills folder).
name
gram-functions
description
A walkthrough of the Gram Functions feature in this codebase
metadata.relevant_files
server/internal/functions/**/*.go, server/internal/background/activities/deploy_function_runners.go, server/internal/background/activities/reap_functions.go…

Gram Functions

Gram Functions is a serverless code execution feature that allows users to deploy custom JavaScript/TypeScript or Python code as callable tools within Gram deployments. Functions can be invoked by AI agents during conversations.

Key Server Packages

PackagePurpose
server/internal/functions/Core functions service - deployment, execution, auth
server/internal/background/activities/Temporal activities for deploying/reaping function runners
server/design/functions/Goa API design for functions endpoints

Key Files

Server Implementation (server/internal/functions/)
  • impl.go - API service, handles signed asset URL requests from runners
  • deploy.go - Core interfaces: Deployer, ToolCaller, Orchestrator
  • deploy_fly.go - Fly.io integration via Machines API
  • manifest.go - Manifest format (ManifestV0) describing exported tools/resources
  • runtimes.go - Supported runtime definitions (JS, TS, Python)
  • auth.go - JWT authentication for function runners
  • queries.sql - SQL queries for fly_apps table management
Background Workers (server/internal/background/)
  • activities/deploy_function_runners.go - Deploys runners during deployment processing
  • activities/reap_functions.go - Cleans up old Fly.io apps
  • activities/provision_functions_access.go - Creates access credentials for runners
  • functions_reaper.go - Temporal workflow for cleanup (triggered per-project after deployments)

Function Runner OCI Images (functions/)

The functions/ directory contains the source code and build configuration for the OCI images that run user functions on Fly.io. These images are built using melange and apko for reproducible, minimal container images.

Build System
FilePurpose
melange.yamlBuilds the gram-runner Go binary as an APK package
images/nodejs22-alpine3.22.yamlapko config for Node.js 22 runtime image
images/python3.12-alpine3.22.yamlapko config for Python 3.12 runtime image
Image Structure

Each runtime image contains:

  • Alpine Linux base with minimal packages (ca-certificates-bundle, su-exec)
  • Language runtime (nodejs or python3)
  • The gram-runner binary (built from cmd/runner/main.go)

Entrypoint behavior:

  1. gram-runner -init -language <lang> - Initializes filesystem, unzips user code
  2. su-exec gram - Drops privileges to non-root gram user (UID 10000)
  3. gram-runner -language <lang> - Starts HTTP server on port 8888
Runner Binary (cmd/runner/main.go)

The gram-runner binary is an HTTP server that:

  • Listens on :8888 for tool call and resource requests
  • Authenticates requests using JWT tokens
  • Spawns language-specific subprocesses to execute user code
  • Communicates with subprocesses via named pipes (FIFO)
  • Reports resource usage (CPU, memory, execution time) as HTTP trailers
  • Auto-terminates after 1 minute of idle time (scale-to-zero support)
Internal Packages (functions/internal/)
PackagePurpose
auth/JWT authentication and request authorization middleware
bootstrap/Machine initialization: unzip code, prepare entrypoints, lazy asset loading
encryption/AES-GCM encryption for secure communication
guardian/Process execution with resource limits
ipc/Named pipe (FIFO) creation for subprocess communication
javascript/JavaScript/TypeScript entrypoint script (gram-start.js)
python/Python entrypoint script (gram_start.py)
runner/HTTP handlers for /tool-call and /resource-request endpoints
svc/Service utilities (idle tracking, secrets, errors)
o11y/Observability setup (OpenTelemetry, logging)
middleware/HTTP middleware (recovery, version header)
attr/Structured logging attribute helpers
Show full SKILL.md (326 more words)Show less
Tool Call Execution Flow
  1. Request received at POST /tool-call with JSON payload:
    json
    {"name": "tool_name", "input": {...}, "environment": {...}}
  2. FIFO created - Named pipe for IPC with subprocess
  3. Subprocess spawned - node --experimental-strip-types gram-start.js or python gram_start.py
  4. Arguments passed - FIFO path, serialized request, request type ("tool" or "resource")
  5. Response read - HTTP response format read from FIFO
  6. Metrics collected - CPU time, memory, execution duration added as trailers
  7. Cleanup - FIFO removed, subprocess waited
Lazy Asset Loading

For large function bundles (>700KiB), the code isn't embedded in the Fly machine config. Instead:

  1. A .lazy file is written containing the asset ID
  2. On init, bootstrap.resolveLazyFile() detects the .lazy file
  3. Runner fetches a pre-signed URL from the Gram server
  4. Code is downloaded from Tigris blob storage and unzipped

Database Tables

TablePurpose
deployments_functionsLinks functions to deployments, stores runtime/slug
functions_accessEncryption keys and bearer token formats for auth
fly_appsTracks deployed Fly.io apps (status, region, URL, reap state)
function_tool_definitionsTool metadata (name, description, input schema, variables)
function_resource_definitionsResource metadata (URI, mime type)

Deployment Flow

  1. Upload - User uploads ZIP archive with function code + manifest.json
  2. Processing - Temporal workflow triggers DeployFunctionRunners activity
  3. Fly.io Deployment - Creates Fly app via Machines API with appropriate runtime image
  4. Asset Handling - Small functions embedded in config; large functions use Tigris blob storage with lazy loading
  5. Auto-scaling - 2 machines per function, scale to 0 when idle

Execution Flow

  1. AI agent requests tool call → FlyRunner.ToolCall() sends authenticated HTTP request
  2. Runner receives request at /tool-call endpoint
  3. Subprocess spawned (node/python) with user code
  4. Communication via named pipe (FIFO)
  5. Response streamed back with resource usage metrics as HTTP trailers

Cleanup (Reaping)

  • Functions Reaper workflow is triggered after each deployment completes (see server/internal/deployments/impl.go)
  • Keeps only N most recent deployments' Fly apps per project (default: 3)
  • Old apps deleted via Machines API, marked reaped_at in database
  • Note: A FunctionsReaperScopeGlobal scope exists in the code but is not currently used/scheduled

© speakeasy-api, AGPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/gram-functions of speakeasy-api/gram.

Open the folder on GitHubat commit ad78247

Compare with similar skills

Gram Functions next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Gram Functions compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Gram Functions this skillspeakeasy-api/gram272—~2kAutomated safety check: PassAGPL-3.0
Mintlify APImacro-inc/macro4.6k2 repos~333Automated safety check: PassMIT
Rtvi Vlm Perf TestingNVIDIA-AI-Blueprints/video-search-and-summarization1.9k—~8.6kAutomated safety check: NotesApache-2.0
Frappe Ops Website DeployImpertio-Studio/Frappe_Claude_Skill_Package187—~2.5kAutomated safety check: PassMIT
Noodle Usewilfredinni/noodle363—~8.5kAutomated safety check: NotesApache-2.0
Supercheck Feature Implementationsupercheck-io/supercheck215—~1.1kAutomated safety check: PassAGPL-3.0

Similar skills

  • Mintlify API

    macro-inc/macro

    Interact with the Mintlify REST API to manage deployments, trigger builds, and query documentation site metadata programmatically.

    4.6k GitHub starsUsed in 2 repos~333 tokens
    Backend & APIsAuto-check passed
  • Rtvi Vlm Perf Testing

    NVIDIA-AI-Blueprints/video-search-and-summarization

    Plan, run, and diagnose reproducible RT-VLM GPU performance canaries and benchmarks.

    1.9k GitHub stars~8.6k tokensUpdated today
    Backend & APIsAuto-check: notes
  • Frappe Ops Website Deploy

    Impertio-Studio/Frappe_Claude_Skill_Package

    Deploy HTML/CSS websites to ERPNext/Frappe (v15/v16) as Web Pages via the REST API.

    187 GitHub stars~2.5k tokensUpdated 20 days ago
    Backend & APIsAuto-check passed
  • Noodle Use

    wilfredinni/noodle

    Teach agents to create, organize, maintain, evaluate, import, convert, and automate noodle terminal REST client collections using supported CLI commands plus YAML and dotenv files.

    363 GitHub stars~8.5k tokensUpdated today
    Backend & APIsAuto-check: notes
  • Supercheck Feature Implementation

    supercheck-io/supercheck

    Implement a new or changed Supercheck feature end to end across schema, auth/RBAC, services, routes/actions, UI, queues/workers, CLI/recorder, tests, docs, and deployment contracts.

    215 GitHub stars~1.1k tokensUpdated today
    Backend & APIsAuto-check passed
  • Flow Nexus Platform

    ruvnet/agentic-flow

    Comprehensive Flow Nexus platform management - authentication, sandboxes, app deployment, payments, and challenges

    816 GitHub starsUsed in 4 repos~6.4k tokens
    Backend & APIsAuto-check passed

More from speakeasy-api/gram

All 39 skills in this repo
  • Gram Playwright CLI

    speakeasy-api/gram

    A skill your agent uses when automating the Gram dashboard in a browser, capturing screenshots, inspecting pages.

    272 GitHub stars~3.4k tokensUpdated today
    Auto-check passed
  • Transactional Email

    speakeasy-api/gram

    A skill your agent uses when adding, changing, restyling, reviewing, validating, or previewing a Gram/Speakeasy transactional email, in Go or in LMX/MJML — a template<name.go, a TemplateKey…

    272 GitHub stars~4.7k tokensUpdated today
    Auto-check passed
  • Admin Shadcn

    speakeasy-api/gram

    A skill your agent uses when adding, changing, or styling UI in client/admin (the Gram admin dashboard) that touches shadcn/ui — a button, dialog, table, sidebar, badge, select, tabs, tooltip, card…

    272 GitHub stars~1k tokensUpdated today
    Auto-check passed
  • A skill your agent uses when adding, editing, reviewing, testing, or locating a reviewed skill distributed with the Platform MCP plugin; triggers include "Platform MCP skill", "platformmcpskills"…

    272 GitHub stars~2.2k tokensUpdated today
    Auto-check passed
  • Clickhouse

    speakeasy-api/gram

    A skill your agent uses when changing or reviewing Gram ClickHouse schemas, migrations, queries, inserts, access principals, bootstrap SQL, Cloud compatibility, partial migration failures, or…

    272 GitHub stars~3.2k tokensUpdated today
    Auto-check passed
  • Feature Flag

    speakeasy-api/gram

    A skill your agent uses when gating a feature behind a flag, dogfooding or gradually rolling out a change, choosing between productfeatures and PostHog feature flags, adding or checking a product…

    272 GitHub stars~2.6k tokensUpdated today
    Auto-check passed

Questions about Gram Functions

What does Gram Functions do?

A walkthrough of the Gram Functions feature in this codebase. Gram Functions is an agent skill from speakeasy-api/gram.

When should I use Gram Functions?

Gram Functions fits situations like: backend & APIs work in your project.

How do I install Gram Functions in Claude Code?

Run `npx skills add speakeasy-api/gram --skill gram-functions -a claude-code`. Or copy the skill folder (.agents/skills/gram-functions in speakeasy-api/gram) into .claude/skills/gram-functions in your project. Claude Code loads it when a task matches its description.

How do I install Gram Functions in Codex?

Run `npx skills add speakeasy-api/gram --skill gram-functions -a codex`. Or copy the skill folder (.agents/skills/gram-functions in speakeasy-api/gram) into .agents/skills/gram-functions in your project. Codex loads it when a task matches its description.

Can I use Gram Functions in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add speakeasy-api/gram --skill gram-functions -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/gram-functions, .gemini/skills/gram-functions, .github/skills/gram-functions and .opencode/skills/gram-functions in your project.

What does Gram Functions need to run?

Going by SKILL.md and its folder, Gram Functions needs the command-line tools its instructions call (node and python). Our summary lists: Python 3; Node.js.

Does Gram Functions access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Gram Functions safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Gram Functions use?

Gram Functions is published under the AGPL-3.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Gram Functions use?

About 2k tokens (SKILL.md is roughly 8.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Gram Functions?

Skills that share tags, products or a category with Gram Functions: Mintlify API (macro-inc/macro, 4.6k stars), Rtvi Vlm Perf Testing (NVIDIA-AI-Blueprints/video-search-and-summarization, 1.9k stars), Frappe Ops Website Deploy (Impertio-Studio/Frappe_Claude_Skill_Package, 187 stars) and Noodle Use (wilfredinni/noodle, 363 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Gram Functions?

speakeasy-api (a GitHub organization) maintains it in speakeasy-api/gram, which has 272 GitHub stars. The repository holds 39 skills in this directory. The repository was last updated on October 8, 2026.

Source: speakeasy-api/gram on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.