---
sidebar_position: 51
tags: [AI, Generative AI, LLM, Agent, Claude]
---

# Claude Code

## Setup

1. Sync config with `cc-switch`.

```bash
sqlite3 ~/.cc-switch/cc-switch.db "DELETE FROM session_log_sync;"
sqlite3 ~/.cc-switch/cc-switch.db "DELETE FROM skill_repos;"
sqlite3 ~/.cc-switch/cc-switch.db "DELETE FROM skills;"
```

2. Set up `.claude.json`:

```bash
sed -i '0,/{/s/{/{\n  "hasCompletedOnboarding": true,/' ~/.claude.json
```

3. Set up harness:

```bash
claude plugin marketplace add anthropics/claude-plugins-official
claude plugin marketplace add jarrodwatts/claude-hud
claude plugin marketplace add sabertazimi/skills
claude plugin install ralph-loop@claude-plugins-official
claude plugin install superpowers@claude-plugins-official
claude plugin install claude-hud@claude-hud
claude plugin install sabertaz@sabertaz
```

```bash
pnpx skills add anthropics/skills -s skill-creator -a claude-code codex opencode -g -y
pnpx skills add mattpocock/skills -s grill-me grill-with-docs -a claude-code codex opencode -g -y
pnpx skills add vercel-labs/skills -s find-skills -a claude-code codex opencode -g -y
pnpx skills add vercel-labs/agent-skills -s "*" -a claude-code codex opencode -g -y
pnpx skills add multica-ai/andrej-karpathy-skills -s "*" -a claude-code codex opencode -g -y
pnpx skills add nextlevelbuilder/ui-ux-pro-max-skill -s "*" -a claude-code codex opencode -g -y
pnpx skills add upstash/context7 -s find-docs -a claude-code codex opencode -g -y
```

:::tip[Update]

```bash
claude plugin update ralph-loop@claude-plugins-official
claude plugin update superpowers@claude-plugins-official
claude plugin update claude-hud@claude-hud
claude plugin update sabertaz@sabertaz
pnpx skills update
```

:::

:::tip[Proxy]

Optionally set up [`cli-proxy-api`](#proxy) for API proxying.

:::

## Keyboard Shortcuts

[Cheat sheet](https://cc.storyfox.cz):

- `<C-R>`: search history.
- `<C-G>`: open prompt in editor.

## Memory

Captures everything Claude does during your coding sessions, compresses it with Claude `agent-sdk`,
and [injects relevant context](http://github.com/thedotmack/claude-mem) back into future sessions.

## Session

Resume from [session](https://stevekinney.com/courses/ai-development/claude-code-session-management):

```bash
# Most recent session
claude -c

# Specific session
claude -r
claude -r [session_id]
```

## Noninteractive Mode

Use Claude Code as a [Unix-style utility](https://code.claude.com/docs/en/common-workflows#use-claude-as-a-unix-style-utility):

```bash
claude -p "$REVIEW_PROMPT" > review-result.md 2>&1 || true
```

See GitHub [code review action](https://github.com/sabertazimi/blog/pull/1572),
[improved version](https://github.com/sabertazimi/blog/pull/1573),
and [agent-native version](https://github.com/sabertazimi/blog/pull/1574).

:::tip[Composable]

Unix 系统中, 命令行工具通常是独立的、可组合的，
`claude -p` 可以接受标准输入, 并且可以与其他工具无缝集成,
从而形成一个强大的工具链.

:::

## Commands

`.claude/commands/api/api-new.md`:

```md
Create a new POST $ARGUMENTS endpoint with:

- Auth middleware.
- Rate limiting middleware.
- Error handling wrapper.
- TypeScript interfaces for request and response.
```

```bash
/api-new /api/users
```

URL to Markdown [command](../prompt/recipes/url2md.md).

## Skills

```md
<skills_instructions>
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.

How to use skills:
- Invoke skills using this tool with the skill name only (no arguments)
- When you invoke a skill, you will see <command-message>The "{name}" skill is loading</command-message>
- The skill's prompt will expand and provide detailed instructions

IMPORTANT:
- Only use skills listed in <available_skills> below
- Do not invoke a skill that is already running
</skills_instructions>

<available_skills>
<skill>
<name>xlsx</name>
<description>Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis...</description>
<location>plugin</location>
</skill>
</available_skills>
```

```mermaid
---
config:
  flowchart:
    subGraphTitleMargin:
      bottom: 30
---
graph TD
  subgraph Application["应用层<br />(Application Layer)"]
    SKILLS["Agent Skills"]
    KNOWLEDGE["领域知识、工作流、最佳实践"]
  end

  subgraph Transport["传输层<br />(Transport Layer)"]
    MCP["MCP"]
    STD["标准化接口、工具调用、资源访问"]
  end

  subgraph Infrastructure["基础设施层<br />(Infrastructure Layer)"]
    DB[("数据库")]
    API[("API")]
    FS[("文件系统")]
    EXT[("外部服务")]
  end

  SKILLS --> KNOWLEDGE --> MCP --> STD
  STD --> DB & API & FS & EXT

  style Transport fill:#fceacf,color:#333
  style Application fill:#e1eff8,color:#333
  style Infrastructure fill:#d9f0e1,color:#333
```

**渐进式披露**:

- 核心功能简洁: 500 行以内.
- 高级功能分离.
- [按需加载](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work):
  metadata -> instructions -> resources and code.
- Persistent storage + on-demand loading + human-editable.

:::tip[工具选择]

- 临时任务 -> prompts
- 标准作业程序 -> skills
- 连接外部系统 -> MCP
- 复杂独立任务 -> subagents

:::

### Name

Using gerund form [`verb + -ing`](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#naming-conventions):
this clearly describes activity or capability:

- `processing-pdf`
- `analyzing-spreadsheets`
- `managing-databases`
- `testing-code`
- `writing-documentation`

### Description

**核心原则**: 既要说明`做什么`，也要说明`什么时候用`:

```yaml
description: Extract text and tables from PDF files, fill forms, merge documents.
  Use when working with PDF files or when the user mentions PDFs,
  forms, or document extraction.
```

### Patterns

Common skills [patterns](https://claude.com/blog/complete-guide-to-building-skills-for-claude):

- Sequential workflow orchestration.
- Multi-MCP coordination.
- Iterative refinement: [ralph loop](../prompt/recipes/ralph.md), etc.
- Context-aware tool selection.
- Domain-specific intelligence: finance, marketing, math, etc.

### Effective

1. Core quality:
   - [ ] Description is specific and includes key terms
   - [ ] Description includes both what the Skill does and when to use it
   - [ ] SKILL.md body is under 500 lines
   - [ ] Additional details are in separate files (if needed)
   - [ ] No time-sensitive information (or in "old patterns" section)
   - [ ] Consistent terminology throughout
   - [ ] Examples are concrete, not abstract
   - [ ] File references are one level deep
   - [ ] Progressive disclosure used appropriately
   - [ ] Workflows have clear steps
2. Code and scripts:
   - [ ] Scripts solve problems rather than punt to Claude
   - [ ] Error handling is explicit and helpful
   - [ ] No "voodoo constants" (all values justified)
   - [ ] Required packages listed in instructions and verified as available
   - [ ] Scripts have clear documentation
   - [ ] No Windows-style paths (all forward slashes)
   - [ ] Validation/verification steps for critical operations
   - [ ] Feedback loops included for quality-critical tasks
3. Testing:
   - [ ] At least three evaluations created
   - [ ] Tested with Haiku, Sonnet, and Opus
   - [ ] Tested with real usage scenarios
   - [ ] Team feedback incorporated (if applicable)

### Security

1. Code Review:
   - [ ] 所有脚本已审查
   - [ ] 无硬编码密钥或密码
   - [ ] 无危险的系统命令（rm -rf, eval, exec）
   - [ ] 文件路径经过验证（防止路径遍历）
2. Network Access:
   - [ ] 检查所有外部 URL
   - [ ] 验证 API 端点可信
   - [ ] 处理网络失败情况
3. Data Handling:
   - [ ] 无敏感数据泄露
   - [ ] 日志不包含 PII
   - [ ] 临时文件正确清理
4. Permissions:
   - [ ] 最小权限原则
   - [ ] 不请求不必要的文件访问
   - [ ] 明确说明需要的权限
5. Documentation:
   - [ ] 安全注意事项已文档化
   - [ ] 数据处理流程透明
   - [ ] 用户知情同意

```bash
grep -r "requests\." .
grep -r "os.system" .
grep -r "subprocess" .
grep -r "eval" .
```

## Plugins

Install [plugins](https://github.com/anthropics/claude-plugins-official)
from [marketplace](https://code.claude.com/docs/en/plugin-marketplaces),
it will extend Claude Code through the plugin system with:

- Custom commands.
- Agents.
- Hooks.
- Skills.
- MCP servers.

## SDK

- [Code review agent](../prompt/recipes/review.md).

## Proxy

1. Set up `cli-proxy-api`:

```bash
yay -S cli-proxy-api-bin
mkdir -p ~/.cli-proxy-api
cp /usr/share/doc/cli-proxy-api-bin/config.example.yaml ~/.cli-proxy-api/config.yaml
```

```yaml
port: 8317

remote-management:
  secret-key: MGT-123456

api-keys:
  - sk-dummy

usage-statistics-enabled: true
```

2. Set up providers with [Web UI](https://help.router-for.me/cn/hands-on/tutorial-6.html).

3. Set up service:

```bash
systemctl --user enable --now cli-proxy-api.service
```

## Best Practices

Claude code [best practices](https://www.anthropic.com/engineering/claude-code-best-practices):

- Research mode: `deeply`/`intricacies`/`in great details`/`go through everything`.
- Plan mode: 对于复杂的任务, 使用 plan mode 先进行规划, 会比直接执行更高效.
- Extended thinking mode: [`MAX_THINKING_TOKENS`](https://decodeclaude.com/ultrathink-deprecated).
- Claude code has [built-in toolkit](https://code.claude.com/docs/en/settings#tools-available-to-claude),
  follow [certain paradigm](https://www.vtrivedy.com/posts/claudecode-tools-reference) to use them.
- Avoid `/compact`: dump plan and progress + `/clear` the state + restart from dump file.
- Use GitHub [actions](https://github.com/anthropics/claude-code-action):
  code review, issue triage, documentation sync, etc.

## Troubleshooting

### Bug Release

Remove `~/.claude/projects/` for bug release.

### Official Marketplace

`src/hooks/useOfficialMarketplaceNotification.tsx` output
`Failed to install Anthropic marketplace · Will retry on next startup`,
`src/utils/plugins/officialMarketplaceStartupCheck.ts` checks:

- `officialMarketplaceAutoInstallFailReason`
- `officialMarketplaceAutoInstallRetryCount`
- `officialMarketplaceAutoInstallNextRetryTime`

## References

- Skills [best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).
- Skills [cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/skills).
- Skills [specification](https://github.com/agentskills/agentskills).
- `OpenCode` complete [guide](https://github.com/vbgate/learn-opencode).
