docs(skill): add setting-up-relayfile#28
Conversation
Canonical setup recipe for agents (or humans delegating to them) that need to mount a provider through relayfile and read/write through the local filesystem. Covers: - happy path (`relayfile setup --provider notion --workspace ... --no-open`) - cloud-login + Nango OAuth flow with the localhost callback trap - mount verification (`relayfile status` lag/pending/dead-lettered) - agent handoff via RELAYFILE_LOCAL_DIR or @relayfile/sdk - writeback introspection (`writeback status`, `writeback retry`) - per-provider path conventions (Notion, Slack, Linear, GitHub) - gotchas captured during the May 2026 setup-and-debug session: - cold-start 500 on POST /workspaces (retry) - OAuth callback timing trap (redirect after wizard exit doesn't load) - rw_<8hex> workspace IDs vs UUID (workspace-id-unification debt) - .relay/dead-letter/<opId>.json record shape - what each writeback failure mode looks like and how to recover - complete teardown procedure - scope statement for what this skill does NOT cover (self-hosted, multi-workspace, GitHub-as-source-code) Companion to the writeback-reliability spec / impl PRs (cloud#452, relayfile#84) — the gotchas section is the runbook for the failure modes those PRs make observable. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis PR introduces a new "setting-up-relayfile" skill package to the Agent Relay Starter manifest. It includes manifest registration via prpm.json and a comprehensive 316-line skill guide covering interactive setup, mount verification, agent handoff patterns, writeback flow, provider path conventions, and troubleshooting. ChangesRelayfile Setup Skill
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 934f1ebdec
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| `lastStatus` tells you what the cloud rejected with. `lastBody` is truncated to 1KB. Once you've fixed the underlying issue (e.g. the file had bad JSON properties, or the page was archived in the provider), retry: | ||
|
|
||
| ```bash | ||
| relayfile writeback retry --opId <opId> --workspace my-agent |
There was a problem hiding this comment.
When a user follows this recovery command, --workspace is rejected by the current relayfile CLI: in relayfile v0.6.3 / PR #84 the documented usage is relayfile writeback retry --opId OP [WORKSPACE], and runWritebackRetry only registers the opId flag rather than a workspace flag. This makes dead-letter recovery fail with an unknown flag whenever the user includes --workspace my-agent; document the workspace as the positional argument instead, e.g. relayfile writeback retry --opId <opId> my-agent.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
skills/setting-up-relayfile/SKILL.md (1)
317-317:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove stray line number.
Line 317 appears to contain only a line number with no content. This should be removed.
🧹 Proposed fix
Remove this empty line entirely, or if there's intended content, add it here.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/setting-up-relayfile/SKILL.md` at line 317, Remove the stray standalone "317" line from the document (it currently appears as an orphan line number on line 317); delete that empty/garbage line so the file contains no lone line numbers, or if there was intended content, replace the "317" with the correct content instead.
🧹 Nitpick comments (2)
skills/setting-up-relayfile/SKILL.md (1)
177-177: 💤 Low valueConsider hyphenating compound modifier.
For formal technical writing, "30-minute TTL" reads more clearly than "~30 minute TTL".
✍️ Suggested edit
-Same trap on the Nango Connect URL: it has a ~30 minute TTL. If the wizard exited and you click it later, you may need to mint a fresh one: +Same trap on the Nango Connect URL: it has a ~30-minute TTL. If the wizard exited and you click it later, you may need to mint a fresh one:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/setting-up-relayfile/SKILL.md` at line 177, Update the phrasing around the Nango Connect URL TTL to use a hyphenated compound modifier: change the sentence containing "Nango Connect URL: it has a ~30 minute TTL" to read "Nango Connect URL: it has a ~30-minute TTL" (or remove the tilde if you prefer "30-minute TTL") so the compound modifier is hyphenated correctly; locate the sentence mentioning "Nango Connect URL" and "~30 minute TTL" in SKILL.md and apply this small copy edit.prpm.json (1)
164-204: Consider whether to add setting-up-relayfile to the Agent Relay Starter collection.The new skill is not included in the "Agent Relay Starter" collection. If agents commonly need to read/write provider files (Notion, Slack, Linear, GitHub) as part of multi-agent workflows, this might warrant inclusion.
However, if Relayfile setup is considered infrastructure/integration work separate from core orchestration, the current structure makes sense.
Can you confirm whether excluding this skill from the collection was intentional?
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@prpm.json` around lines 164 - 204, The Agent Relay Starter collection ("id": "agent-relay-starter", "name": "Agent Relay Starter") currently omits the setup skill for Relayfile; decide if excluding the "setting-up-relayfile" skill was intentional and if it should be bundled with the other packages. If it should be included, add a new package entry in the packages array (similar to existing package objects) with the canonical packageId for the Relayfile setup skill (e.g., the packageId matching your registry for setting-up-relayfile), set version and required flags appropriately, and provide a short reason; if exclusion was intentional, add a brief comment in the collection metadata or PR response explaining that Relayfile setup is considered separate infrastructure/integration work and therefore omitted.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/setting-up-relayfile/SKILL.md`:
- Around line 71-80: The fenced code block showing the workspace snapshot in
SKILL.md is missing a language specifier; update the triple-backtick fence to
include a language (e.g., change ``` to ```text) so the example renders
correctly, leaving the block contents unchanged—locate the sample block in the
SKILL.md content and prepend the language token after the opening backticks.
- Around line 23-34: The fenced directory-tree code block in SKILL.md lacks a
language specifier; update the opening fence for the block that currently starts
with "```" to include a language (e.g., "text" or "bash") so the tree under
"~/relayfile-mount/notion/" renders/accessibility properly; locate the block
showing the tree (the lines with "~/relayfile-mount/notion/" and the nested
directories) and change its opening fence to "```text" (or another appropriate
language).
- Around line 192-202: The fenced code block showing the directory tree
(starting with the opening backticks ``` and the line "<local-dir>/") lacks a
language specifier; update the opening fence to include a language (e.g., change
``` to ```text) so the tree renders correctly, leaving the rest of the block
(lines containing ".relay/", "state.json", "integrations/<provider>.json", etc.)
unchanged.
---
Outside diff comments:
In `@skills/setting-up-relayfile/SKILL.md`:
- Line 317: Remove the stray standalone "317" line from the document (it
currently appears as an orphan line number on line 317); delete that
empty/garbage line so the file contains no lone line numbers, or if there was
intended content, replace the "317" with the correct content instead.
---
Nitpick comments:
In `@prpm.json`:
- Around line 164-204: The Agent Relay Starter collection ("id":
"agent-relay-starter", "name": "Agent Relay Starter") currently omits the setup
skill for Relayfile; decide if excluding the "setting-up-relayfile" skill was
intentional and if it should be bundled with the other packages. If it should be
included, add a new package entry in the packages array (similar to existing
package objects) with the canonical packageId for the Relayfile setup skill
(e.g., the packageId matching your registry for setting-up-relayfile), set
version and required flags appropriately, and provide a short reason; if
exclusion was intentional, add a brief comment in the collection metadata or PR
response explaining that Relayfile setup is considered separate
infrastructure/integration work and therefore omitted.
In `@skills/setting-up-relayfile/SKILL.md`:
- Line 177: Update the phrasing around the Nango Connect URL TTL to use a
hyphenated compound modifier: change the sentence containing "Nango Connect URL:
it has a ~30 minute TTL" to read "Nango Connect URL: it has a ~30-minute TTL"
(or remove the tilde if you prefer "30-minute TTL") so the compound modifier is
hyphenated correctly; locate the sentence mentioning "Nango Connect URL" and
"~30 minute TTL" in SKILL.md and apply this small copy edit.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 51d9269b-61f0-4f93-a8a6-05b8b9f213f6
📒 Files selected for processing (2)
prpm.jsonskills/setting-up-relayfile/SKILL.md
| ``` | ||
| ~/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) | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to fenced code block.
The directory tree structure should specify a language for proper rendering and accessibility.
📝 Proposed fix
-```
+```text
~/relayfile-mount/notion/🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 23-23: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/setting-up-relayfile/SKILL.md` around lines 23 - 34, The fenced
directory-tree code block in SKILL.md lacks a language specifier; update the
opening fence for the block that currently starts with "```" to include a
language (e.g., "text" or "bash") so the tree under "~/relayfile-mount/notion/"
renders/accessibility properly; locate the block showing the tree (the lines
with "~/relayfile-mount/notion/" and the nested directories) and change its
opening fence to "```text" (or another appropriate language).
| ``` | ||
| workspace rw_xxxxxxxx (my-agent) mode: poll lag: 4s | ||
|
|
||
| local mirror: /Users/you/relayfile-mount | ||
| daemon: running (pid 12345) | ||
|
|
||
| notion ready 214 files last event 2s ago | ||
|
|
||
| pending writebacks: 0 failed: 0 dead-lettered: 0 | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to fenced code block.
The example output should specify a language for proper rendering.
📝 Proposed fix
-```
+```text
workspace rw_xxxxxxxx (my-agent) mode: poll lag: 4s📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| workspace rw_xxxxxxxx (my-agent) mode: poll lag: 4s | |
| local mirror: /Users/you/relayfile-mount | |
| daemon: running (pid 12345) | |
| notion ready 214 files last event 2s ago | |
| pending writebacks: 0 failed: 0 dead-lettered: 0 | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 71-71: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/setting-up-relayfile/SKILL.md` around lines 71 - 80, The fenced code
block showing the workspace snapshot in SKILL.md is missing a language
specifier; update the triple-backtick fence to include a language (e.g., change
``` to ```text) so the example renders correctly, leaving the block contents
unchanged—locate the sample block in the SKILL.md content and prepend the
language token after the opening backticks.
| ``` | ||
| <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) | ||
| │ ├── disconnected/<provider>.json ← marker after `integration disconnect` | ||
| │ └── conflicts/<resolved-conflicts> | ||
| └── .relayfile-mount-state.json ← sync revisions per file | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to fenced code block.
The directory tree structure should specify a language for proper rendering.
📝 Proposed fix
-```
+```text
<local-dir>/📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| <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) | |
| │ ├── disconnected/<provider>.json ← marker after `integration disconnect` | |
| │ └── conflicts/<resolved-conflicts> | |
| └── .relayfile-mount-state.json ← sync revisions per file | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 192-192: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/setting-up-relayfile/SKILL.md` around lines 192 - 202, The fenced code
block showing the directory tree (starting with the opening backticks ``` and
the line "<local-dir>/") lacks a language specifier; update the opening fence to
include a language (e.g., change ``` to ```text) so the tree renders correctly,
leaving the rest of the block (lines containing ".relay/", "state.json",
"integrations/<provider>.json", etc.) unchanged.
1 participant
Summary
Canonical setup recipe for agents (or humans delegating to them) that need to mount a provider through relayfile and read/write through the local filesystem.
Companion to the writeback-reliability work (AgentWorkforce/cloud#452, AgentWorkforce/relayfile#84). Captures the gotchas, runbook, and recovery procedures from the May 2026 setup-and-debug session that motivated those fixes.
What's in it
relayfile setup --provider notion --workspace … --no-open, cloud-login flow, Nango OAuth, mount verification.RELAYFILE_LOCAL_DIR) and remote (@relayfile/sdk).writeback status.rw_*workspace-id format vs UUID, mount mirror dir layout including the.relay/dead-letter/<opId>.jsonrecord shape.dead-lettered > 0, pending stuck, counts zero but provider not updating) with diagnostic commands and fixes.The "Quick reference" table at the end summarizes every CLI command this skill teaches.
Test plan
relayfile setuprun after the next cloud deploy to make sure the documented commands still resolve.🤖 Generated with Claude Code