# Reorganize Docs

> Reorganize project documentation with bilingual (English/Japanese) structure. Use when asked to "reorganize docs", "update documentation", or "sync documentation". Use when this capability is needed.

- Skill: `tomevault-io/reorganize-docs-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/reorganize-docs-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/reorganize-docs-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/reorganize-docs-2

---


# Reorganize Docs

Reorganize and synchronize project documentation with proper bilingual structure.

## Documentation Structure

```text
/
├── AGENTS.md              # Claude Code guidance (English)
├── README.md              # Project introduction (English)
└── docs/
    ├── AGENTS.ja.md       # Claude Code guidance (Japanese)
    ├── README.ja.md       # Project introduction (Japanese)
    ├── DEVELOPMENT.md     # Development guide (English)
    └── DEVELOPMENT.ja.md  # Development guide (Japanese)
```

## File Purposes

| File                   | Purpose                                       |
| ---------------------- | --------------------------------------------- |
| `AGENTS.md`            | Claude Code guidance: overview, commands      |
| `README.md`            | Project intro: quickstart, prerequisites      |
| `docs/DEVELOPMENT.md`  | Detailed dev guide: services, troubleshooting |

## Cross-link Format

**English files:** Add after the title heading

```markdown
[🇯🇵 日本語版](path/to/file.ja.md)
```

**Japanese files:** Add after the title heading

```markdown
[🇺🇸 English](path/to/file.md)
```

### Cross-link Paths

| English File          | Japanese File             |
| --------------------- | ------------------------- |
| `AGENTS.md`           | `docs/AGENTS.ja.md`       |
| `README.md`           | `docs/README.ja.md`       |
| `docs/DEVELOPMENT.md` | `docs/DEVELOPMENT.ja.md`  |

English files link to Japanese with `[🇯🇵 日本語版](path/to/file.ja.md)`.
Japanese files link to English with `[🇺🇸 English](path/to/file.md)`.

## AGENTS.md Content Requirements

1. **Project Overview**: Purpose and architecture
2. **Development Commands**: Just commands with descriptions
3. **Directory Structure**: Minimal monorepo structure
4. **GitHub Secrets**: Required secrets for CI/CD
5. **Key Technical Decisions**: Stack and tooling choices

## README.md Content Requirements

1. **Project Title and Description**
2. **Prerequisites**: Homebrew, mise, pnpm
3. **Quick Start**: Bootstrap and dev commands
4. **Documentation Links**: Links to detailed docs
5. **License**

## Workflow

1. Read existing documentation files
2. Read `justfile` to extract command documentation
3. Read `.github/workflows/` to extract required GitHub Secrets
4. Generate English `AGENTS.md` with all required sections
5. Generate English `README.md`
6. Create `docs/` directory if not exists
7. Generate Japanese translations (`*.ja.md`)
8. Add cross-links to all files
9. Remove old `DEVELOPMENT.md` from root (if moved to docs/)
10. Run `prek run -a` to verify all linting passes

## Translation Guidelines

- Keep code blocks, commands, file paths, and URLs as-is
- Translate prose content naturally
- Maintain consistent terminology
- Keep table structure identical
- Preserve markdown formatting

## Emoji Guidelines

ドキュメント作成時は絵文字を積極的に使用する:

- 📋 セクション見出しに絵文字を追加
- ✅ リストアイテムや完了項目
- ⚠️ 警告や注意事項
- 💡 Tips やヒント
- 🔧 設定・コマンド関連
- 📁 ファイル・ディレクトリ
- 🚀 Quick Start・Getting Started
- 📖 ドキュメントリンク
- ⚡ パフォーマンス・最適化
- 🔒 セキュリティ関連

## Verification

After completion, run:

```bash
prek run -a
```

All checks must pass before considering the task complete.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/tqer39) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->