Skip to content

スキル名の区切り文字（ハイフン / ドット）を選択可能に #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ysak-y wants to merge 9 commits into
base: main
Choose a base branch
from
Open

スキル名の区切り文字（ハイフン / ドット）を選択可能に #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
8c3e1ac
skills: スキル名の区切り文字（ハイフン / ドット）を選択可能に
ysak-y Jul 17, 2026
aa008d8
v1.4.0
ysak-y Jul 17, 2026
84b1ac5
skills: スキル名のアンダースコアをハイフンに統一
ysak-y Jul 17, 2026
1f67518
install: 区切り文字の選択をインストール時プロンプトに変更
ysak-y Jul 17, 2026
dbdb68f
install: switch_separator.sh と skills_manifest を廃止
ysak-y Jul 17, 2026
9b0d462
config: separator の値を dot / hyphen に変更
ysak-y Jul 17, 2026
e5140eb
tone_guide: スキル・ガイドの原文はドット区切りである旨を明記
ysak-y Jul 17, 2026
9fc08ca
tone_guide: separator が読めない場合はドット区切りをデフォルトとする
ysak-y Jul 17, 2026
55ab7a1
tone_guide: スキル名の表記セクションに断り書きを追加
ysak-y Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,19 @@
# Changelog

## v1.4.0 (2026-07-17)

### New

- **スキル名の区切り文字（ハイフン / ドット）を選択可能に** — 一部の LLM プラットフォームは Agent Skills 準拠のハイフン区切りのスキル名しか使えないため、インストール時にどこでも動作するハイフン区切り（`/miko-setup`、デフォルト）とドット区切り（`/miko.setup`）を選択できるようにした。設定は `.miko/config` の `separator=` に保存され、スキルディレクトリ名とファイル内のスキル名参照（handoffs 含む）がインストール・アップグレード時に自動変換される。後から変更する場合は miko を削除して再インストールする。tone_guide に「出力でスキル名に言及するときは config の separator に従う」を明記

### Changed

- **スキル名のアンダースコアをハイフンに統一** — `miko.new_cap` → `miko.new-cap` のように、スキル名内の `_` を `-` に変更（対象: new-cap / new-harae / quick-catchup / quick-impl / split-proposal / catchup-system-hld）。ハイフン区切り選択時に `miko-new_harae` のような混在表記になるのを避けるため。既存インストールはアップグレード時に旧名スキルが削除され新名で再配置される

### Fixed

- **upgrade.sh が macOS 標準の bash 3.2 で中断する問題を修正** — `.miko/protected_skills` にプロテクト対象がない場合、`set -u` 下での空配列展開により処理が中断していた

## v1.3.2 (2026-06-26)

### Changed
Expand Down
52 changes: 30 additions & 22 deletions README.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,13 @@ Organizing by capability gathers related business rules in one place, which make

### Other design decisions

- **speckit is a surveying tool** — speckit artifacts are disposable. For heavy changes, we use speckit as a device to make Claude read the codebase deeply. Day-to-day implementation goes through `/miko.quick_impl`, without speckit
- **speckit is a surveying tool** — speckit artifacts are disposable. For heavy changes, we use speckit as a device to make Claude read the codebase deeply. Day-to-day implementation goes through `/miko.quick-impl`, without speckit
- **Division of labor between documents** — the rules themselves (conclusions) go in `business_rules.md`; why they were decided (history) goes in proposals

## 🌿 Prerequisites

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) is installed
- (Optional) The [speckit](https://github.com/github/spec-kit) skills — needed only if you use the full flow (`/miko.speckit.*`). Not required for the standard `/miko.quick_impl` flow
- (Optional) The [speckit](https://github.com/github/spec-kit) skills — needed only if you use the full flow (`/miko.speckit.*`). Not required for the standard `/miko.quick-impl` flow

## ✨ Installation

Expand All @@ -70,6 +70,14 @@ The installer asks you to choose an output language (日本語 / English). Your
MIKO_LANG=en bash <(curl -fsSL https://raw.githubusercontent.com/studyplus/miko/main/install.sh)
```

The installer then asks you to choose a skill name separator. Because some LLM platforms only accept [Agent Skills](https://agentskills.io/)-compliant hyphenated names, hyphen-separated names (`/miko-setup`), which work everywhere, are the default. On platforms that support dots in skill names you can choose dots (`/miko.setup`) instead. To change the separator later, remove miko and reinstall:

```bash
rm -rf .claude/skills/miko.* .claude/skills/miko-* .miko # remove, then reinstall
```

Skill names in this README are written with dots. If you use hyphens, read them as `/miko-setup` and so on.

After installation, set up your project:

```bash
Expand Down Expand Up @@ -98,7 +106,7 @@ miko.my-custom-skill
miko.another-skill
```

Protected skills are excluded from upgrades — never removed or overwritten.
Protected skills are excluded from upgrades — never removed or overwritten. If you chose the hyphen separator, write the names hyphenated, e.g. `miko-my-custom-skill`.

### Usage

Expand Down Expand Up @@ -127,11 +135,11 @@ miko/

| File | Role | Maintenance |
|---|---|---|
| `system_high_level_design.md` | System-wide architecture, including the code exploration guide | Generated by `/miko.setup`, kept current by `/miko.catchup_system_hld` |
| `system_high_level_design.md` | System-wide architecture, including the code exploration guide | Generated by `/miko.setup`, kept current by `/miko.catchup-system-hld` |
| `glossary.md` | Term definitions (organized in per-capability sections) | Maintained by miko |
| `business_rules.md` | Domain decision criteria. Records the "why" that cannot be read from code | Maintained by miko |
| `high_level_design.md` | Structure and overview of the capability | Maintained by miko |
| `harae.md` | Findings from adversarial verification, with status tracking | Generated by `/miko.new_harae`, updated by `/miko.harae` |
| `harae.md` | Findings from adversarial verification, with status tracking | Generated by `/miko.new-harae`, updated by `/miko.harae` |
| `proposals/` | Change proposals for the capability and their history | Nushi-sama provides the raw material; written together with miko |

## ⛩️ Skills
Expand All @@ -148,25 +156,25 @@ miko/
| Skill | Purpose |
|---|---|
| `/miko.setup [overview]` | Introduces miko to your project. Surveys the codebase and generates `miko/system_high_level_design.md` |
| `/miko.catchup_system_hld` | Brings `system_high_level_design.md` up to date with the codebase. Detects and fixes directory-structure drift |
| `/miko.catchup-system-hld` | Brings `system_high_level_design.md` up to date with the codebase. Detects and fixes directory-structure drift |

### Document authoring

| Skill | Purpose |
|---|---|
| `/miko.new_cap <capability> [overview]` | Interactively creates business_rules.md and high_level_design.md for a new capability, drawing on existing code where available |
| `/miko.new-cap <capability> [overview]` | Interactively creates business_rules.md and high_level_design.md for a new capability, drawing on existing code where available |
| `/miko.catchup <capability>` | Reconciles existing business_rules.md and high_level_design.md against the full codebase |
| `/miko.quick_catchup <capability> [diff]` | Creates a proposal from a code change (git diff / PR) and updates the BR/HLD. For after emergency fixes, etc. |
| `/miko.quick-catchup <capability> [diff]` | Creates a proposal from a code change (git diff / PR) and updates the BR/HLD. For after emergency fixes, etc. |
| `/miko.propose <capability> [raw material]` | Interactively creates a change proposal |
| `/miko.split_proposal <proposal>` | Splits a proposal into an umbrella (parent) + sub-proposals by phase |
| `/miko.new_harae <capability>` | First adversarial verification of the business rules. Generates harae.md from scratch |
| `/miko.split-proposal <proposal>` | Splits a proposal into an umbrella (parent) + sub-proposals by phase |
| `/miko.new-harae <capability>` | First adversarial verification of the business rules. Generates harae.md from scratch |
| `/miko.harae <capability> [proposal]` | Reviews and extends an existing harae.md. With a proposal, records the findings inside the proposal |

### Implementation (standard flow)

| Skill | Purpose |
|---|---|
| `/miko.quick_impl <proposal \| capability \| change instruction>` | The standard flow: implements changes directly, without speckit. Accepts change instructions without a proposal (refactoring, etc.). Changes to BR text require a proposal. Heavy changes beyond its scope are routed to the full flow |
| `/miko.quick-impl <proposal \| capability \| change instruction>` | The standard flow: implements changes directly, without speckit. Accepts change instructions without a proposal (refactoring, etc.). Changes to BR text require a proposal. Heavy changes beyond its scope are routed to the full flow |

### Implementation (full flow — speckit extensions, for heavy changes)

Expand All @@ -193,10 +201,10 @@ Available only when speckit is installed.
### Defining a new capability

```
/miko.new_cap <capability>
/miko.new-cap <capability>
→ Interactively creates business_rules.md + high_level_design.md

/miko.new_harae <capability>
/miko.new-harae <capability>
→ Adversarially probes the defined rules for contradictions and gaps. Generates harae.md

→ After fixing the findings, re-verification with /miko.harae <capability> is recommended
Expand All @@ -220,14 +228,14 @@ Proceed in three stages: **Propose → Verify → Implement.** Propose gathers t
→ Adversarially verifies the rule set as it would be after the proposal. Findings are recorded in the proposal

# Optional
/miko.split_proposal <proposal>
/miko.split-proposal <proposal>
→ For large changes only, splits into umbrella (parent) + subs by phase (run after harae)
```

**Implementation phase (standard: quick_impl)**
**Implementation phase (standard: quick-impl)**

```
/miko.quick_impl <capability>
/miko.quick-impl <capability>
→ Implements directly, without speckit (for single-intent changes within the existing structure)
→ Afterwards, business_rules.md + high_level_design.md + harae.md are updated automatically
→ If the change exceeds this scope, you are guided to the full flow
Expand Down Expand Up @@ -262,10 +270,10 @@ When a change involves multiple intents, requires exploration to pin down its im

### Refactoring without a proposal

Changes that do not alter business-rule text (renames, moves, redistributing responsibilities, etc.) can be implemented by passing the instruction directly to `/miko.quick_impl`, without a proposal.
Changes that do not alter business-rule text (renames, moves, redistributing responsibilities, etc.) can be implemented by passing the instruction directly to `/miko.quick-impl`, without a proposal.

```
/miko.quick_impl <change instruction>
/miko.quick-impl <change instruction>
→ Afterwards, affected implementation mappings are updated across all capabilities
→ If a BR text change turns out to be needed, you are guided to /miko.propose
→ If the change exceeds the scope (single intent, clear impact, mechanical or local), you are guided to the full flow
Expand All @@ -275,24 +283,24 @@ Changes that do not alter business-rule text (renames, moves, redistributing res

```
# Bring system_high_level_design.md up to date
/miko.catchup_system_hld
/miko.catchup-system-hld
→ Detects directory-structure drift and updates system_high_level_design.md

# Full scan (reconcile the whole capability)
/miko.catchup <capability>
→ Reconciles BR/HLD against the full codebase, detecting and applying differences

# Diff-based (apply a specific code change only)
/miko.quick_catchup <capability>
/miko.quick-catchup <capability>
→ Creates a proposal from the current branch's diff + updates the BR/HLD

/miko.quick_catchup <capability> #8250
/miko.quick-catchup <capability> #8250
→ Creates a proposal from the PR's diff + updates the BR/HLD
```

## 🌾 Quality improvement during implementation

`/miko.quick_impl` (after implementing) and `/miko.speckit.implement` (per feature) automatically run the following self-reviews:
`/miko.quick-impl` (after implementing) and `/miko.speckit.implement` (per feature) automatically run the following self-reviews:

1. **Self-review** -- checks responsibility placement, naming, and framework conventions
2. **/simplify** -- checks for duplication, quality, and efficiency
Expand Down
Loading