balatro-mod-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Balatro Mod Development

Balatro模组开发

Create and debug Balatro mods with Steamodded, Lovely, and SMODS.

使用Steamodded、Lovely和SMODS创建并调试Balatro模组。

Quick Agent Selection

快速选择Agent

When researching, spawn the right agent:

Need to find...	Use agent	Search boundary	Default Backend
Game function implementation	`game-source-researcher`	`Balatro_src/` only	claude
SMODS API usage/hooks	`smods-api-researcher`	`smods/` only	claude
How other mods do X	`mod-pattern-researcher`	`Mods/` folder only	claude
Lovely patch syntax	`lovely-patch-researcher`	lovely files only	claude
Project architecture/exploration	`project-explorer`	Current project only	codex
Run temp script for data	`script-runner`	N/A (execution)	codex
Plan implementation strategy	`strategic-planner`	Current project only	opus
Review code for correctness	`code-reviewer`	Current project only	opus
Synthesize research findings	`research-analyst`	Current project only	opus

Parallel: When researching DIFFERENT sources - spawn multiple agents at once Sequential: When second query depends on first result

⚠️ MANDATORY: Sub-Agent Invocation
ALWAYS use
scripts/run_subagent.sh
to spawn sub-agents. This adapter resolves backend config from
mod.config.json
and routes through codeagent.
DO NOT use built-in agent spawning, direct shell commands, or any other method.
bash
# CORRECT - always use this
./scripts/run_subagent.sh game-source-researcher <<'EOF'
[task content]
EOF

# WRONG - never do this
# spawn_agent(...), create_subagent(...), direct codeagent calls, etc.

See

references/sub-agents.md

for boundaries, workflow patterns, and creating new agents.

进行研究时，选择合适的Agent：

需要查找...	使用Agent	搜索范围	默认后端
游戏功能实现	`game-source-researcher`	仅 `Balatro_src/`	claude
SMODS API用法/钩子	`smods-api-researcher`	仅 `smods/`	claude
其他模组实现X的方式	`mod-pattern-researcher`	仅 `Mods/` 文件夹	claude
Lovely补丁语法	`lovely-patch-researcher`	仅Lovely相关文件	claude
项目架构/探索	`project-explorer`	仅当前项目	codex
运行临时脚本获取数据	`script-runner`	N/A（执行）	codex
规划实现策略	`strategic-planner`	仅当前项目	opus
代码正确性审查	`code-reviewer`	仅当前项目	opus
研究成果整合	`research-analyst`	仅当前项目	opus

并行执行：当研究不同来源时，可同时启动多个Agent 串行执行：当第二个查询依赖第一个查询结果时

⚠️ 强制要求：子Agent调用方式
**必须使用
scripts/run_subagent.sh
**来启动子Agent。该适配器会从
mod.config.json
读取后端配置，并通过codeagent进行路由。
禁止使用内置Agent启动、直接shell命令或其他任何方式。
bash
# 正确方式 - 请始终使用此命令
./scripts/run_subagent.sh game-source-researcher <<'EOF'
[任务内容]
EOF

# 错误方式 - 请勿使用
# spawn_agent(...), create_subagent(...), 直接调用codeagent等

如需了解范围边界、工作流模式及创建新Agent，请查看

references/sub-agents.md

。

Repo Type Awareness

仓库类型识别

Auto-detection: Compare mod manifest

author

with git remote username.

bash

undefined

自动检测：将模组清单中的

author

与Git远程仓库用户名进行比对。

bash

undefined

Get git remote username

获取Git远程仓库用户名

git_user=$(git remote get-url origin 2>/dev/null | sed -E 's|.*://[^/]+.git$|\1|' | tr '[:upper:]' '[:lower:]')

Get mod author from manifest (first author, lowercase)

从模组清单中获取作者（第一个作者，转为小写）

mod_author=$(jq -r '.author[0] // .author // ""' *.json 2>/dev/null | head -1 | tr '[:upper:]' '[:lower:]')

Compare: match = own, no match = fork

比对：匹配则为自有仓库，不匹配则为分叉仓库

[[ "$git_user" == "$mod_author" ]] && echo "own" || echo "fork"


| Type | Detection | Implications |
|------|-----------|--------------|
| `new` | Empty repo (no files) | Full docs, Logger.lua, localization |
| `own` | Author matches git user | Full docs, standardize structure |
| `fork` | Author differs from git user | Minimal changes, temp logs only |

See `templates/project-rules-template.md` for detailed rules per type.

[[ "$git_user" == "$mod_author" ]] && echo "own" || echo "fork"


| 类型 | 检测方式 | 影响 |
|------|-----------|--------------|
| `new` | 空仓库（无文件） | 完整文档、Logger.lua、本地化支持 |
| `own` | 作者与Git用户匹配 | 完整文档、标准化结构 |
| `fork` | 作者与Git用户不匹配 | 最小化修改、仅使用临时日志 |

不同类型仓库的详细规则请查看`templates/project-rules-template.md`。

File Naming Convention (Claude & Codex)

文件命名规范（Claude & Codex）

Both Claude and Codex use the same file structure:

File	Purpose	Git
`INIT.md`	Project rules, constraints for AI agents	ignored
`AGENT.md`	Mod structure, functions, dependencies, dev status (for handover)	ignored
`mod.config.json`	File lists for sync/release scripts	ignored
`docs/knowledge-base.md`	Issues & lessons learned	ignored

AGENT.md Purpose: Enable seamless handover between agents. Another agent should quickly understand mod structure, functions, dependencies, and current development status without losing context.

Claude和Codex使用相同的文件结构：

文件	用途	Git状态
`INIT.md`	AI Agent的项目规则与约束	忽略
`AGENT.md`	模组结构、功能、依赖项、开发状态（用于交接）	忽略
`mod.config.json`	同步/发布脚本的文件列表	忽略
`docs/knowledge-base.md`	问题与经验总结	忽略

AGENT.md用途：实现Agent之间的无缝交接。其他Agent应能快速理解模组结构、功能、依赖项及当前开发状态，无需丢失上下文。

File Placement Rules

文件放置规则

Only these

.md

files belong in root:

```
README.md
```
,
```
README_zh.md
```
```
CHANGELOG.md
```
,
```
CHANGELOG_zh.md
```
```
AGENT.md
```
,
```
INIT.md
```
```
LICENSE.md
```

ALL other
.md
files MUST go in
docs/

仅以下

.md

文件可存放在根目录：

```
README.md
```
,
```
README_zh.md
```
```
CHANGELOG.md
```
,
```
CHANGELOG_zh.md
```
```
AGENT.md
```
,
```
INIT.md
```
```
LICENSE.md
```

所有其他
.md
文件必须放入
docs/
目录

External References (No Symlinks Needed)

外部引用（无需符号链接）

Access reference code directly via absolute paths. No setup required.

可通过绝对路径直接访问参考代码，无需额外设置。

Source Locations (macOS)

资源路径（macOS）

Resource	Path
Game Source (desktop)	`~/Development/GitWorkspace/Balatro_src/desktop/`
Game Source (mobile)	`~/Development/GitWorkspace/Balatro_src/ios_plus/`
Steamodded Source	`~/Development/GitWorkspace/smods/src/`
Steamodded Lovely	`~/Development/GitWorkspace/smods/lovely/`
Lovely Docs	`~/Development/GitWorkspace/lovely-injector/`
Installed Mods	`~/Library/Application Support/Balatro/Mods/`
Lovely Logs	`~/Library/Application Support/Balatro/Mods/lovely/log/`

资源	路径
游戏源码（桌面端）	`~/Development/GitWorkspace/Balatro_src/desktop/`
游戏源码（移动端）	`~/Development/GitWorkspace/Balatro_src/ios_plus/`
Steamodded源码	`~/Development/GitWorkspace/smods/src/`
Steamodded Lovely	`~/Development/GitWorkspace/smods/lovely/`
Lovely文档	`~/Development/GitWorkspace/lovely-injector/`
已安装模组	`~/Library/Application Support/Balatro/Mods/`
Lovely日志	`~/Library/Application Support/Balatro/Mods/lovely/log/`

Source Locations (Windows)

资源路径（Windows）

Resource	Path
Game Source	Varies by setup
Installed Mods	`%APPDATA%/Balatro/Mods/`
Lovely Logs	`%APPDATA%/Balatro/Mods/lovely/log/`

资源	路径
游戏源码	因设置而异
已安装模组	`%APPDATA%/Balatro/Mods/`
Lovely日志	`%APPDATA%/Balatro/Mods/lovely/log/`

Finding Patterns & Examples

查找模式与示例

When you need to find how something is implemented:

What to Find	Where to Search	Command
Game functions	Balatro_src/desktop/	`grep -rn "function Game:start_run" ~/Development/GitWorkspace/Balatro_src/desktop/`
SMODS API usage	smods/src/	`grep -rn "SMODS.Joker" ~/Development/GitWorkspace/smods/src/`
Lovely patch examples	smods/lovely/	`grep -rn "patches.pattern" ~/Development/GitWorkspace/smods/lovely/`
Other mods' implementations	Installed Mods	`grep -rn "pattern" ~/Library/Application\ Support/Balatro/Mods/`
Mobile differences	Balatro_src/ios_plus/	Compare with desktop version

当你需要了解某项功能的实现方式时：

查找内容	搜索位置	命令
游戏函数	Balatro_src/desktop/	`grep -rn "function Game:start_run" ~/Development/GitWorkspace/Balatro_src/desktop/`
SMODS API用法	smods/src/	`grep -rn "SMODS.Joker" ~/Development/GitWorkspace/smods/src/`
Lovely补丁示例	smods/lovely/	`grep -rn "patches.pattern" ~/Development/GitWorkspace/smods/lovely/`
其他模组的实现方式	已安装模组	`grep -rn "pattern" ~/Library/Application\ Support/Balatro/Mods/`
移动端差异	Balatro_src/ios_plus/	与桌面端版本对比

Key Dependencies

核心依赖项

Dependency	Purpose
Steamodded	Core mod loader, SMODS API
Lovely	Lua injection framework
Malverk	Texture pack API (AltTexture, TexturePack)

依赖项	用途
Steamodded	核心模组加载器、SMODS API
Lovely	Lua注入框架
Malverk	纹理包API（AltTexture、TexturePack）

Pattern References

模式参考

Read these files for specific topics:

Topic	Reference File
Lovely.toml syntax	`patterns/lovely-patches.md`
SMODS hooks, config, localization	`patterns/smods-api.md`
Desktop vs mobile differences	`patterns/mobile-compat.md`
UIBox, CardArea, draw order	`patterns/ui-system.md`
Game source file map + search tips	`references/game-files.md`
G.GAME, G.STATES, G.P_* globals	`references/globals.md`
Lua/LuaJIT pitfalls, common mod bugs	`references/lua-gotchas.md`

如需了解特定主题，请阅读以下文件：

主题	参考文件
Lovely.toml语法	`patterns/lovely-patches.md`
SMODS钩子、配置、本地化	`patterns/smods-api.md`
桌面端与移动端差异	`patterns/mobile-compat.md`
UIBox、CardArea、绘制顺序	`patterns/ui-system.md`
游戏源码文件映射 + 搜索技巧	`references/game-files.md`
G.GAME、G.STATES、G.P_*全局变量	`references/globals.md`
Lua/LuaJIT陷阱、常见模组BUG	`references/lua-gotchas.md`

New Mod Setup (type: new)

新模组初始化（类型：new）

Templates in

templates/

folder:

templates/

文件夹中的模板：

File	Purpose
`project-rules-template.md`	INIT.md template (rules)
`agent-md-template.md`	AGENT.md template (repo docs)
`agent-texture-pack-template.md`	AGENT.md for Malverk texture packs
`mod-config-template.json`	Script configuration
`gitignore-template`	Standard .gitignore
`logger-template.lua`	Centralized logging utility

文件	用途
`project-rules-template.md`	INIT.md模板（规则）
`agent-md-template.md`	AGENT.md模板（仓库文档）
`agent-texture-pack-template.md`	Malverk纹理包的AGENT.md模板
`mod-config-template.json`	脚本配置
`gitignore-template`	标准.gitignore
`logger-template.lua`	集中式日志工具

Meta Files:

元文件：

File	Purpose
`mod-json-template.json`	SMODS mod manifest ({ModName}.json)
`manifest-json-template.json`	Thunderstore manifest

文件	用途
`mod-json-template.json`	SMODS模组清单（{ModName}.json）
`manifest-json-template.json`	Thunderstore清单

User Docs in

templates/docs/

templates/docs/

中的用户文档：

File	Purpose
`description-template.md`	Concise README for docs/
`NEXUSMODS_DESCRIPTION-template.txt`	BBCode for NexusMods
`knowledge-base-template.md`	Issues & lessons learned

文件	用途
`description-template.md`	docs目录下的精简README
`NEXUSMODS_DESCRIPTION-template.txt`	NexusMods的BBCode格式文档
`knowledge-base-template.md`	问题与经验总结

Required User Docs (new repos):

必需的用户文档（新仓库）：

Root:
├── README.md, README_zh.md      # Main docs (EN/ZH)
├── CHANGELOG.md, CHANGELOG_zh.md # Version history (EN/ZH)
└── {ModName}.json, manifest.json # Meta files

docs/:
├── description.md               # Concise README
├── NEXUSMODS_DESCRIPTION.txt    # BBCode format
└── knowledge-base.md            # Issues & lessons

根目录:
├── README.md, README_zh.md      # 主文档（英文/中文）
├── CHANGELOG.md, CHANGELOG_zh.md # 版本历史（英文/中文）
└── {ModName}.json, manifest.json # 元文件

docs/:
├── description.md               # 精简版README
├── NEXUSMODS_DESCRIPTION.txt    # BBCode格式文档
└── knowledge-base.md            # 问题与经验总结

Basic Mod Structure (new repos):

基础模组结构（新仓库）：

{ModName}/
├── main.lua                 # Entry point, mod registration
├── config.lua               # Config defaults (optional)
├── lovely.toml              # Lovely patches (if needed)
├── {ModName}.json           # SMODS mod manifest
├── manifest.json            # Thunderstore manifest
├── mod.config.json          # Script configuration
├── Utils/
│   └── Logger.lua           # Centralized logging
├── localization/
│   ├── en-us.lua            # English (required)
│   └── zh_CN.lua            # Chinese
├── assets/                  # Sprites, shaders
├── scripts/                 # Utility scripts
└── docs/                    # Documentation

{ModName}/
├── main.lua                 # 入口文件，模组注册
├── config.lua               # 配置默认值（可选）
├── lovely.toml              # Lovely补丁（如需）
├── {ModName}.json           # SMODS模组清单
├── manifest.json            # Thunderstore清单
├── mod.config.json          # 脚本配置
├── Utils/
│   └── Logger.lua           # 集中式日志工具
├── localization/
│   ├── en-us.lua            # 英文（必需）
│   └── zh_CN.lua            # 中文
├── assets/                  # 精灵图、着色器
├── scripts/                 # 实用脚本
└── docs/                    # 文档

AI Agent Config Templates

AI Agent配置模板

Folder	Contents
`templates/claude-config/`	Claude hooks.json, init command
`templates/codex-config/`	Codex-specific templates (if needed)

文件夹	内容
`templates/claude-config/`	Claude的hooks.json、初始化命令
`templates/codex-config/`	Codex专属模板（如需）

Logging

日志记录

For new/my repos:

自有仓库：

Use

Utils/Logger.lua

(from

templates/logger-template.lua

lua

local Logger = require("Utils.Logger")
local log = Logger.create("ModuleName")
log("info", "Initialized")
log("error", "Failed: " .. err)

使用

Utils/Logger.lua

（来自

templates/logger-template.lua

）：

lua

local Logger = require("Utils.Logger")
local log = Logger.create("ModuleName")
log("info", "Initialized")
log("error", "Failed: " .. err)

For forks/others' repos:

分叉仓库/他人仓库：

Use temp logs only (remove before PR):

lua

pcall(print, "[Debug] checkpoint: " .. tostring(var))

仅使用临时日志（提交PR前需删除）：

lua

pcall(print, "[Debug] checkpoint: " .. tostring(var))

Utility Scripts

实用脚本

Script	Purpose
`scripts/sync_to_mods.template.sh`	Sync mod files to game's Mods folder
`scripts/create_release.template.sh`	Create release packages
`scripts/fix_transparent_pixels.py`	Fix grey borders on sprites
`scripts/mod-scripts-guide.md`	Detailed script usage

脚本	用途
`scripts/sync_to_mods.template.sh`	将模组文件同步至游戏的Mods目录
`scripts/create_release.template.sh`	创建发布包
`scripts/fix_transparent_pixels.py`	修复精灵图的灰色边框
`scripts/mod-scripts-guide.md`	脚本详细使用指南

Workflow: Init Any Existing Repo

工作流：初始化任意现有仓库

For ALL non-empty repos (own or fork), ALWAYS do these first:

Delete
References/
folder if exists (legacy symlink approach)
Move extra
.md
files to
docs/
- only keep in root: README*.md, CHANGELOG*.md, AGENT.md, INIT.md, LICENSE.md
Add dev files (if missing): AGENT.md, INIT.md, mod.config.json, scripts/sync_to_mods.sh

Add Claude config (if missing):

.claude/commands/

.claude/hooks/

.claude/agents/

Add hookify rules (if missing):

.claude/hookify.no-opus-subagents.local.md

(Opus only for reasoning agents),

.claude/hookify.subagent-routing.local.md

Update .gitignore with agent folders

Then for OWN repos: Also check manifest, scripts version (2.0.1), add create_release.sh, Logger.lua

Then for FORK repos: Keep AGENT.md lightweight, use fork-mode INIT.md, don't add release scripts

对于所有非空仓库（自有或分叉），请首先执行以下步骤：

删除
References/
文件夹（如果存在，属于旧版符号链接方式）
将多余的
.md
文件移至
docs/
- 根目录仅保留：README*.md、CHANGELOG*.md、AGENT.md、INIT.md、LICENSE.md
添加开发文件（如缺失）：AGENT.md、INIT.md、mod.config.json、scripts/sync_to_mods.sh

添加Claude配置（如缺失）：

.claude/commands/

、

.claude/hooks/

、

.claude/agents/

添加hookify规则（如缺失）：

.claude/hookify.no-opus-subagents.local.md

（仅Opus用于推理Agent）、

.claude/hookify.subagent-routing.local.md

在.gitignore中添加Agent相关文件夹

自有仓库额外步骤：检查清单、脚本版本（2.0.1）、添加create_release.sh、Logger.lua

分叉仓库额外步骤：保持AGENT.md简洁、使用分叉模式的INIT.md、不添加发布脚本

Workflow: Debugging

工作流：调试

Check
```
references/lua-gotchas.md
```
for known pitfalls (FFI cdata, nil scoping, boolean normalization)
Check platform (desktop vs mobile)
Search game source for function
Check other mods for implementations
Add logs (Logger.lua for own, temp for fork)
Check Lovely logs
If fix fails 3+ times: Document in
```
docs/knowledge-base.md
```

查看
```
references/lua-gotchas.md
```
了解已知陷阱（FFI cdata、nil作用域、布尔值标准化）
检查平台（桌面端vs移动端）
在游戏源码中搜索相关函数
查看其他模组的实现方式
添加日志（自有仓库用Logger.lua，分叉仓库用临时日志）
查看Lovely日志
如果修复失败3次以上：将问题记录在
```
docs/knowledge-base.md
```
中

Workflow: Update User Docs

工作流：更新用户文档

When user says "update all user docs":

Review ALL files: README(_zh).md, CHANGELOG(_zh).md
Review docs/: description.md, NEXUSMODS_DESCRIPTION.txt
Update version in {ModName}.json, manifest.json
Ensure EN/ZH consistency

当用户要求“更新所有用户文档”时：

检查所有文件：README(_zh).md、CHANGELOG(_zh).md
检查docs目录：description.md、NEXUSMODS_DESCRIPTION.txt
更新{ModName}.json、manifest.json中的版本号
确保英文与中文文档内容一致

Workflow: Draft PR Message (fork repos)

工作流：起草PR消息（分叉仓库）

Use

/draft-pr

command. Style: 3-5 sentences, casual tone, what/why/done.

使用

/draft-pr

命令。风格：3-5句话，语气随意，说明做了什么、为什么做、完成了什么。

Sub-Agents for Research

用于研究的子Agent

Main agent handles code. Sub-agents handle information gathering via

scripts/run_subagent.sh

→ codeagent routing.

Shared context: When invoking multiple sub-agents for a task, the main agent must first create

.tmp/[taskname]/task.md

as a shared brief. Sub-agents read it for context and write their artifacts (research.md, analysis.md, plan.md, review.md) to the same directory. See

references/sub-agents.md

→ "Shared Task Context" for the full protocol.

Situation	Use	Default Backend
Research (game, SMODS, mods, lovely)	Research agent	`claude`
Running temp scripts for data	`script-runner`	`codex`
Planning, reviewing, synthesizing	Reasoning agent	`opus`
Writing/editing code	Main agent	—
User interaction needed	Main agent	—

Backends and source paths are configurable in

mod.config.json

agent_backends.research

agent_backends.execution

agent_backends.reasoning

— category defaults

agent_backends.overrides.{agent-name}

— per-agent override (string or

{backend, workdir}

)

```
source_paths
```
— where game source, SMODS, mods are located on this machine

Model restriction: Opus is allowed only for reasoning sub-agents (strategic-planner, code-reviewer, research-analyst). Research agents use Sonnet; execution agents use Haiku.

Hookify enforcement (requires hookify plugin on-site):

```
hookify.no-opus-subagents.local.md
```
— Blocks Opus for non-reasoning agents (allows strategic-planner, code-reviewer, research-analyst)
```
hookify.subagent-routing.local.md
```
— Blocks direct codeagent/route_subagent calls

These are backend hints. Codeagent owns final invocation policy (

~/.codeagent/config.yaml

~/.codeagent/models.json

run_subagent.sh

resolves config and routes through codeagent automatically — no direct

codeagent-wrapper

calls.

See

references/sub-agents.md

for full config resolution, invocation patterns, and parallel examples.

主Agent负责代码处理。子Agent通过

scripts/run_subagent.sh

→ codeagent路由来处理信息收集。

共享上下文：当为某任务启动多个子Agent时，主Agent必须先创建

.tmp/[taskname]/task.md

作为共享任务说明。子Agent会读取该文件获取上下文，并将研究成果（research.md、analysis.md、plan.md、review.md）写入同一目录。完整协议请查看

references/sub-agents.md

→ "Shared Task Context"。

场景	使用方式	默认后端
研究（游戏、SMODS、模组、Lovely）	研究Agent	`claude`
运行临时脚本获取数据	`script-runner`	`codex`
规划、审查、整合	推理Agent	`opus`
编写/编辑代码	主Agent	—
需要用户交互	主Agent	—

后端配置与资源路径可在

mod.config.json

中自定义：

agent_backends.research

agent_backends.execution

agent_backends.reasoning

— 分类默认值

agent_backends.overrides.{agent-name}

— 单个Agent的覆盖配置（字符串或

{backend, workdir}

）

```
source_paths
```
— 当前机器上游戏源码、SMODS、模组的存放路径

模型限制：Opus仅允许用于推理子Agent（strategic-planner、code-reviewer、research-analyst）。研究Agent使用Sonnet；执行Agent使用Haiku。

Hookify强制规则（需现场安装hookify插件）：

```
hookify.no-opus-subagents.local.md
```
— 禁止非推理Agent使用Opus（允许strategic-planner、code-reviewer、research-analyst）
```
hookify.subagent-routing.local.md
```
— 禁止直接调用codeagent/route_subagent

以上为后端提示。最终调用策略由Codeagent决定（

~/.codeagent/config.yaml

、

~/.codeagent/models.json

）。

run_subagent.sh

会自动解析配置并通过codeagent路由 — 无需直接调用

codeagent-wrapper

。

完整的配置解析、调用模式及并行示例请查看

references/sub-agents.md

。

Available Commands

可用命令

```
/familiar
```
- Get familiar with this mod (reads AGENT.md, INIT.md, maps architecture)
```
/init-balatro-mod
```
- Initialize new mod
```
/sync-mod
```
- Start sync with watch mode (run once at start)
```
/bump-version [patch|minor|major]
```
- Increment version, update changelogs
```
/release
```
- Create release packages (auto-detects version from manifests)
```
/fix-sprites <directory> [--preview]
```
- Fix grey borders on sprites
```
/refactor [focus-area]
```
- Review code for redundancy, outdated fallbacks, modularization
```
/debug
```
- Verify fix by checking Lovely logs (auto-detects mod key from repo)
```
/draft-pr
```
- Draft PR message (for forks)
```
/update
```
- Audit project health: scripts, hooks, commands, config, file placement, gitignore
```
/update-docs
```
- Review all docs (user docs + AGENT.md + INIT.md) for accuracy, staleness, duplication, verbosity
```
/update-skill [file|instruction]
```
- Update skill based on new knowledge
```
/knowledge
```
- Review session work, capture discoveries (project-scope → AGENT.md, general → skill)

Sub-agents available after setup:

```
game-source-researcher
```
- Find game functions and injection points
```
smods-api-researcher
```
- Find SMODS API patterns and usage
```
mod-pattern-researcher
```
- Find how other mods implement features
```
lovely-patch-researcher
```
- Find Lovely patch syntax and examples
```
project-explorer
```
- Extensive codebase exploration (uses codex for token efficiency)
```
script-runner
```
- Run temp scripts and return results
```
strategic-planner
```
- Plan implementation strategy (uses opus for deep reasoning)
```
code-reviewer
```
- Review code for correctness and edge cases (uses opus)
```
research-analyst
```
- Synthesize multi-source research findings (uses opus)

```
/familiar
```
- 熟悉当前模组（读取AGENT.md、INIT.md，梳理架构）
```
/init-balatro-mod
```
- 初始化新模组
```
/sync-mod
```
- 启动同步并开启监听模式（启动时运行一次）
```
/bump-version [patch|minor|major]
```
- 递增版本号，更新变更日志
```
/release
```
- 创建发布包（自动从清单中检测版本号）
```
/fix-sprites <directory> [--preview]
```
- 修复精灵图的灰色边框
```
/refactor [focus-area]
```
- 审查代码冗余、过时回退逻辑及模块化情况
```
/debug
```
- 通过查看Lovely日志验证修复效果（自动从仓库中检测模组密钥）
```
/draft-pr
```
- 起草PR消息（适用于分叉仓库）
```
/update
```
- 审计项目健康状态：脚本、钩子、命令、配置、文件放置、gitignore
```
/update-docs
```
- 审查所有文档（用户文档 + AGENT.md + INIT.md）的准确性、时效性、重复性及冗长性
```
/update-skill [file|instruction]
```
- 根据新知识更新技能
```
/knowledge
```
- 回顾会话工作内容，记录新发现（项目范围内容写入AGENT.md，通用内容写入技能）

设置完成后可用的子Agent：

```
game-source-researcher
```
- 查找游戏函数与注入点
```
smods-api-researcher
```
- 查找SMODS API模式与用法
```
mod-pattern-researcher
```
- 查找其他模组的功能实现方式
```
lovely-patch-researcher
```
- 查找Lovely补丁语法与示例
```
project-explorer
```
- 深度探索代码库（使用codex以提高令牌效率）
```
script-runner
```
- 运行临时脚本并返回结果
```
strategic-planner
```
- 规划实现策略（使用opus进行深度推理）
```
code-reviewer
```
- 审查代码正确性与边缘情况（使用opus）
```
research-analyst
```
- 整合多来源研究成果（使用opus）