qshell-copilot

Manage files on Qiniu Cloud Storage (Kodo) via the qshell CLI tool: upload, download, list, delete, copy, move files, CDN refresh/prefetch, and bucket manage...

Security Scan

The skill is an instruction-only wrapper around the qshell CLI for Qiniu Kodo and the instructions, triggers, and references are consistent with that purpose.

Purpose & Capability

Name, description, and all declared artifacts are focused on using the qshell CLI to manage Qiniu Kodo (upload/download/list/delete/CDN/etc.). There are no unrelated environment variables, binaries, or config paths requested.

Instruction Scope

SKILL.md directs the agent to run local qshell commands, check installation and configured accounts, choose upload methods based on file size, and require explicit confirmation before destructive actions. The instructions reference only user files and qshell state needed for the declared tasks and do not instruct reading or exfiltrating unrelated system files or credentials.

Install Mechanism

This is an instruction-only skill with no install spec and no code files; installation guidance (if needed) points to GitHub Releases for qshell, which is an expected and appropriate source.

Credentials

The skill declares no required env vars or credentials. It instructs the user/agent to use qshell's account command to configure AccessKey/SecretKey (which is appropriate for interacting with Qiniu) but does not request unrelated secrets or config paths.

Persistence & Privilege

The skill is not forced-always (always:false) and does not request persistent system-wide privileges or modify other skills. Model invocation is enabled (normal default) but that alone is not a concern given the rest of the footprint.

Assessment

This skill is coherent: it expects the qshell CLI to be present and uses qshell to manage your Qiniu buckets. Before installing or enabling it, confirm you (or your system) have a legitimate qshell binary (the guide points to GitHub Releases), and be prepared to provide or configure your Qiniu AccessKey/SecretKey via qshell (the skill does not harvest secrets itself). Note that the agent will run local qshell commands (e.g., list, upload, delete) on paths you supply — always double-check confirm prompts before destructive actions. If you prefer tighter control, disable autonomous invocation for the skill so it only runs when you explicitly ask.

Qiniu Cloud Storage Management (qshell)

This skill wraps the qshell CLI to let you manage Qiniu Kodo storage through natural language. It handles prerequisite checks, command selection, and result formatting automatically.

Pre-flight Checks

Before executing any storage operation, run these checks in order. The reason for checking every time is that qshell state can change between sessions (uninstalled, credentials expired), and failing silently leads to confusing errors.

1. Installation Check

qshell --version

If this fails, the user doesn't have qshell installed. Stop and guide them through installation (see references/install-guide.md).

2. Authentication Check

qshell user ls

If the output is empty or shows an error, the user needs to configure credentials:

qshell account <AccessKey> <SecretKey> <Name>

Direct them to Qiniu Key Management to get their AK/SK.

3. Proceed with the Request

Once both checks pass, execute the user's request using the command reference below.

Command Reference

Uploading Files

Choose the upload method based on what the user provides:

• Single file, under 100MB: qshell fput [--overwrite] <Bucket> <Key> <LocalFile>
• Single file, 100MB or larger: qshell rput [--overwrite] <Bucket> <Key> <LocalFile> — rput uses resumable upload, so if it fails partway through, re-running the same command resumes from where it left off rather than starting over.
• Entire directory: qshell qupload2 --src-dir=<Dir> --bucket=<Bucket> [--overwrite] [--key-prefix=<Prefix>] [--thread-count=<N>] — if some files fail during batch upload, qupload2 logs failures to a local file. Re-running the same command retries only the failed files.

To decide which to use: check the file size first (ls -lh <file>). If the user points to a directory rather than a file, use qupload2.

Key (remote path) inference: When the user doesn't specify a remote path, use the local filename as the Key. If they mention a remote directory like images/, concatenate it as images/filename.ext.

After a successful upload: Run qshell domains <Bucket> to get the bound domain, then show the user the full access URL: http(s)://<Domain>/<Key>. Prefer CDN domains when multiple domains are available.

Downloading Files

• Single file: qshell get <Bucket> <Key> [-o <SaveAs>]
• Batch download: Requires a config file. See references/batch-download.md for the JSON format.

File Operations

Operation	Command
List files	qshell listbucket2 <Bucket> [--prefix <P>] [--limit <N>] [--marker <M>]
File info	qshell stat <Bucket> <Key>
Delete file	qshell delete <Bucket> <Key>
Copy file	qshell copy <SrcBucket> <SrcKey> <DstBucket> [-k <DstKey>]
Move/rename	qshell move <SrcBucket> <SrcKey> <DstBucket> [-k <DstKey>]

When listing files, use --limit 20 by default to keep output manageable. However, if the user explicitly asks for "all" files or a large number, omit the limit or set a high value to respect their intent.

Before deleting: Always run qshell stat first and show the file details to the user. Wait for explicit confirmation before executing qshell delete. This prevents accidental data loss — deleted files in Kodo cannot be recovered without versioning enabled.

Bucket Management

Operation	Command
List buckets	qshell buckets
Bucket domains	qshell domains <Bucket>
Create bucket	qshell mkbucket <Bucket> --region <Region>

Region values: z0 (East China), z1 (North China), z2 (South China), na0 (North America), as0 (Southeast Asia), cn-east-2 (East China - Zhejiang 2)

CDN and Network

Operation	Command
Fetch URL to bucket	qshell fetch <URL> <Bucket> <Key>
CDN refresh URLs	qshell cdnrefresh -i <file>
CDN refresh dirs	qshell cdnrefresh -r -i <file>
CDN prefetch	qshell cdnprefetch -i <file>
Private download URL	qshell privateurl <PublicUrl> [--deadline <timestamp>]

Error Recovery

When a command fails, diagnose and guide the user rather than just showing the raw error:

Error pattern	What happened	What to do
no such file or directory	Local file path is wrong	Help the user verify the path exists
invalid account / no auth	Credentials missing or expired	Re-run qshell account
no such bucket	Bucket name doesn't exist	Run qshell buckets to show available ones
file exists	Remote file already exists	Ask if they want to add --overwrite
key doesn't exist	Remote key not found	Use qshell listbucket2 to find the correct key
bad token / expired token	Auth token expired	Re-run qshell account
Network timeout	Connectivity issue	Suggest checking network and retrying

Reference Files

• references/install-guide.md — Platform-specific installation instructions (Windows, macOS, Linux)
• references/batch-download.md — JSON config format for qdownload batch downloads

Examples

Example 1: Input: "Upload ./logo.png to my-bucket" Steps: Check file size -> qshell fput my-bucket logo.png ./logo.png -> qshell domains my-bucket -> Return URL

Example 2: Input: "List all jpg files in my-bucket" Steps: qshell listbucket2 my-bucket --limit 100 -> Filter results for .jpg suffix -> Display

Example 3: Input: "Delete old-file.txt from my-bucket" Steps: qshell stat my-bucket old-file.txt -> Show file info -> Wait for user confirmation -> qshell delete my-bucket old-file.txt