skills/hermes/cursor-agent-cn/SKILL.md

name, version, description, metadata

name	version	description	metadata
cursor-agent-cn	1.1.0	Run Cursor Agent CLI for coding tasks in China region — writing, editing, refactoring, reviewing, or planning code. Uses --model auto to work around China-region model restrictions. Use when your machine is in mainland China and you need Cursor Agent for coding tasks.	requiredBinaries cursor-agent

Cursor Agent (China Region)

Cursor Agent CLI runs on the user's Cursor subscription — zero API cost. This is the China-region variant that uses --model auto to work around server-side model availability restrictions.

For non-China regions (where you can specify models directly), use the cursor-agent skill instead.

Prerequisites

Required binary: cursor-agent (or the alias agent)

Install: https://cursor.com/docs/cli/overview — verify with cursor-agent --version.

The helper script (scripts/run.sh) will exit with an error if neither cursor-agent nor agent is found in PATH.

Authentication

# Option 1: Environment variable
export CURSOR_API_KEY=crsr_xxxxxxxxxxxxxxxx

# Option 2: Browser login (interactive)
cursor-agent login

# Check status
cursor-agent status

⚠️ China Region: Model Availability

Tested & confirmed in WSL (China mainland, April 2026)

Specifying a model like --model claude-sonnet-4.6 or --model gpt-5.4 will fail:

Model not available — This model provider doesn't serve your region

Setting HTTP_PROXY / SOCKS5 does NOT help. Cursor routes model selection on the server side based on account region, not client IP.

Solution: --model auto

Let Cursor pick whichever model is available in your region:

cursor-agent -p "your task" --model auto --trust

Or simply omit --model — the default is auto.

Trade-off: auto may route to different models across runs, so output quality can vary. Use the two-step workflow below to review before applying changes.

Recommended Workflow: Ask First, Write Second

Because auto mode picks an unpredictable model, always review before applying:

Step 1 — Read-only review (ask mode)

cursor-agent -p "Review this code for bugs and suggest fixes" \
  --model auto --mode=ask --output-format text --trust

Inspect the output. If the suggestions look good, proceed to step 2.

Step 2 — Apply changes (write mode)

cursor-agent -p "Fix the bugs identified above" \
  --model auto --force --output-format text --trust

Headless Mode (Recommended for Automation)

Pipe mode (-p) is more stable than ACP/interactive mode:

cursor-agent -p "<task>" --model auto --mode=ask --output-format text --trust

• Runs non-interactively, returns text output
• Best for subagent integration and scripted pipelines
• Avoids the "Connection stalled" issues seen in ACP/interactive mode

Command Quick Reference

Scenario	Command
Code review	cursor-agent -p "Review..." --model auto --mode=ask --trust
Write code / fix bug	cursor-agent -p "Fix..." --model auto --force --trust
Planning / design	cursor-agent -p "Plan..." --model auto --mode=plan --trust
Check version	cursor-agent --version
Check auth status	cursor-agent status

Helper Script

Use scripts/run.sh for standardized invocation:

bash scripts/run.sh /path/to/repo "Review the auth module" auto ask
bash scripts/run.sh /path/to/repo "Fix the auth bug" auto write
TIMEOUT=300 bash scripts/run.sh /path/to/repo "Refactor utils" auto write

Arguments: <repo_path> <task> [model] [mode]

• model: auto (default) — always use auto in China region
• mode: ask (default, read-only) | plan | write (applies changes)

Git Rule

Cursor's sandbox blocks git commit. After Cursor edits files, commit manually:

git add -A && git commit -m "feat: description of changes"

Always review the diff before committing.

Known Issues

Issue	Details
Region-locked models	Server-side restriction; proxies don't help. Use --model auto.
Connection stalled	ACP/interactive mode may hang. Use headless -p mode instead.
Inconsistent output	auto may route to different models each run. Review before applying.
Sandbox git block	Cursor sandbox prevents git commit. Commit manually after edits.

Gitea Integration

Cursor Agent can access git.shazhou.work via the tea CLI (pre-configured login: xingyue). Global rules at ~/.cursor/rules/gitea-access.mdc teach it how to use tea.

When assigning issue-related tasks, tell cursor to read the issue first:

"Read issue #3 with `tea issues 3`, then implement the changes described."

Context Tips

• Add @<file> in your prompt to include specific files in context
• Use --continue or --resume to continue a previous session
• ~/.cursor/rules/ contains global rules loaded for all projects (e.g. gitea-access)