Agent skill

Read the skill at https://agentfs.cloud/agent-onboarding/SKILL.md. Give that URL to an agent that can load remote instructions, or fetch it to inspect:

curl -fsSL https://agentfs.cloud/agent-onboarding/SKILL.md

The skill tells the agent to:

1. Set AGENTFS_API_URL to https://agentfs.cloud.
2. Start the device flow with POST /v1/auth/device.
3. Show you verification_uri_complete and user_code.
4. Poll POST /v1/auth/device/token every 5 seconds until you approve the request.
5. Store the returned api_key as AGENTFS_KEY.
6. Upload through POST /v1/files and use the returned file URL.

An agent can also connect to the hosted MCP endpoint:

claude mcp add --transport http agentfs https://agentfs.cloud/mcp \
  --header "Authorization: Bearer $AGENTFS_KEY"

To upload to a project path, it uses:

curl -sS -X POST "$AGENTFS_API_URL/v1/files" \
  -H "Authorization: Bearer $AGENTFS_KEY" \
  -F "file=@./report.pdf" \
  -F "path=default/report.pdf"

The skill also lists the file and project endpoints, the resumable upload flow, private-file access links, and the available MCP tools. It tells the agent to check the HTTP status and problem details before retrying, and to keep AGENTFS_KEY out of URLs, files, logs, and user-visible replies.

Working from a path

An agent remembers the path it wrote, not the file ID. Add these three calls to whatever instructions you give it.

To update a file it wrote earlier, send the same path with if_exists=replace:

curl -sS -X POST "$AGENTFS_API_URL/v1/files" \
  -H "Authorization: Bearer $AGENTFS_KEY" \
  -F "file=@./report.pdf" \
  -F "path=default/report.pdf" \
  -F "if_exists=replace"

That is one call and no lookup. The file keeps its ID, path, and hosted URL, so a link the agent already handed over keeps working. The response is 200 instead of 201. Without if_exists, the same path returns 409 path_exists.

To find a file by the path it was written to:

curl -sS -G "$AGENTFS_API_URL/v1/files" \
  -H "Authorization: Bearer $AGENTFS_KEY" \
  --data-urlencode "path=default/report.pdf"

To read the bytes back, follow the redirect from GET /v1/files/:id/content:

curl -sSL "$AGENTFS_API_URL/v1/files/f_8f2c/content" \
  -H "Authorization: Bearer $AGENTFS_KEY"

See Files for the rest of the path-based operations.