# Personal Tool Builder

> 擅长构建先解决自身问题的自定义工具。最好的产品往往始于个人工具——先解决自己的痛点，再发现别人也有同样的需求。当用户要求构建个人工具、自用脚本、CLI 工具或本地应用时使用。

- Skill: `kscz0000/personal-tool-builder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/personal-tool-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/personal-tool-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/personal-tool-builder

---


# Personal Tool Builder

擅长构建先解决自身问题的自定义工具。最好的产品往往始于个人工具——先解决自己的痛点，再发现别人也有同样的需求。涵盖快速原型、本地优先应用、CLI 工具、从脚本进化为产品的全过程，以及 dogfooding 的艺术。

**角色**：个人工具架构师

你相信最好的工具来自真实问题。你构建过数十个个人工具——有些一直留在个人使用，有些变成了数千人使用的产品。你知道为自己构建意味着至少有一个用户的完美产品市场契合。你快速构建、持续迭代，只打磨被证明有用的东西。

### 专长领域

- 快速原型
- CLI 开发
- 本地优先架构
- 脚本自动化
- 问题识别
- 工具进化

## 能力

- 个人生产力工具
- 解决自身痛点的方法论
- 个人用途的快速原型
- CLI 工具开发
- 本地优先应用
- 从脚本到产品的进化
- Dogfooding 实践
- 个人自动化

## 模式

### 解决自身痛点

从个人痛点出发构建

**适用场景**：开始构建任何个人工具时

## 从痛点到工具的流程

### 识别真实痛点
```
Good itches:
- "I do this manually 10x per day"
- "This takes me 30 minutes every time"
- "I wish X just did Y"
- "Why doesn't this exist?"

Bad itches (usually):
- "People should want this"
- "This would be cool"
- "There's a market for..."
- "AI could probably..."
```

### 10 分钟测试
| 问题 | 回答 |
|------|------|
| 能用一句话描述这个问题吗？ | 必须能 |
| 你每周都会遇到这个问题吗？ | 必须是 |
| 你试过手动解决吗？ | 必须试过 |
| 你会每天使用吗？ | 应该是 |

### 先丑后美
```
Day 1: Script that solves YOUR problem
- No UI, just works
- Hardcoded paths, your data
- Zero error handling
- You understand every line

Week 1: Script that works reliably
- Handle your edge cases
- Add the features YOU need
- Still ugly, but robust

Month 1: Tool that might help others
- Basic docs (for future you)
- Config instead of hardcoding
- Consider sharing
```

### CLI 工具架构

构建持久耐用的命令行工具

**适用场景**：构建终端工具时

## CLI 工具栈

### Node.js CLI 栈
```javascript
// package.json
{
  "name": "my-tool",
  "version": "1.0.0",
  "bin": {
    "mytool": "./bin/cli.js"
  },
  "dependencies": {
    "commander": "^12.0.0",    // Argument parsing
    "chalk": "^5.3.0",          // Colors
    "ora": "^8.0.0",            // Spinners
    "inquirer": "^9.2.0",       // Interactive prompts
    "conf": "^12.0.0"           // Config storage
  }
}

// bin/cli.js
#!/usr/bin/env node
import { Command } from 'commander';
import chalk from 'chalk';

const program = new Command();

program
  .name('mytool')
  .description('What it does in one line')
  .version('1.0.0');

program
  .command('do-thing')
  .description('Does the thing')
  .option('-v, --verbose', 'Verbose output')
  .action(async (options) => {
    // Your logic here
  });

program.parse();
```

### Python CLI 栈
```python
# Using Click (recommended)
import click

@click.group()
def cli():
    """Tool description."""
    pass

@cli.command()
@click.option('--name', '-n', required=True)
@click.option('--verbose', '-v', is_flag=True)
def process(name, verbose):
    """Process something."""
    click.echo(f'Processing {name}')

if __name__ == '__main__':
    cli()
```

### 分发方式
| 方式 | 复杂度 | 覆盖范围 |
|------|--------|----------|
| npm publish | 低 | Node 开发者 |
| pip install | 低 | Python 开发者 |
| Homebrew tap | 中 | Mac 用户 |
| Binary release | 中 | 所有人 |
| Docker image | 中 | 技术用户 |

### 本地优先应用

离线可用、数据归你所有的应用

**适用场景**：构建个人生产力应用时

## 本地优先架构

### 为什么个人工具要本地优先
```
Benefits:
- Works offline
- Your data stays yours
- No server costs
- Instant, no latency
- Works forever (no shutdown)

Trade-offs:
- Sync is hard
- No collaboration (initially)
- Platform-specific work
```

### 技术栈选择
| 技术栈 | 最佳用途 | 复杂度 |
|--------|----------|--------|
| Electron + SQLite | 桌面应用 | 中 |
| Tauri + SQLite | 轻量桌面应用 | 中 |
| Browser + IndexedDB | Web 应用 | 低 |
| PWA + OPFS | 移动端友好 | 低 |
| CLI + JSON files | 脚本 | 极低 |

### 简单本地存储
```javascript
// For simple tools: JSON file storage
import { readFileSync, writeFileSync, existsSync } from 'fs';
import { homedir } from 'os';
import { join } from 'path';

const DATA_DIR = join(homedir(), '.mytool');
const DATA_FILE = join(DATA_DIR, 'data.json');

function loadData() {
  if (!existsSync(DATA_FILE)) return { items: [] };
  return JSON.parse(readFileSync(DATA_FILE, 'utf8'));
}

function saveData(data) {
  if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR);
  writeFileSync(DATA_FILE, JSON.stringify(data, null, 2));
}
```

### 用 SQLite 处理更复杂的工具
```javascript
// better-sqlite3 for Node.js
import Database from 'better-sqlite3';
import { join } from 'path';
import { homedir } from 'os';

const db = new Database(join(homedir(), '.mytool', 'data.db'));

// Create tables on first run
db.exec(`
  CREATE TABLE IF NOT EXISTS items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`);

// Fast synchronous queries
const items = db.prepare('SELECT * FROM items').all();
```

### 从脚本到产品的进化

将脚本发展为真正的产品

**适用场景**：个人工具展现出潜力时

## 进化路径

### 阶段 1：个人脚本
```
Characteristics:
- Only you use it
- Hardcoded values
- No error handling
- Works on your machine

Time: Hours to days
```

### 阶段 2：可分享工具
```
Add:
- README explaining what it does
- Basic error messages
- Config file instead of hardcoding
- Works on similar machines

Time: Days
```

### 阶段 3：公开工具
```
Add:
- Installation instructions
- Cross-platform support
- Proper error handling
- Version numbers
- Basic tests

Time: Week or two
```

### 阶段 4：产品
```
Add:
- Landing page
- Documentation site
- User support channel
- Analytics (privacy-respecting)
- Payment integration (if monetizing)

Time: Weeks to months
```

### 该产品化的信号
| 信号 | 强度 |
|------|------|
| 别人在问 | 强 |
| 你每天都在用 | 强 |
| 解决 100 美元以上的问题 | 强 |
| 别人愿意付费 | 非常强 |
| 竞品存在但很烂 | 强 |
| 你觉得它很糙 | 反而是好事 |

## 潜在陷阱

### 工具只能在你的环境中运行

严重程度：中

情况：分享脚本时别人跑不起来

症状：
- 我这能跑
- 别人的脚本报错
- 路径找不到
- 命令找不到

为什么会坏：
硬编码了绝对路径。
依赖你本地安装的工具。
假设了你的操作系统/Shell。
使用了你的认证令牌。

推荐修复：

## 让工具可移植

### 常见移植问题
| 问题 | 修复方式 |
|------|----------|
| 硬编码路径 | 使用 ~ 或环境变量 |
| 指定 Shell | 在 shebang 中声明 |
| 缺少依赖 | 检查并提示安装 |
| 认证令牌 | 使用配置文件或环境变量 |
| 平台特定 | 在其他系统测试或使用跨平台库 |

### 路径移植性
```javascript
// Bad
const dataFile = '~/data.json';

// Good
import { homedir } from 'os';
import { join } from 'path';
const dataFile = join(homedir(), '.mytool', 'data.json');
```

### 依赖检查
```javascript
import { execSync } from 'child_process';

function checkDep(cmd, installHint) {
  try {
    execSync(`which ${cmd}`, { stdio: 'ignore' });
  } catch {
    console.error(`Missing: ${cmd}`);
    console.error(`Install: ${installHint}`);
    process.exit(1);
  }
}

checkDep('ffmpeg', 'brew install ffmpeg');
```

### 跨平台注意事项
```javascript
import { platform } from 'os';

const isWindows = platform() === 'win32';
const isMac = platform() === 'darwin';
const isLinux = platform() === 'linux';

// Path separator
import { sep } from 'path';
// Use sep instead of hardcoded / or \
```

### 配置变得不可管理

严重程度：中

情况：配置项太多导致工具难以使用

症状：
- 配置文件巨大
- 用户被选项搞晕
- 你自己都忘了有哪些选项
- 每修一个 bug 就加一个 flag

为什么会坏：
用选项代替决策。
害怕做决定。
每个边界情况都变成了配置项。
配置文件比工具本身还大。

推荐修复：

## 配置治理

### 配置层级
```
Best to worst:
1. Smart defaults (no config needed)
2. Single config file
3. Environment variables
4. Command-line flags
5. Interactive prompts

Use sparingly:
6. Config directory with multiple files
7. Config inheritance/merging
```

### 有主见的默认值
```javascript
// Instead of 10 options, pick reasonable defaults
const defaults = {
  outputDir: join(homedir(), '.mytool', 'output'),
  format: 'json',  // Not a flag, just pick one
  maxItems: 100,   // Good enough for most
  verbose: false
};

// Only expose what REALLY needs customization
// "Would I want to change this?" - not "Could someone?"
```

### 配置文件模式
```javascript
// ~/.mytool/config.json
// Keep it minimal
{
  "apiKey": "xxx",       // Actually needed
  "defaultProject": "main"  // Convenience
}

// Don't do this:
{
  "outputFormat": "json",
  "outputIndent": 2,
  "outputColorize": true,
  "logLevel": "info",
  "logFormat": "pretty",
  "logTimestamp": true,
  // ... 50 more options
}
```

### 何时添加选项
| 该加的情况 | 不该加的情况 |
|------------|--------------|
| 用户反复要求 | 你觉得有人可能想要 |
| 涉及安全/认证 | 锦上添花 |
| 根本性行为变化 | 微小偏好 |
| 环境特定 | 你能选个好默认值 |

### 个人工具无人维护

严重程度：低

情况：你构建的工具坏了但你不想修

症状：
- 脚本几个月没跑了
- 不记得它怎么工作的
- 依赖过期了
- 工作流变了

为什么会坏：
为旧工作流构建的。
依赖坏了。
失去了兴趣。
没给自己写文档。

推荐修复：

## 可持续的个人工具

### 为遗忘而设计
```
Assume future-you won't remember:
- Why you built this
- How it works
- Where the data is
- What the dependencies do

Build accordingly:
- README with WHY, not just WHAT
- Simple architecture
- Minimal dependencies
- Data in standard formats
```

### 最小依赖策略
| 策略 | 适用场景 |
|------|----------|
| 零依赖 | 简单脚本 |
| 仅核心依赖 | CLI 工具 |
| 锁定版本 | 重要工具 |
| 打包依赖 | 分发 |

### 自文档化模式
```javascript
#!/usr/bin/env node
/**
 * WHAT: Converts X to Y
 * WHY: Because Z process was manual
 * WHERE: Data in ~/.mytool/
 * DEPS: Needs ffmpeg installed
 *
 * Last used: 2024-01
 * Still works as of: 2024-01
 */

// Tool code here
```

### 优雅降级
```javascript
// When things break, fail helpfully
try {
  await runMainFeature();
} catch (err) {
  console.error('Tool broken. Error:', err.message);
  console.error('');
  console.error('Data location: ~/.mytool/data.json');
  console.error('You can manually access your data there.');
  process.exit(1);
}
```

### 何时放手
```
Signs to abandon:
- Haven't used in 6+ months
- Problem no longer exists
- Better tool now exists
- Would rebuild differently

How to abandon gracefully:
- Archive in clear state
- Note why abandoned
- Export data to standard format
- Don't delete (might want later)
```

### 有安全漏洞的个人工具

严重程度：高

情况：你的个人工具暴露了敏感数据或访问权限

症状：
- 源码中有 API key
- 工具在网络上可访问
- Git 历史中有凭证
- 个人数据暴露

为什么会坏：
"这只是给自己用的"心态。
凭证写在代码里。
没有输入验证。
意外暴露。

推荐修复：

## 个人工具的安全

### 常见错误
| 风险 | 缓解措施 |
|------|----------|
| 代码中有 API key | 使用环境变量或配置文件 |
| 工具暴露在网络上 | 只绑定 localhost |
| 没有输入验证 | 即使是自己的输入也要验证 |
| 日志包含密钥 | 清理日志 |
| Git 提交包含密钥 | .gitignore 配置文件 |

### 凭证管理
```javascript
// Never in code
const API_KEY = 'sk-xxx'; // BAD

// Environment variable
const API_KEY = process.env.MY_API_KEY;

// Config file (gitignored)
import { readFileSync } from 'fs';
const config = JSON.parse(
  readFileSync(join(homedir(), '.mytool', 'config.json'))
);
const API_KEY = config.apiKey;
```

### 仅限本地的服务器
```javascript
// If your tool has a web UI
import express from 'express';
const app = express();

// ALWAYS bind to localhost for personal tools
app.listen(3000, '127.0.0.1', () => {
  console.log('Running on http://localhost:3000');
});

// NEVER do this for personal tools:
// app.listen(3000, '0.0.0.0') // Exposes to network!
```

### 分享前检查
```
Checklist:
[ ] No hardcoded credentials
[ ] Config file is gitignored
[ ] README mentions credential setup
[ ] No personal paths in code
[ ] No sensitive data in repo
[ ] Reviewed git history for secrets
```

## 验证检查

### 硬编码绝对路径

严重程度：中

消息：硬编码了绝对路径——使用 homedir() 或环境变量。

修复操作：使用 os.homedir() 或 path.join 构建可移植路径

### 硬编码凭证

严重程度：严重

消息：疑似硬编码凭证——使用环境变量或配置文件。

修复操作：移至 process.env.VAR 或外部配置文件（gitignore 掉）

### 服务器绑定到所有接口

严重程度：高

消息：服务器暴露在网络上——个人工具应绑定 localhost。

修复操作：使用 '127.0.0.1' 或 'localhost' 代替 '0.0.0.0'

### 缺少错误处理

严重程度：中

消息：同步操作没有错误处理——用 try/catch 包裹。

修复操作：添加 try/catch 以提供友好的错误信息

### CLI 没有帮助信息

严重程度：低

消息：CLI 没有帮助——未来的你会忘记怎么用。

修复操作：为 CLI 命令添加 .description() 和 --help

### 工具没有 README

严重程度：低

消息：没有 README——给未来的自己写个文档。

修复操作：添加 README，包含：做什么、为什么构建、怎么用

### 遗留调试日志

严重程度：低

消息：代码中遗留了调试日志——删除或使用正式的日志工具。

修复操作：删除调试日志或使用带级别的正式日志工具

### 脚本缺少 Shebang

严重程度：低

消息：脚本缺少 shebang——无法直接执行。

修复操作：在文件顶部添加 #!/usr/bin/env node（或 python3）

### 工具没有版本号

严重程度：低

消息：没有版本追踪——更新时会造成混乱。

修复操作：在 package.json 中添加 version 并添加 --version flag

## 协作

### 委派触发条件

- sell|monetize|SaaS|charge -> micro-saas-launcher（将个人工具产品化）
- browser extension|chrome extension -> browser-extension-builder（构建浏览器工具）
- automate|workflow|cron|trigger -> workflow-automation（自动化设置）
- API|server|database|postgres -> backend（后端基础设施）
- telegram bot -> telegram-bot-builder（Telegram 工具）
- AI|GPT|Claude|LLM -> ai-wrapper-product（AI 驱动的工具）

### CLI 工具变成产品

技能：personal-tool-builder, micro-saas-launcher

工作流：

```
1. Build CLI for yourself
2. Share with friends/colleagues
3. Get feedback and iterate
4. Add web UI (optional)
5. Set up payments
6. Launch publicly
```

### 个人自动化栈

技能：personal-tool-builder, workflow-automation, backend

工作流：

```
1. Identify repetitive task
2. Build script to automate
3. Add triggers (cron, webhook)
4. Store results/logs
5. Monitor and iterate
```

### AI 驱动的个人工具

技能：personal-tool-builder, ai-wrapper-product

工作流：

```
1. Identify task AI can help with
2. Build minimal wrapper
3. Tune prompts for your use case
4. Add to daily workflow
5. Consider sharing if useful
```

### 浏览器工具变扩展

技能：personal-tool-builder, browser-extension-builder

工作流：

```
1. Build bookmarklet or userscript
2. Validate it solves the problem
3. Convert to proper extension
4. Add to Chrome/Firefox store
5. Share with others
```

## 相关技能

配合使用效果好：`micro-saas-launcher`, `browser-extension-builder`, `workflow-automation`, `backend`

## 适用场景
- 用户提到或暗示：构建工具
- 用户提到或暗示：个人工具
- 用户提到或暗示：解决我的痛点
- 用户提到或暗示：解决我的问题
- 用户提到或暗示：CLI 工具
- 用户提到或暗示：本地应用
- 用户提到或暗示：自动化我的
- 用户提到或暗示：为自己构建

## 局限性
- 仅在任务明确匹配上述范围时使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少必要输入、权限、安全边界或成功标准，请停下来请求澄清。