메뉴
Use when working in a shared relayfile virtual filesystem with other agents - covers reading/writing files with metadata, discovering other agents' work, conflict handling, ACL permissions, and real-time collaboration patterns
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/AgentWorkforce/relayfile --skill relayfile-workspace명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | relayfile-workspace |
| description | Use when working in a shared relayfile virtual filesystem with other agents - covers reading/writing files with metadata, discovering other agents' work, conflict handling, ACL permissions, and real-time collaboration patterns |
You are working in a shared virtual filesystem powered by relayfile. Multiple agents read and write files here concurrently. Every file carries semantic metadata (intent, relations, comments) so agents can understand each other's work without direct communication.
RELAYFILE_URL env var# These should be set in your environment
RELAYFILE_URL=http://127.0.0.1:8080 # or https://api.relayfile.dev
RELAYFILE_TOKEN=<your-jwt>
RELAYFILE_WORKSPACE=<workspace-id>
Files sync automatically through the mount daemon. You can read and write files normally on the local filesystem. But to collaborate effectively, use the API for metadata.
Always check before writing to a file someone else may be working on.
# Read a file with its metadata
curl -s "$RELAYFILE_URL/v1/workspaces/$RELAYFILE_WORKSPACE/fs/file?path=/src/auth.ts" \
-H "Authorization: Bearer " \
-H
Response includes semantic metadata:
{
"path": "/src/auth.ts",
"revision": "rev_42",
"content": "...",
"semantics": {
"properties": {
"author": "agent-alpha",
"intent": "implementing JWT validation",
"status": "in-progress"
},
"relations": ["task-123", "epic-auth"],
"comments": ["Blocked on key rotation design"]
}
}
Read the intent and status before editing. If another agent's intent is "in-progress", coordinate or work on a different file.
When you write, always include metadata so other agents understand what you're doing and why.
curl -X PUT "$RELAYFILE_URL/v1/workspaces/$RELAYFILE_WORKSPACE/fs/file?path=/src/auth.ts" \
-H "Authorization: Bearer $RELAYFILE_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Correlation-Id: write-1" \
-H "If-Match: rev_42" \
-d '{
"content": "// JWT auth implementation...",
"semantics": {
"properties": {
"author": "your-agent-name",
"intent": "added refresh token rotation",
"status": "complete"
},
"relations": ["task-123"],
"comments": ["Uses RS256, keys rotate every 24h"]
}
}'
| Property | Purpose | Example Values |
|---|---|---|
author | Who wrote this | Your agent name |
intent | What you were trying to do | "implementing auth", "fixing race condition", "refactoring for readability" |
status | Current state | "in-progress", "complete", "needs-review", "blocked" |
priority | Urgency | "high", "medium", "low" |
depends-on | What this file needs | "waiting on config module" |
Link files to tasks, epics, or other files:
"relations": ["task-123", "epic-auth", "related:/src/config.ts"]
Leave context for other agents:
"comments": ["Uses RS256 not HS256 per security requirements", "See design doc at /docs/auth-design.md"]
Every write requires an If-Match header to prevent silent overwrites.
| Value | Meaning | When to Use |
|---|---|---|
If-Match: 0 | Create new file (fails if exists) | First time writing a file |
If-Match: rev_42 | Update specific revision (fails if stale) | Editing an existing file |
If-Match: * | Write regardless of current state | Seeding, migrations, or when you don't care about conflicts |
If you get a 409 Conflict:
{
"code": "revision_conflict",
"currentRevision": "rev_43",
"expectedRevision": "rev_42",
"currentContentPreview": "// Updated by agent-beta..."
}
Don't retry blindly. Read the current content, understand what changed, merge if needed, then write with the current revision.
curl "$RELAYFILE_URL/v1/workspaces/$WS/fs/query?property.author=agent-beta" \
-H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: q1"
curl "$RELAYFILE_URL/v1/workspaces/$WS/fs/query?relation=task-123" \
-H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: q2"
curl "$RELAYFILE_URL/v1/workspaces/$WS/fs/query?property.intent=architecture+review" \
-H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: q3"
curl "$RELAYFILE_URL/v1/workspaces/$WS/fs/query?property.status=in-progress" \
-H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: q4"
curl "$RELAYFILE_URL/v1/workspaces/$WS/fs/tree?path=/&depth=3" \
-H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: q5"
Before starting work on a file, claim it by writing a stub with status: in-progress:
# Claim the file
curl -X PUT ".../fs/file?path=/src/new-feature.ts" \
-H "If-Match: 0" \
-d '{"content":"// WIP","semantics":{"properties":{"author":"me","intent":"implementing feature X","status":"in-progress"}}}'
# Do your work...
# Update with final content
curl -X PUT ".../fs/file?path=/src/new-feature.ts" \
-H "If-Match: rev_1" \
-d '{"content":"// Final implementation","semantics":{"properties":{"author":"me","intent":"implemented feature X","status":"complete"}}}'
Before implementing, check what exists:
# What's related to my task?
curl ".../fs/query?relation=task-123"
# What's the current state of the module I'm about to change?
curl ".../fs/file?path=/src/auth.ts"
# Who else is working in this area?
curl ".../fs/query?property.status=in-progress&path=/src/"
When you make a decision that affects other agents, leave it in the metadata:
{
"semantics": {
"comments": [
"Changed from REST to WebSocket for real-time updates - see /docs/adr-003.md",
"This breaks the old polling client in /src/poll-client.ts"
]
}
}
When creating many files at once (scaffolding, migrations):
curl -X POST ".../fs/bulk" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "X-Correlation-Id: seed-1" \
-d '{
"files": [
{"path":"/src/index.ts","content":"...","semantics":{"properties":{"author":"me","intent":"scaffolding"}}},
{"path":"/src/config.ts","content":"..."},
{"path":"/src/types.ts","content":"..."}
]
}'
Directories can have access control via .relayfile.acl marker files.
// /finance/.relayfile.acl
{
"semantics": {
"permissions": ["scope:finance", "deny:agent:untrusted-bot"]
}
}
Permission rules:
scope:<name> — allow agents with this scope in their JWTagent:<name> — allow a specific agentdeny:scope:<name> — deny agents with this scope (overrides allows)deny:agent:<name> — deny a specific agentpublic — allow everyonePermissions inherit from parent directories. If you get a 403, check for .relayfile.acl files in ancestor directories.
const ws = new WebSocket(
`ws://${RELAYFILE_URL}/v1/workspaces/${WS}/fs/ws?token=${TOKEN}`
);
ws.on('message', (data) => {
const event = JSON.parse(data);
// event.type: "file.created" | "file.updated" | "file.deleted"
// event.path: "/src/auth.ts"
// event.revision: "rev_43"
console.log(`${event.type}: ${event.path}`);
});
On connect, you'll receive the last 100 events as catch-up, then live events going forward.
curl ".../fs/events?limit=20" \
-H "Authorization: Bearer $TOKEN" -H "X-Correlation-Id: events-1"
| Mistake | Fix |
|---|---|
Writing without If-Match | Always include If-Match: 0 (new), rev_X (update), or * (force) |
Not setting intent metadata | Other agents can't understand your work without it |
| Overwriting without reading first | Check the file's current state and metadata before writing |
| Ignoring 409 conflicts | Read the current version, merge changes, retry with correct revision |
Missing X-Correlation-Id header | Required on all API requests for tracing |
| Writing many files with separate PUTs | Use bulk write (POST /fs/bulk) for scaffolding |
| Not checking for in-progress work | Query property.status=in-progress before starting in a shared area |
Setting status: complete on partial work | Be honest — use in-progress or needs-review |
If @relayfile/sdk is available:
import { RelayFileClient } from '@relayfile/sdk';
const client = new RelayFileClient({
baseUrl: process.env.RELAYFILE_URL,
token: process.env.RELAYFILE_TOKEN,
});
// Read with metadata
const file = await client.readFile('ws_id', '/src/auth.ts');
console.log(file.semantics.properties.intent);
// Write with intent
await client.writeFile({
workspaceId: 'ws_id',
path: '/src/auth.ts',
baseRevision: file.revision,
content: '// updated code',
semantics: {
properties: { author: 'my-agent', intent: 'fix auth bug', status: 'complete' },
relations: ['task-456'],
},
});
// Query other agents' work
const results = await client.queryFiles('ws_id', {
properties: { status: 'in-progress' },
});
If-Match prevents silent overwrites