Agent skill

Setting Up Relayfile

by AgentWorkforce in AgentWorkforce/relay

A skill your agent uses when an agent or human needs to set up relayfile end-to-end so agents can read and write provider files through a local mount.

Apache-2.0Auto-check passedProductivity & Automation

Install Setting Up Relayfile

skills CLI
$ npx skills add AgentWorkforce/relay --skill setting-up-relayfile -a claude-code

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

GitHub CLI
$ gh skill install AgentWorkforce/relay setting-up-relayfile --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/AgentWorkforce/relay.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/setting-up-relayfile .claude/skills/setting-up-relayfile && 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
setting-up-relayfile
GitHub stars
865
Token cost
~3.3k tokens
SKILL.md length
826 words
Files
1
Skills in repo
14
Repo updated
First seen
Licence
Apache-2.0

At a glance

A skill your agent uses when an agent or human needs to set up relayfile end-to-end so agents can read and write provider files through a local mount.

  • Works in 4 steps: Run setup (interactive happy path) → Verify the mount is healthy → Hand off to an agent → …
  • Human needs to set up relayfile end-to-end so agents can read and write provider files through a local mount
  • Calls jq, curl and git; reaches api.relayfile.dev and agentrelay.com; needs RELAYFILE_TOKEN
  • Tasks that involve App automation through connectors

What it does

Setting Up Relayfile is an agent skill from AgentWorkforce/relay. Use when an agent or human needs to set up relayfile end-to-end so agents can read and write provider files through a local mount. Covers relayfile setup, dynamic integration discovery with relayfile integration available/search, Nango and Composio backend selection, Atlassian site selection and metadata, cloud login, OAuth/connect flows, mount verification, RELAYFILELOCALDIR handoff, writeback status and retry commands, and key May 2026 cloud-mount gotchas.

Its SKILL.md is about 3.3k 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 Productivity & Automation, covering App automation through connectors and OAuth and OpenID Connect. It works with Composio, Notion and Slack. The repository describes itself as: Infrastructure for coding agents. The licence is Apache-2.0.

When your agent uses it

  • Human needs to set up relayfile end-to-end so agents can read and write provider files through a local mount
  • Tasks that involve App automation through connectors
  • Tasks that involve OAuth and OpenID Connect

Example prompts

  • “/setting-up-relayfile”

Requirements

  • Docker
  • A credential in RELAYFILE_TOKEN

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Run setup (interactive happy path)
  2. Verify the mount is healthy
  3. Hand off to an agent
  4. Verify writeback works (optional but recommended)

What it can do on your machine

Read from SKILL.md and the folder at commit 734600d. 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:

    • jq
    • curl
    • git

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

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • api.relayfile.dev
    • agentrelay.com

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

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • RELAYFILE_TOKEN

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

Context cost

Setting Up Relayfile loads about 3.3k tokens when it runs. Until then it costs about 123 tokens; SKILL.md has 826 words of instructions outside code blocks.

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

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 AgentWorkforce/relay at commit 734600d, republished under its Apache-2.0 licence (© AgentWorkforce). 826 words, ~3,346 tokens.

Download SKILL.mdSave it as .claude/skills/setting-up-relayfile/SKILL.md (or your agent's skills folder).
name
setting-up-relayfile
description
Use when an agent or human needs to set up relayfile end-to-end so agents can read and write provider files through a local mount. Covers `relayfile setup`, dynamic integration discovery with `relayfile integration available/search`, Nango and Composio backend selection, Atlassian site selection and metadata, cloud login, OAuth/connect flows, mount verification, `RELAYFILE_LOCAL_DIR` handoff, writeback status and retry commands, and key May 2026 cloud-mount gotchas.
Overview

Relayfile mounts a provider (Notion, Linear, Slack, GitHub, and other adapter-backed integrations) as ordinary files on disk so an agent can read and write through the filesystem instead of calling APIs. This skill is the canonical setup recipe. Follow it top-to-bottom for first-time setup; jump to Recovering from breakage if a working mount has gone wrong.

When to use this skill
  • An agent needs read access to a provider (e.g., "summarize this Notion database").
  • An agent needs to write back to a provider (e.g., "post a review on this Notion page", "update this Linear issue").
  • A human is setting up a mount before delegating work to an agent.
  • A mount stopped reflecting changes and you need to diagnose where.
What you get
After setup, files appear under <local-dir>/<provider>/...:
text
~/relayfile-mount/notion/
├── databases/
│   ├── <slug>--<id>/
│   │   ├── metadata.json     ← database schema (read-only)
│   │   └── pages/
│   │       ├── <slug>--<id>.json     ← page metadata
│   │       └── <slug>--<id>/
│   │           ├── content.md        ← page body (READ + WRITE)
│   │           └── blocks/<id>.json  ← raw Notion block tree
└── pages/                            ← top-level pages (not in a database)
Prerequisites
  • Recent relayfile CLI on $PATH. Verify: relayfile --help should list setup, integration, writeback, and the integration available / integration search / integration set-metadata subcommands.
  • A modern macOS or Linux shell with jq for JSON inspection. AWS CLI access is optional and only needed for internal cloud log diagnostics.
  • Network access to agentrelay.com/cloud (cloud control plane), api.relayfile.dev (relayfile API), connect.nango.dev (Nango OAuth), and Composio connect endpoints when using --backend composio.
Step 1 — Run setup (interactive happy path)
```bash
bash
relayfile setup \
  --provider notion \
  --workspace my-agent \
  --local-dir ~/relayfile-mount \
  --no-open
Step 2 — Verify the mount is healthy
```bash
bash
relayfile status my-agent
Step 3 — Hand off to an agent
Pattern A: local agent (Claude Code, scripts, Cursor)
bash
export RELAYFILE_LOCAL_DIR=~/relayfile-mount
# point Claude Code at the dir or `cd` in
Pattern B: remote agent / SDK access (no disk mirror)
ts
import { RelayFileClient } from '@relayfile/sdk';

const token = process.env.RELAYFILE_TOKEN; // from ~/.relayfile/credentials.json
const client = new RelayFileClient({ token, server: 'https://api.relayfile.dev' });

// Read
const file = await client.getFile('rw_xxxxxxxx', '/notion/pages/xxx/content.md');

// Write — triggers writeback automatically
await client.putFile('rw_xxxxxxxx', '/notion/pages/xxx/content.md', {
  content: '# New body\n\n…',
  contentType: 'text/markdown',
});
Skip-able if the agent only reads. Required if the agent will write.
bash
echo "[writeback test $(date -u +%FT%TZ)]" > ~/relayfile-mount/notion/pages/<throwaway-page>/content.md
Discover writeback contracts before writing
Do not guess writeback shapes and do not use a magic new.json filename. Current relayfile adapters ship discovery documents for writable resources:
text
<provider>/
├── .adapter.md                         ← adapter overview, operations, ID patterns
└── <resource>/
    ├── .schema.json                    ← full-record JSON Schema, draft 2020-12
    └── .create.example.json            ← minimal create payload
Path conventions per provider
ProviderRead pathsWrite paths
Notion/notion/pages/<slug>--<id>/content.md, /notion/databases/<id>/pages/.../content.md, <slug>.json (metadata)same paths overwrite the body / properties
Slack/slack/channels/<id>/messages/ plus .adapter.md / .schema.json discoverycreate by writing a valid message JSON to /slack/channels/<id>/messages/<non-canonical>.json; edit/delete canonical message files when supported
Linear/linear/issues/<id>.json, comments under issue resources, plus .adapter.md / .schema.json discoverycreate by writing a valid issue/comment JSON to a non-canonical filename; edit/delete canonical issue files when supported
GitHub/github/repos/<owner>/<repo>/pulls/<n>/metadata.json, files.json, plus .adapter.md / .schema.json discoverycreate a review by writing the review JSON to a non-canonical file under the reviews resource

new.json is not special in the file-native adapter contract. If a current .adapter.md and .schema.json are present, translate older examples using /messages/new.json or /comments/new.json to "write the create payload to any non-canonical filename in the resource directory." If the live mount only exposes new.json, treat that as an older deployment surface and follow the mounted template or wait for the workspace to refresh onto the new adapter version.

<local-dir>/.relay/ is reserved — never write there. Anything you put under it gets ignored or treated as daemon state.

Adding more integrations after setup
Do not guess provider names. Ask the CLI for the live catalog first; it pulls static Relayfile integrations plus dynamic Nango providers and Composio toolkits from the cloud, then caches the result locally.
bash
relayfile integration available --refresh
relayfile integration search docker --backend composio --refresh
relayfile integration available --backend nango --search notion
Show full SKILL.md (327 more words)Show less
Common gotchas
G2 — OAuth callback timing trap
bash
curl -sS -X POST "https://agentrelay.com/cloud/api/v1/workspaces/<id>/integrations/connect-session" \
  -H "Authorization: Bearer $(cat ~/.relayfile/credentials.json | jq -r .token)" \
  -H "Content-Type: application/json" \
  -d '{"allowedIntegrations":["notion"]}'
G3 — Dynamic provider discovery and Composio names
bash
relayfile integration search <term> --backend composio --refresh
relayfile integration search <term> --backend nango --refresh
G4 — Jira / Confluence sync says cloudId is missing
bash
relayfile integration connect jira --workspace my-agent --no-open
# or, if you know the target site:
relayfile integration set-metadata jira cloudId=<cloud-id> baseUrl=https://<site>.atlassian.net --workspace my-agent --yes
G6 — Mount mirror dir conventions
text
<local-dir>/
├── <provider>/...                     ← actual files
├── .relay/
│   ├── state.json                     ← daemon's live state (workspaceId, lag, counters, remoteRoot)
│   ├── integrations/<provider>.json   ← per-integration metadata
│   ├── dead-letter/<opId>.json        ← failed writebacks (Phase 1 dead-letter)
│   ├── permissions-denied.log         ← read/write denials preserved for diagnosis
│   ├── disconnected/<provider>.json   ← marker after `integration disconnect`
│   └── conflicts/<resolved-conflicts>
└── .relayfile-mount-state.json        ← sync revisions per file
Recovering from breakage
Symptom: file edits don't appear in the provider
bash
relayfile writeback status my-agent --json | jq
Symptom: cloud run marked FAILED but the handler logged runner.handler.ok
json
{ "message": "relayfile.mount.cleanup", "flushExitCode": 124, "killAttempted": true, "killExitCode": 0 }
Cleaning up
When you're done with a mount and want to tear down:
bash
# 1. stop the daemon
relayfile stop my-agent

# 2. disconnect each integration (revokes OAuth, removes <provider>/ tree)
relayfile integration disconnect notion --workspace my-agent --yes

# 3. remove the local workspace registration
relayfile workspace delete my-agent --yes

# 4. delete the mirror dir
rm -rf ~/relayfile-mount
What this skill does NOT cover
  • Self-hosted relayfile (running your own relayfile-server Go binary against a private Nango). For most agent use-cases the managed cloud at agentrelay.com is the right choice; self-hosted is for environments where data residency rules out the cloud.
  • Multi-workspace agents. A single agent talking to multiple workspaces simultaneously needs careful token handling that's out of scope here.
  • GitHub-via-relayfile for source code. The GitHub adapter exists but the productized cloud-mount workflow is heavier-weight than git clone; only use it if the agent specifically benefits from filesystem-shaped access to PR metadata, reviews, etc.
Quick reference
CommandPurpose
relayfile setup --provider <p> --workspace <name> --local-dir <path>First-time setup
relayfile status <workspace>Health overview
relayfile mount <workspace> <local-dir>Restart the daemon
relayfile stop <workspace>Stop the daemon
relayfile integration available [--search <q>] [--backend <nango|composio>] [--json] [--refresh]Browse the live provider catalog
relayfile integration search <q> [--backend <nango|composio>] [--json] [--refresh]Search dynamic Nango providers and Composio toolkits
relayfile integration list --workspace <name> --jsonList connected providers
relayfile integration connect <provider> [--backend <nango|composio>] --workspace <name>Add another provider
relayfile integration set-metadata <provider> KEY=VALUE... --workspace <name> --yesReplace flat provider metadata, such as Jira/Confluence cloudId and baseUrl
relayfile integration disconnect <provider> --workspace <name> --yesRemove a provider
relayfile tree <workspace> <path>Live cloud-side directory listing
relayfile read <workspace> <path>Live cloud-side file read
relayfile writeback status <workspace> [--json]Pending / failed / dead-lettered counts
relayfile writeback retry --opId <op> <workspace>Re-enqueue a dead-lettered op
relayfile pull --workspace <name>Force a refresh from provider
relayfile ops list --workspace <name> --jsonCloud-side operation log
relayfile workspace delete <name> --yesRemove from local registry

© AgentWorkforce, Apache-2.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/setting-up-relayfile of AgentWorkforce/relay.

Open the folder on GitHubat commit 734600d

Compare with similar skills

Setting Up Relayfile 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.

Setting Up Relayfile compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Setting Up Relayfile this skillAgentWorkforce/relay865—~3.3kAutomated safety check: PassApache-2.0
Connect Apps with ComposioComposioHQ/awesome-claude-skills77k3 repos~557Automated safety check: PassNone
Openloomi Connectorsmelandlabs/openloomi1k—~3.3kAutomated safety check: PassApache-2.0
Composio Cloud Toolsquarqlabs/argus277—~543Automated safety check: PassApache-2.0
ComposioComposioHQ/composio30k1 repos~1.7kAutomated safety check: PassMIT
Validate OAuth Integrationrome-os/rome717—~2kAutomated safety check: NotesMIT

Similar skills

  • Connect Apps with Composio

    ComposioHQ/awesome-claude-skills

    Connects an agent to 1000+ external apps through the Composio Tool Router plugin, so it can actually send emails, create issues and post messages instead of only drafting them.

    77k GitHub starsUsed in 3 repos~557 tokens
    Productivity & AutomationAuto-check passed
  • Openloomi Connectors

    melandlabs/openloomi

    openloomi Connectors tools - manage the native 7 messaging integrations and pair with the composio skill for the 1000+ apps OAuth layer (Slack, Discord, X, Gmail, Outlook, Google…

    1k GitHub stars~3.3k tokensUpdated 14 days ago
    Productivity & AutomationAuto-check passed
  • Composio Cloud Tools

    quarqlabs/argus

    Routes requests to external SaaS apps such as GitHub, Gmail, Google Calendar, Slack, Notion and Linear through cloud tools, with safeguards on irreversible actions.

    277 GitHub stars~543 tokensUpdated 4 mo ago
    Productivity & AutomationAuto-check passed
  • Composio

    ComposioHQ/composio

    Route and complete Composio work across Composio For You and Composio Platform.

    30k GitHub starsUsed in 1 repo~1.7k tokens
    Productivity & AutomationAuto-check passed
  • Validate a Rome-managed OAuth integration end-to-end — prove a user can click Connect and Rome ends up holding a delegated token it can use to call the provider's API.

    717 GitHub stars~2k tokensUpdated today
    Backend & APIsAuto-check: notes
  • Connect Apps

    yc-software/qm

    Connect an administrator-enabled SaaS app for a user with a one-time OAuth consent link.

    15k GitHub stars~746 tokensUpdated yesterday
    Backend & APIsAuto-check passed

More from AgentWorkforce/relay

All 14 skills in this repo
  • A skill your agent uses when testing web applications with visual verification - automates Chrome browser interactions, element selection, and screenshot capture for confirming UI functionality

    865 GitHub starsUsed in 1 repo~2.2k tokens
    Auto-check passed
  • Agent Relay

    AgentWorkforce/relay

    A skill your agent uses when you need Codex to coordinate multiple agents through Agent Relay for peer-to-peer messaging, lead/worker handoffs, or shared status tracking across sub-agents and…

    865 GitHub stars~1.7k tokensUpdated yesterday
    Auto-check passed
  • Debugging Websocket Issues

    AgentWorkforce/relay

    A skill your agent uses when seeing WebSocket errors like "Invalid frame header", "RSV1 must be clear", or "WSERRUNEXPECTEDRSV1" - covers multiple WebSocketServer conflicts, compression issues, and…

    865 GitHub starsUsed in 1 repo~1.3k tokens
    Auto-check passed
  • GitHub OAuth Nango Integration

    AgentWorkforce/relay

    A skill your agent uses when implementing GitHub OAuth + GitHub App authentication with Nango - provides two-connection pattern for user login and repo access with webhook handling

    865 GitHub starsUsed in 1 repo~3.4k tokens
    Auto-check passed
  • Implementing Command Palettes

    AgentWorkforce/relay

    A skill your agent uses when building Cmd+K command palettes in React - covers keyboard navigation with arrow keys, keeping selected items in view with scrollIntoView, filtering with shortcut…

    865 GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed
  • Using Agent Relay

    AgentWorkforce/relay

    A skill your agent uses when you are a registered relay agent (a spawned worker, or a lead that called registeragent) coordinating with peers in real time over current Agent Relay MCP tools -…

    865 GitHub starsUsed in 1 repo~2k tokens
    Auto-check passed

Questions about Setting Up Relayfile

What does Setting Up Relayfile do?

A skill your agent uses when an agent or human needs to set up relayfile end-to-end so agents can read and write provider files through a local mount. Setting Up Relayfile is an agent skill from AgentWorkforce/relay. Use when an agent or human needs to set up relayfile end-to-end so agents can read and write provider files through a local mount.

When should I use Setting Up Relayfile?

Setting Up Relayfile fits situations like: human needs to set up relayfile end-to-end so agents can read and write provider files through a local mount; tasks that involve App automation through connectors; tasks that involve OAuth and OpenID Connect.

How do I install Setting Up Relayfile in Claude Code?

Run `npx skills add AgentWorkforce/relay --skill setting-up-relayfile -a claude-code`. Or copy the skill folder (.agents/skills/setting-up-relayfile in AgentWorkforce/relay) into .claude/skills/setting-up-relayfile in your project. Claude Code loads it when a task matches its description.

How do I install Setting Up Relayfile in Codex?

Run `npx skills add AgentWorkforce/relay --skill setting-up-relayfile -a codex`. Or copy the skill folder (.agents/skills/setting-up-relayfile in AgentWorkforce/relay) into .agents/skills/setting-up-relayfile in your project. Codex loads it when a task matches its description.

Can I use Setting Up Relayfile 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 AgentWorkforce/relay --skill setting-up-relayfile -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/setting-up-relayfile, .gemini/skills/setting-up-relayfile, .github/skills/setting-up-relayfile and .opencode/skills/setting-up-relayfile in your project.

What does Setting Up Relayfile need to run?

Going by SKILL.md and its folder, Setting Up Relayfile needs the command-line tools its instructions call (jq, curl and git) and credentials named RELAYFILE_TOKEN. Our summary lists: Docker; A credential in RELAYFILE_TOKEN.

Does Setting Up Relayfile access the network?

SKILL.md names 2 domains. In commands or code: api.relayfile.dev and agentrelay.com; the agent is likely to contact these when it follows the instructions. This is read from the text; nothing was executed.

Is Setting Up Relayfile 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 Setting Up Relayfile use?

Setting Up Relayfile is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Setting Up Relayfile use?

About 3.3k tokens (SKILL.md is roughly 13k 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 Setting Up Relayfile?

Skills that share tags, products or a category with Setting Up Relayfile: Connect Apps with Composio (ComposioHQ/awesome-claude-skills, 77k stars), Openloomi Connectors (melandlabs/openloomi, 1k stars), Composio Cloud Tools (quarqlabs/argus, 277 stars) and Composio (ComposioHQ/composio, 30k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Setting Up Relayfile?

AgentWorkforce (a GitHub organization) maintains it in AgentWorkforce/relay, which has 865 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on October 7, 2026.

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