# skill-forge
A multilingual workspace for authoring, validating, and distributing reusable AI agent skills.
English · 한국어 · 简体中文
`skill-forge` packages focused workflows as portable `SKILL.md` bundles and installs the correct localized files into Codex, Gemini, Claude Code, Cursor, and GitHub Copilot projects. Each skill can include references, examples, evals, scripts, and agent metadata while keeping its core instructions focused.
## Why skill-forge
- **One source, multiple agents:** install the same skill into each agent's project-local skill directory.
- **Built-in localization:** maintain English, Korean, and Simplified Chinese variants alongside one another.
- **Evidence-backed workflows:** ship validation guidance, deterministic evals, and reusable examples with the skill.
- **Reviewable distribution:** preview every installation with `--dry-run` before copying files.
- **Simple package model:** a skill remains an ordinary directory centered on `SKILL.md`.
## Quick start
Run directly with `npx`:
```bash
# List available skills
npx @bhoon716/skill-forge list --lang en
# Install one skill for Codex or Gemini
npx @bhoon716/skill-forge install bugfix --lang en --agent codex
# Install every skill in Korean to all supported local agent directories
npx @bhoon716/skill-forge install all --lang ko
```
Or install the CLI globally:
```bash
npm install -g @bhoon716/skill-forge
skill-forge
```
Running `skill-forge` without arguments opens the interactive installer.
## Included skills
| Skill | What it does |
| --- | --- |
| [`architecture`](./skills/architecture/) | Compares architecture alternatives, records tradeoffs, and produces ADRs, reviews, system views, and migration plans. |
| [`bugfix`](./skills/bugfix/) | Reproduces or establishes evidence for broken behavior, identifies the root cause, applies the smallest safe fix, and chooses proportionate verification. |
| [`deep-code-review`](./skills/deep-code-review/) | Coordinates independent review lenses, verifies candidate findings, removes root-cause duplicates, and reports confirmed issues. |
| [`feature-dev`](./skills/feature-dev/) | Implements new behavior through a strict Red → Green → Refactor workflow. |
| [`performance-testing`](./skills/performance-testing/) | Measures baseline and candidate performance under controlled conditions, investigates regressions and tradeoffs, and records evidence-backed conclusions. |
| [`refactoring`](./skills/refactoring/) | Improves internal structure through Baseline → Transform → Same Tests while preserving observable behavior. |
| [`ultra-grill-me`](./skills/ultra-grill-me/) | Pressure-tests plans, designs, strategies, research questions, and decisions through one-question-at-a-time Socratic interrogation. |
## Installation targets
| `--agent` | Destination |
| --- | --- |
| `codex`, `gemini` | `./.agents/skills` |
| `claude` | `./.claude/skills` |
| `cursor` | `./.cursor/skills` |
| `copilot` | `./.copilot/skills` |
| `global` | All destinations above |
Supported language codes are `en`, `ko`, and `zh`. English is the default. Use `--dry-run` to inspect source-to-destination mappings without changing files.
```bash
skill-forge install architecture --lang zh --agent claude --dry-run
```
## Repository layout
```text
skill-forge/
├── bin/ # Installer CLI
├── docs/ # Authoring, compatibility, naming, and testing guides
│ └── assets/ # Documentation and branding assets
├── skills/ # Published multilingual skill packages
│ └── /
│ ├── SKILL.md # English default
│ ├── SKILL.ko.md # Korean
│ ├── SKILL.zh.md # Simplified Chinese
│ ├── README*.md # Human-facing documentation
│ └── references/ # Optional supporting material
├── templates/ # Starting points for new skills
└── tests/ # CLI smoke tests
```
Some skills also include `agents/`, `examples/`, `evals/`, `logs/`, or `scripts/` when the workflow requires them.
## Authoring a skill
1. Define one narrow, repeatable job and its trigger boundary.
2. Put routing criteria in the frontmatter `description`.
3. Keep `SKILL.md` focused on non-obvious procedure and decision rules.
4. Move detailed material into `references/` and reusable validation cases into `examples/` or `evals/`.
5. Keep localized suffix pairs intact so the installer can map them correctly.
6. Validate the skill and run the repository tests before publishing.
See the [authoring guide](./docs/authoring-guide.md), [naming rules](./docs/naming.md), [compatibility guide](./docs/compatibility.md), and [testing guide](./docs/testing.md).
## Validation
```bash
# Verify CLI behavior
npm test
# Preview a complete localized installation
node bin/cli.js install all --lang en --agent codex --dry-run
# Run the bundled Ultra Grill evaluator
python3 skills/ultra-grill-me/evals/check_evals.py --run-mock
```
## License
[MIT](./LICENSE)