Agent skill

Octo Files

by Mininglamp-OSS in Mininglamp-OSS/octo-cli

File operations (upload/download, presigned S3 credentials) plus bot housekeeping (register, set-commands, user-info, space-members, typing, heartbeat).

Apache-2.0Auto-check passedBackend & APIs

Install Octo Files

skills CLI

$ npx skills add Mininglamp-OSS/octo-cli --skill octo-files -a claude-code

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

GitHub CLI

$ gh skill install Mininglamp-OSS/octo-cli octo-files --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/Mininglamp-OSS/octo-cli.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/octo-files .claude/skills/octo-files && 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/

Paste into Claude Code

Install the "octo-files" agent skill from https://github.com/Mininglamp-OSS/octo-cli/tree/main/skills/octo-files into .claude/skills/octo-files/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "octo-files", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/Mininglamp-OSS/octo-cli/tree/main/skills/octo-files

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add Mininglamp-OSS/octo-cli --skill octo-files -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install Mininglamp-OSS/octo-cli octo-files --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/Mininglamp-OSS/octo-cli.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/octo-files .agents/skills/octo-files && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "octo-files" agent skill from https://github.com/Mininglamp-OSS/octo-cli/tree/main/skills/octo-files into .agents/skills/octo-files/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "octo-files", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add Mininglamp-OSS/octo-cli --skill octo-files -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install Mininglamp-OSS/octo-cli octo-files --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/Mininglamp-OSS/octo-cli.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/octo-files .cursor/skills/octo-files && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "octo-files" agent skill from https://github.com/Mininglamp-OSS/octo-cli/tree/main/skills/octo-files into .cursor/skills/octo-files/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "octo-files", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/Mininglamp-OSS/octo-cli.git --path skills/octo-files

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add Mininglamp-OSS/octo-cli --skill octo-files -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install Mininglamp-OSS/octo-cli octo-files --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/Mininglamp-OSS/octo-cli.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/octo-files .gemini/skills/octo-files && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "octo-files" agent skill from https://github.com/Mininglamp-OSS/octo-cli/tree/main/skills/octo-files into .gemini/skills/octo-files/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "octo-files", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install Mininglamp-OSS/octo-cli octo-files

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add Mininglamp-OSS/octo-cli --skill octo-files -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/Mininglamp-OSS/octo-cli.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/octo-files .github/skills/octo-files && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "octo-files" agent skill from https://github.com/Mininglamp-OSS/octo-cli/tree/main/skills/octo-files into .github/skills/octo-files/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "octo-files", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add Mininglamp-OSS/octo-cli --skill octo-files -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install Mininglamp-OSS/octo-cli octo-files --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/Mininglamp-OSS/octo-cli.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/octo-files .opencode/skills/octo-files && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "octo-files" agent skill from https://github.com/Mininglamp-OSS/octo-cli/tree/main/skills/octo-files into .opencode/skills/octo-files/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "octo-files", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: octo-files
GitHub stars: 918
Token cost: ~1.6k tokens
SKILL.md length: 487 words
Files: 1
Skills in repo: 11
Repo updated: Oct 10, 2026
First seen: Oct 7, 2026
Licence: Apache-2.0

At a glance

File operations (upload/download, presigned S3 credentials) plus bot housekeeping (register, set-commands, user-info, space-members, typing, heartbeat).

Works in 5 steps: File operations → Bot housekeeping → Common pattern: message attachment… → …
Tasks that involve File uploads and storage
SKILL.md covers 1. File operations, 2. Bot housekeeping, 3. Common pattern: message… and 4. Error recovery, plus 1 more section
Calls jq and curl; needs OCTO_BOT_TOKEN

What it does

Octo Files is an agent skill from Mininglamp-OSS/octo-cli. File operations (upload/download, presigned S3 credentials) plus bot housekeeping (register, set-commands, user-info, space-members, typing, heartbeat). Load after octo-shared.

Its SKILL.md is about 1.6k 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, covering File uploads and storage. The repository describes itself as: Metadata-driven CLI for AI Agent Bots — 48 operations across 7 domains, structured JSON envelope I/O, zero interactive prompts. The licence is Apache-2.0.

When your agent uses it

Tasks that involve File uploads and storage

Example prompts

“/octo-files”

Requirements

A credential in OCTO_BOT_TOKEN

Workflow steps

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

File operations
Bot housekeeping
Common pattern: message attachment end-to-end
Error recovery
Schema lookup

What it can do on your machine

Read from SKILL.md and the folder at commit 6d21f11. 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
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use curl, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names these keys or tokens, usually read from environment variables:
- OCTO_BOT_TOKEN
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Octo Files loads about 1.6k tokens when it runs. Until then it costs about 47 tokens; SKILL.md has 487 words of instructions outside code blocks.

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

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 Mininglamp-OSS/octo-cli at commit 6d21f11, republished under its Apache-2.0 licence (© Mininglamp-OSS). 487 words, ~1,601 tokens.

Download SKILL.mdSave it as .claude/skills/octo-files/SKILL.md (or your agent's skills folder).

name: octo-files
description: File operations (upload/download, presigned S3 credentials) plus bot housekeeping (register, set-commands, user-info, space-members, typing, heartbeat). Load after octo-shared.
version: 0.4.0

octo-files — file I/O and bot housekeeping

Two small domains are covered here because they share a base URL ($OCTO_API_BASE_URL/v1/bot/*) and are usually needed together:

file — 4 ops, no bot-kind restrictions
bot — 6 ops, no bot-kind restrictions

1. File operations

bash

octo-cli file upload      --file ./report.pdf [--type chat] [--path subdir/]
octo-cli file download    <path> --format json > saved.bin      # <path> = storage key (no bucket prefix), see note below
octo-cli file credentials --filename report.pdf
octo-cli file presigned   --filename report.pdf --fileSize 1048576   # --fileSize (bytes) is REQUIRED

`upload` — multipart form

Unlike every other command, file upload sends a multipart multipart/form-data body, not JSON. The --file flag is required and names a local path; --type (default chat) and --path become form text fields. Promoted body flags declared in the spec go in as text fields alongside the binary.

The response envelope carries the returned file descriptor under data — use it to build attachment references in message send.

`download` — returns a presigned URL

file download <path> issues a GET. The backend responds with a 302 redirect to the storage tier. The CLI does not stream raw bytes — instead it returns a JSON envelope containing the presigned URL:

bash

octo-cli file download /chat/2026/05/abc123.png
# → {"ok":true,"data":{"url":"https://s3.../abc123.png?...","status":302,"content_type":"image/png"}}

To actually fetch the file, use the URL from the response:

bash

octo-cli file download /chat/2026/05/abc123.png --jq '.data.url' | xargs curl -o out.png

Direct-to-S3 uploads

For files too large for multipart, ask the backend for a presigned target and upload directly:

bash

size=$(stat -f%z big.zip 2>/dev/null || stat -c%s big.zip)    # fileSize in bytes (REQUIRED; no padding)
cred=$(octo-cli file presigned --filename big.zip --fileSize "$size")
url=$(jq   -r '.data.uploadUrl'                   <<<"$cred")
ctype=$(jq -r '.data.contentType'                 <<<"$cred")
cdisp=$(jq -r '.data.contentDisposition // empty' <<<"$cred")
curl -X PUT -T big.zip -H "Content-Type: $ctype" ${cdisp:+-H "Content-Disposition: $cdisp"} "$url"

file presigned requires --fileSize (bytes) — the size is signed into the PUT Content-Length, so a missing/oversized value is rejected (HTTP 400 — fileSize is required). It returns {method, uploadUrl, downloadUrl, contentType, key, expiresIn, expiredTime, maxFileSize, [contentDisposition]} — a one-shot signed URL (echo contentDisposition verbatim on the PUT if present). file credentials returns STS-style temporary credentials ({bucket, region, key, credentials:{tmpSecretId, tmpSecretKey, sessionToken}, startTime, expiredTime, cdnBaseUrl}) for SDK-driven uploads. Pick the shape the backend gives you.

2. Bot housekeeping

bash

octo-cli bot register       [--data '{"agent_platform":"…","agent_version":"…","plugin_version":"…"}']
octo-cli bot set-commands   --data '{"commands":[{"command":"fix","description":"create a matter"}]}'
octo-cli bot user-info      --uid <uid>         # --uid is REQUIRED; returns {uid,name,avatar} for that user
octo-cli bot space-members  [--keyword <q>]     # members of the bot's space (limit cap 200)
octo-cli bot typing         --channel-id <cid> --channel-type 1 [--on-behalf-of <uid>]
octo-cli bot heartbeat

`bot register` — special auth

register is the only operation not behind the authBot middleware. The backend routes it by token prefix: app_* → registerAppBot, bf_* → registerUserBot. You still supply OCTO_BOT_TOKEN; the CLI treats the call like any other.

Use bot register exactly once per bot lifecycle (publish), then use bot set-commands to advertise slash-command metadata.

Show full SKILL.md (182 more words)Show less

Get the owner_uid from `bot register`

bot user-info needs --uid and returns only {uid, name, avatar} — it does not carry owner_uid. The bot's owner_uid comes from the one-time bot register at publish; capture it then and cache it (env/config) rather than re-registering:

bash

owner=$(octo-cli bot register --jq '.data.owner_uid')   # capture once at publish, then cache

This is the value LLM-backed operations require as creator_uid (e.g. the withheld matter extract, once the matter domain is re-enabled).

`typing` and `heartbeat`

Both are fire-and-forget. typing signals an "…is typing" UI state in DM channels. heartbeat refreshes bot liveness — call it on a long-running poll loop so the platform knows the bot is alive.

3. Common pattern: message attachment end-to-end

bash

# 1. Upload the binary.
up=$(octo-cli file upload --file ./log.txt --type chat)
url=$(jq -r '.data.url'  <<<"$up")
name=$(jq -r '.data.name' <<<"$up")

# 2. Attach it to a message.
octo-cli message send --data "$(jq -n \
  --arg c "chat-1" --arg u "$url" --arg n "$name" \
  '{chat_id:$c, text:"see log", attachments:[{url:$u, name:$n, type:"text/plain"}]}')"

4. Error recovery

Symptom	Fix
`upload` → `PAYLOAD_TOO_LARGE`	Use `file presigned` / `file credentials` and upload direct to S3.
`upload` → `validation` "--file is required"	Path is empty or unreadable; check permissions and absolute path.
`download` returns JSON instead of bytes	Expected; extract `.data.url` and fetch with curl/wget.
`bot typing` returns 200 but no UI update	Channel type must be `1` and the DM must exist.
`bot register` rejected with `UNAUTHORIZED`	Token prefix/env mismatch — confirm with `octo-cli config show`.

5. Schema lookup

bash

octo-cli schema file.upload
octo-cli schema file.download
octo-cli schema bot.register
octo-cli schema bot.user-info

Files

Just SKILL.md in skills/octo-files of Mininglamp-OSS/octo-cli.

Open the folder on GitHubat commit 6d21f11

Compare with similar skills

Octo Files 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.

Octo Files compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Octo Files this skillMininglamp-OSS/octo-cli	918	—	~1.6k	Automated safety check: Pass	Apache-2.0	yesterday
Stripe Projectsfossasia/eventyay	1.7k	5 repos	~2k	Automated safety check: Notes	Apache-2.0	today
FoundatioFoundatioFx/Foundatio	2.1k	—	~3.9k	Automated safety check: Pass	Apache-2.0	2 days ago
Spatialduckdb/duckdb-skills	603	1 repos	~1k	Automated safety check: Notes	MIT	5 mo ago
R Oopab604/claude-code-r-skills	207	2 repos	~1.9k	Automated safety check: Pass	MIT	23 days ago
Edgestore Setupedgestorejs/edgestore	454	—	~1.8k	Automated safety check: Pass	MIT	today

Similar skills

Stripe Projects
fossasia/eventyay
A skill your agent uses when the user wants to provision infrastructure or third-party services using Stripe Projects.
1.7k GitHub starsUsed in 5 repos~2k tokens
Backend & APIsAuto-check: notes
Foundatio
FoundatioFx/Foundatio
A skill your agent uses when working with Foundatio infrastructure abstractions for .NET -- caching, queuing, messaging, file storage, distributed locking, or background jobs.
2.1k GitHub stars~3.9k tokensUpdated 2 days ago
Backend & APIsAuto-check passed
Spatial
duckdb/duckdb-skills
Official
Answer questions about spatial data using DuckDB. An agent skill from duckdb/duckdb-skills.
603 GitHub starsUsed in 1 repo~1k tokens
Backend & APIsAuto-check: notes
R Oop
ab604/claude-code-r-skills
R object-oriented programming guide for S7, S3, S4, and vctrs.
207 GitHub starsUsed in 2 repos~1.9k tokens
Backend & APIsAuto-check passed
Edgestore Setup
edgestorejs/edgestore
A skill your agent uses when adding, extending, or troubleshooting EdgeStore file uploads, upload UI, or bucket access policies in a TypeScript/React application.
454 GitHub stars~1.8k tokensUpdated today
Backend & APIsAuto-check passed
S3 Explore
duckdb/duckdb-skills
Official
Explore and query data on S3, Cloudflare R2, GCS, MinIO, or any S3-compatible storage.
603 GitHub starsUsed in 1 repo~848 tokens
Backend & APIsAuto-check: notes

Questions about Octo Files

What does Octo Files do?

File operations (upload/download, presigned S3 credentials) plus bot housekeeping (register, set-commands, user-info, space-members, typing, heartbeat). Octo Files is an agent skill from Mininglamp-OSS/octo-cli. File operations (upload/download, presigned S3 credentials) plus bot housekeeping (register, set-commands, user-info, space-members, typing, heartbeat).

When should I use Octo Files?

Octo Files fits situations like: tasks that involve File uploads and storage.

How do I install Octo Files in Claude Code?

Run `npx skills add Mininglamp-OSS/octo-cli --skill octo-files -a claude-code`. Or copy the skill folder (skills/octo-files in Mininglamp-OSS/octo-cli) into .claude/skills/octo-files in your project. Claude Code loads it when a task matches its description.

How do I install Octo Files in Codex?

Run `npx skills add Mininglamp-OSS/octo-cli --skill octo-files -a codex`. Or copy the skill folder (skills/octo-files in Mininglamp-OSS/octo-cli) into .agents/skills/octo-files in your project. Codex loads it when a task matches its description.

Can I use Octo Files 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 Mininglamp-OSS/octo-cli --skill octo-files -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/octo-files, .gemini/skills/octo-files, .github/skills/octo-files and .opencode/skills/octo-files in your project.

What does Octo Files need to run?

Going by SKILL.md and its folder, Octo Files needs the command-line tools its instructions call (jq and curl) and credentials named OCTO_BOT_TOKEN. Our summary lists: A credential in OCTO_BOT_TOKEN.

Does Octo Files access the network?

SKILL.md contains no URLs. Its commands use curl, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Octo Files 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 Octo Files use?

Octo Files 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 Octo Files use?

About 1.6k tokens (SKILL.md is roughly 6.4k 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 Octo Files?

Skills that share tags, products or a category with Octo Files: Stripe Projects (fossasia/eventyay, 1.7k stars), Foundatio (FoundatioFx/Foundatio, 2.1k stars), Spatial (duckdb/duckdb-skills, 603 stars) and R Oop (ab604/claude-code-r-skills, 207 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Octo Files?

Mininglamp-OSS (a GitHub organization) maintains it in Mininglamp-OSS/octo-cli, which has 918 GitHub stars. The repository holds 11 skills in this directory. The repository was last updated on October 10, 2026.

Source: Mininglamp-OSS/octo-cli on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Octo Files

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

octo-files — file I/O and bot housekeeping

1. File operations

upload — multipart form

download — returns a presigned URL

Direct-to-S3 uploads

2. Bot housekeeping

bot register — special auth

Get the owner_uid from bot register

typing and heartbeat

3. Common pattern: message attachment end-to-end

4. Error recovery

5. Schema lookup

Files

Compare with similar skills

Similar skills

More from Mininglamp-OSS/octo-cli

Related

Questions about Octo Files

`upload` — multipart form

`download` — returns a presigned URL

`bot register` — special auth

Get the owner_uid from `bot register`

`typing` and `heartbeat`