ai-nexus 1.5.1 → 1.5.2

package/README.ko.md

@@ -2,14 +2,14 @@
 
 # ai-nexus
 
-> Claude Code는 매 세션마다 모든 규칙을 컨텍스트에 로드합니다.
-> ai-nexus는 필요한 것만 로드하고, Claude, Cursor, Codex 간 규칙을 동기화합니다.
+> 200개 이상의 룰과 스킬을 설치하세요. 프롬프트당 2-3개만 로딩됩니다.
+> 한 번 작성하면 Claude Code, Cursor, Codex에 자동 배포.
 
 [![npm version](https://img.shields.io/npm/v/ai-nexus.svg)](https://www.npmjs.com/package/ai-nexus)
 [![npm downloads](https://img.shields.io/npm/dw/ai-nexus.svg)](https://www.npmjs.com/package/ai-nexus)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**[홈페이지](https://jsk9999.github.io/ai-nexus/)** | **[문서](https://jsk9999.github.io/ai-nexus/docs.html)**
+**[홈페이지](https://jsk9999.github.io/ai-nexus/)** | **[문서](https://jsk9999.github.io/ai-nexus/docs.html)** | **[로드맵](ROADMAP.ko.md)**
 
 ```bash
 npx ai-nexus install
@@ -19,13 +19,17 @@ npx ai-nexus install
 
 ## 문제
 
-AI 코딩 도구마다 룰 형식이 다릅니다 — `.claude/rules/*.md`, `.cursor/rules/*.mdc`, `.codex/AGENTS.md`. 같은 룰을 여러 곳에 관리하다 보면 결국 서로 달라집니다. 게다가 매 프롬프트마다 모든 룰이 로드되어 불필요한 토큰이 낭비됩니다.
+`alwaysApply: true` 룰은 매 프롬프트마다 전부 로딩됩니다 — 많을수록 토큰 낭비가 커집니다. `alwaysApply: false`라도 Claude가 모든 룰의 description을 전부 읽고 뭘 로딩할지 판단합니다 — 코드 작성 대신 룰 필터링에 Claude 토큰을 쓰는 셈입니다. 스킬과 커맨드는 호출할 때만 로딩되지만, 뭘 언제 호출해야 하는지 기억해야 합니다.
 
-[ETH Zurich의 최근 연구](https://arxiv.org/pdf/2602.11988) (12개 레포, 5,694개 PR 대상)가 이를 확인합니다: **모든 룰을 한꺼번에 로드하면 성능이 ~3% 하락하고 비용은 20% 이상 증가합니다.** 사람이 직접 작성한 컨텍스트 파일도 30줄 이하일 때만 4% 개선 효과가 있었습니다. 결론: 프롬프트마다 관련 룰만 로드해야 합니다.
+그래서 대부분 자기검열을 합니다. 관리가 부담되어 룰이나 스킬을 적게 설치하고, 유용한 컨텍스트를 놓치게 됩니다.
+
+[ETH Zurich의 최근 연구](https://arxiv.org/pdf/2602.11988) (12개 레포, 5,694개 PR 대상)가 이를 확인합니다: **모든 룰을 한꺼번에 로드하면 성능이 ~3% 하락하고 비용은 20% 이상 증가합니다.** 결론: 프롬프트마다 관련 컨텍스트만 로드해야 합니다.
+
+게다가 AI 도구마다 형식이 다릅니다 — `.claude/rules/*.md`, `.cursor/rules/*.mdc`, `.codex/AGENTS.md`. 여러 도구를 쓰면 같은 룰과 스킬을 여러 곳에 관리하다 결국 서로 달라집니다.
 
 ## 해결
 
-**ai-nexus**로 룰을 한 번 작성하고 모든 도구에 배포하세요 — 스마트 룰 로딩으로 토큰 낭비도 줄입니다:
+**ai-nexus**는 룰 필터링을 **Claude 바깥에서** 처리합니다. 시맨틱 라우터 훅이 Claude가 시작되기 전에 실행되어 관련 있는 2-3개 파일만 `rules/`에 두고 나머지는 `rules-inactive/`로 물리적으로 빼버립니다. Claude는 나머지가 있는지도 모릅니다. 필터링은 키워드 매칭(무료) 또는 GPT-4o-mini(월 ~$0.50)가 처리. 한 번 작성하면 모든 도구에 배포:
 
 ```
 한 번 작성:
@@ -38,7 +42,7 @@ AI 코딩 도구마다 룰 형식이 다릅니다 — `.claude/rules/*.md`, `.cu
   ✓ Codex        → .codex/AGENTS.md (통합)
 
 하나의 소스. 모든 도구가 동기화됩니다.
-프롬프트마다 필요한 룰만 로딩됩니다.
+200개 이상 설치, 프롬프트당 2-3개만 로딩.
 ```
 
 ---
@@ -47,12 +51,12 @@ AI 코딩 도구마다 룰 형식이 다릅니다 — `.claude/rules/*.md`, `.cu
 
 | | 강점 | 상세 |
 |---|---|---|
-| **필요한 룰만 로드** | 수백 개 룰 중 프롬프트당 2-3개만 선택 | 시맨틱 라우터가 프롬프트를 분석해 관련 룰만 골라 로드합니다. 불필요한 토큰 낭비 제거 → AI 응답 품질 향상 + 비용 절감. |
-| **한 번 작성, 어디서든 배포** | 하나의 룰 파일 → 세 가지 도구 | `.md` 룰 하나만 작성하면 Cursor용 `.mdc`, Codex용 `AGENTS.md`로 자동 변환됩니다. 복붙 불필요. |
-| **AI 기반 룰 선택** | GPT-4o-mini 또는 Claude Haiku가 룰 선택 | 매 프롬프트마다 훅이 실행되어 필요한 룰만 로딩합니다. 월 ~$0.50. AI 없이도 키워드 매칭으로 무료 동작. |
-| **팀 전체 일관성** | Git 기반 룰 공유 | 모든 팀원이 같은 저장소에서 설치. `npx ai-nexus update` 한 번으로 전팀 동기화. |
-| **내 수정은 안전** | 비파괴적 업데이트 | install과 update 모두 로컬 커스터마이징을 절대 덮어쓰지 않습니다. 새 파일만 추가. |
-| **커뮤니티 마켓플레이스** | 브라우저에서 검색, 설치, 제거 | `npx ai-nexus browse`로 로컬 웹 UI를 엽니다. PR merge 즉시 커뮤니티 룰 사용 가능. |
+| **다 설치해도 필요한 것만 로딩** | 200개 이상 설치, 프롬프트당 2-3개만 로딩 | 시맨틱 라우터가 프롬프트를 분석해 필요한 것만 골라 로드 — 룰, 스킬, 커맨드, 에이전트 전부. 설치할 때 자기검열할 필요 없음. |
+| **한 번 작성, 어디서든 배포** | 하나의 파일 → 세 가지 도구 | `.md` 파일 하나만 작성하면 Cursor용 `.mdc`, Codex용 `AGENTS.md`로 자동 변환. 복붙 불필요. |
+| **AI 기반 선택** | GPT-4o-mini 또는 Claude Haiku가 선택 | 매 프롬프트마다 훅이 실행되어 필요한 것만 로딩. 월 ~$0.50. AI 없이도 키워드 매칭으로 무료 동작. |
+| **팀 전체 일관성** | Git 기반 공유 | 모든 팀원이 같은 저장소에서 설치. `npx ai-nexus update` 한 번으로 전팀 동기화. |
+| **내 수정은 안전** | 비파괴적 업데이트 | install과 update 모두 로컬 커스터마이징을 절대 덮어쓰지 않음. 새 파일만 추가. |
+| **커뮤니티 마켓플레이스** | 브라우저에서 검색, 설치, 제거 | `npx ai-nexus browse`로 로컬 웹 UI. 230개 이상의 커뮤니티 룰과 스킬, PR merge 즉시 사용 가능. |
 
 ---
 
@@ -85,9 +89,9 @@ npx ai-nexus install --rules github.com/your-org/team-rules
 
 | 도구 | 동작 방식 | 토큰 부담 |
 |------|-----------|-----------|
-| **Claude Code** | 시맨틱 라우터가 프롬프트마다 동적으로 룰 교체 | 필요한 룰만 로딩 |
-| **Cursor** | 룰을 `.mdc` 형식으로 변환; Cursor 내장 검색이 필터링 | Cursor 검색에 의존 |
-| **Codex** | 집계된 `AGENTS.md` (개별 룰 병합) | 전체 룰 로딩 |
+| **Claude Code** | 시맨틱 라우터가 프롬프트마다 관련 룰과 스킬을 동적 로딩 | 2-3개만 로딩 |
+| **Cursor** | `.mdc` 형식으로 변환; Cursor 내장 검색이 필터링 | Cursor 검색에 의존 |
+| **Codex** | 집계된 `AGENTS.md` (전체 파일 병합) | 전체 로딩 |
 
 ---
 
@@ -95,7 +99,7 @@ npx ai-nexus install --rules github.com/your-org/team-rules
 
 ### Claude Code: 시맨틱 라우터
 
-매 프롬프트마다 훅이 실행되어 실제로 필요한 룰을 분석합니다:
+`alwaysApply: false`는 Claude가 컨텍스트 안에서 모든 description을 읽고 판단합니다. ai-nexus는 Claude가 시작되기 **전에** 훅이 실행되어 관련 파일을 `rules/`로, 나머지를 `rules-inactive/`로 물리적으로 이동시킵니다. Claude는 불필요한 파일을 아예 보지 않습니다:
 
 ```
 ~/.claude/
@@ -112,12 +116,12 @@ export OPENAI_API_KEY=sk-xxx        # 또는 ANTHROPIC_API_KEY
 export SEMANTIC_ROUTER_ENABLED=true
 ```
 
-GPT-4o-mini 또는 Claude Haiku가 프롬프트를 분석해 적절한 룰을 선택합니다. 비용: 월 ~$0.50. 명시적으로 활성화해야 동작합니다.
+GPT-4o-mini 또는 Claude Haiku가 프롬프트를 분석해 적절한 룰과 스킬을 선택합니다. 비용: 월 ~$0.50. 명시적으로 활성화해야 동작합니다.
 
 > **상세 설정 가이드:** [시맨틱 라우터 설정](https://jsk9999.github.io/ai-nexus/docs.html#semantic-router-setup) — 프로바이더 선택, 환경 변수, 커스텀 모델, 동작 확인 방법.
 
 **AI 없이** (기본값):
-프롬프트의 키워드를 매칭해서 룰을 활성화합니다. 비용 없음, API 키 불필요.
+프롬프트의 키워드를 매칭해서 룰과 스킬을 활성화합니다. 비용 없음, API 키 불필요.
 
 ### Cursor: 룰 변환기
 
@@ -398,26 +402,31 @@ node bin/ai-nexus.cjs test "your prompt"
 
 ## FAQ
 
-**Claude Code 스킬(`alwaysApply: false`)이랑 뭐가 다른가요?**
+**나한테 이게 필요해?**
 
-스킬은 이미 Claude Code 안에서 필요할 때만 로딩해줍니다. ai-nexus는 다른 유스케이스를 위한 거예요:
-- **여러 툴** (Claude Code + Cursor + Codex)을 같이 쓰면서 룰을 한 곳에서 관리하고 싶을 때
-- **230개 이상 커뮤니티 룰**을 직접 안 쓰고 바로 가져다 쓰고 싶을 때
-- Claude 대신 **키워드 매칭(무료)** 이나 **더 저렴한 모델**로 라우팅하고 싶을 때
+도구 하나에 룰이나 스킬 몇 개면 굳이 필요 없습니다. 해당 도구 자체 설정으로 충분해요. ai-nexus는 이런 사람들을 위한 거예요:
+- 룰/스킬을 많이 설치하고 효율적으로 로딩하고 싶을 때 (200개 이상 설치, 2-3개만 로딩)
+- **여러 도구** (Claude Code + Cursor + Codex)를 쓰면서 한 곳에서 관리하고 싶을 때
+- **230개 이상 커뮤니티 룰과 스킬**을 직접 안 쓰고 바로 가져다 쓰고 싶을 때
 
-Claude Code만 쓰고 스킬로 충분하면 ai-nexus가 필요 없을 수도 있습니다.
+**스킬만 쓰고 룰은 안 쓰는데, 의미가 있나요?**
 
-**CLAUDE.md나 AGENTS.md에 다 넣으면 되지 않나요?**
+네. 시맨틱 라우터는 스킬, 룰, 커맨드, 에이전트 전부 동일하게 라우팅합니다. 스킬 50개를 깔아도 프롬프트마다 관련 있는 것만 로딩됩니다. "다 설치해도 토큰 걱정 없음"이 스킬에도 똑같이 적용됩니다.
 
-넣을 수는 있지만 규모가 커지면 문제가 됩니다. CLAUDE.md는 뭘 하든 매 프롬프트마다 전부 로드됩니다. 룰이 5개면 괜찮지만, 50개 이상이면 커밋 메시지 쓸 때 Docker best practices까지 같이 로드되는 거예요. [ETH Zurich 연구](https://arxiv.org/pdf/2602.11988)에서도 이게 성능과 비용 둘 다 악화시킨다고 나왔습니다.
+**Claude Code 스킬(`alwaysApply: false`)이랑 뭐가 다른가요?**
+
+스킬은 Claude Code 안에서 온디맨드 로딩을 처리합니다. ai-nexus는 추가로:
+- **크로스 도구 동기화** — 스킬을 Cursor와 Codex에도 배포
+- **더 저렴한 라우팅** — 키워드 매칭(무료) 또는 저렴한 모델로 필터링
+- **커뮤니티 라이브러리** — 230개 이상의 룰과 스킬 바로 사용
 
-ai-nexus는 프롬프트당 관련 있는 2-3개 룰만 로드하고, 나머지는 비활성 상태로 둡니다.
+**CLAUDE.md나 AGENTS.md에 다 넣으면 되지 않나요?**
 
-**Claude Code 스킬 쓰면 룰이 필요 없지 않나요?**
+5개면 괜찮지만 50개 넘으면 커밋 메시지 쓸 때 Docker best practices까지 같이 로드됩니다. [ETH Zurich 연구](https://arxiv.org/pdf/2602.11988)에서도 성능과 비용 둘 다 악화시킨다고 나왔습니다. ai-nexus는 프롬프트당 2-3개만 로드합니다.
 
-스킬은 `/commit`, `/review`처럼 직접 호출하는 작업 워크플로우에 좋습니다. 하지만 룰을 대체하지는 못해요. 룰은 코딩 컨벤션, 보안 기준, 네이밍 패턴처럼 자동으로 적용되는 가이드라인입니다. 코드 짤 때마다 `/security-checklist`를 기억해서 호출할 수는 없잖아요.
+**스킬 vs 룰?**
 
-ai-nexus는 룰과 스킬 둘 다 프롬프트 기반으로 라우팅해서, 직접 호출하지 않아도 필요한 컨텍스트가 자동으로 로드됩니다.
+스킬은 직접 호출하는 워크플로우 (`/commit`, `/review`). 룰은 자동으로 적용되는 패시브 가이드라인 (코딩 컨벤션, 보안 기준, 네이밍 패턴). ai-nexus는 둘 다 프롬프트 기반으로 라우팅 — 뭘 호출할지 기억할 필요 없음.
 
 ---
 

package/README.md

@@ -2,14 +2,14 @@
 
 # ai-nexus
 
-> Claude Code loads all rules into context every session.
-> ai-nexus loads only what you need — and syncs rules across Claude, Cursor, and Codex.
+> Install 200+ rules and skills. Only 2-3 load per prompt.
+> Write once, deploy across Claude Code, Cursor, and Codex.
 
 [![npm version](https://img.shields.io/npm/v/ai-nexus.svg)](https://www.npmjs.com/package/ai-nexus)
 [![npm downloads](https://img.shields.io/npm/dw/ai-nexus.svg)](https://www.npmjs.com/package/ai-nexus)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**[Homepage](https://jsk9999.github.io/ai-nexus/)** | **[Documentation](https://jsk9999.github.io/ai-nexus/docs.html)**
+**[Homepage](https://jsk9999.github.io/ai-nexus/)** | **[Documentation](https://jsk9999.github.io/ai-nexus/docs.html)** | **[Roadmap](ROADMAP.md)**
 
 ```bash
 npx ai-nexus install
@@ -19,13 +19,17 @@ npx ai-nexus install
 
 ## The Problem
 
-Every AI coding tool has its own rule format — `.claude/rules/*.md`, `.cursor/rules/*.mdc`, `.codex/AGENTS.md`. You end up maintaining the same rules in multiple places, and they inevitably drift apart. On top of that, every prompt loads all your rules, wasting tokens on irrelevant context.
+Rules with `alwaysApply: true` load on every prompt — the more you have, the more tokens you waste. With `alwaysApply: false`, Claude reads every rule's description to decide what to load — all your rule descriptions sit in Claude's context while it picks 2-3. You're paying Claude to filter rules instead of writing code. Skills and commands only load when invoked, but that means you have to remember what to call and when.
 
-A [recent study from ETH Zurich](https://arxiv.org/pdf/2602.11988) (12 repos, 5,694 PRs) confirms this: **loading all rules at once hurts performance by ~3% and increases cost by 20%+.** Even hand-written context files only helped by 4% — and only when kept under 30 lines. The takeaway: less is more, and only relevant rules should be loaded per prompt.
+Most people end up self-censoring: only installing a handful of rules or skills to keep things manageable. That means leaving useful context on the table.
+
+A [recent study from ETH Zurich](https://arxiv.org/pdf/2602.11988) (12 repos, 5,694 PRs) confirms this: **loading all rules at once hurts performance by ~3% and increases cost by 20%+.** The takeaway: only relevant context should be loaded per prompt.
+
+On top of that, every AI tool has its own format — `.claude/rules/*.md`, `.cursor/rules/*.mdc`, `.codex/AGENTS.md`. If you use more than one tool, you end up maintaining the same rules and skills in multiple places, and they inevitably drift apart.
 
 ## The Solution
 
-**ai-nexus** lets you write rules once and distribute them across all your tools — while keeping token usage minimal with smart rule loading:
+**ai-nexus** filters rules **before Claude sees them**. A semantic router hook runs on each prompt, picks 2-3 relevant files, and physically parks the rest in `rules-inactive/`. Claude only sees what it needs — it doesn't even know the rest exist. Filtering is done by keyword matching (free) or GPT-4o-mini (~$0.50/month), not by Claude. Write once, deploy across all your tools:
 
 ```
 Write once:
@@ -38,7 +42,7 @@ Deploy everywhere:
   ✓ Codex        → .codex/AGENTS.md (aggregated)
 
 One source of truth. Every tool in sync.
-Only relevant rules loaded per prompt.
+200+ installed, only 2-3 loaded per prompt.
 ```
 
 ---
@@ -47,12 +51,12 @@ Only relevant rules loaded per prompt.
 
 | | Benefit | Detail |
 |---|---|---|
-| **Only relevant rules loaded** | Hundreds of rules installed, only 2-3 loaded per prompt | Semantic Router analyzes your prompt and picks just the rules you need. No unnecessary context = better AI responses + less token waste. |
-| **Write once, deploy everywhere** | One rule file → three tools | Write a single `.md` rule. ai-nexus auto-converts to `.mdc` for Cursor and `AGENTS.md` for Codex. No more copy-pasting. |
-| **AI-powered rule selection** | GPT-4o-mini or Claude Haiku picks rules for you | A hook runs on every prompt, loading only what you need. Costs ~$0.50/month. Falls back to keyword matching with zero cost. |
-| **Team-wide consistency** | Git-based rule sharing | Everyone installs from the same repo. `npx ai-nexus update` keeps the whole team in sync. |
+| **Install everything, load only what's needed** | 200+ rules and skills installed, only 2-3 loaded per prompt | Semantic Router analyzes your prompt and picks just what you need — rules, skills, commands, agents. No more self-censoring what to install. |
+| **Write once, deploy everywhere** | One file → three tools | Write a single `.md` file. ai-nexus auto-converts to `.mdc` for Cursor and `AGENTS.md` for Codex. No more copy-pasting. |
+| **AI-powered selection** | GPT-4o-mini or Claude Haiku picks files for you | A hook runs on every prompt, loading only what you need. Costs ~$0.50/month. Falls back to keyword matching with zero cost. |
+| **Team-wide consistency** | Git-based sharing | Everyone installs from the same repo. `npx ai-nexus update` keeps the whole team in sync. |
 | **Your edits are safe** | Non-destructive updates | Install and update never overwrite your local customizations. Only new files are added. |
-| **Community marketplace** | Browse, install, remove — from your browser | `npx ai-nexus browse` opens a local web UI. Community rules are available instantly after PR merge. |
+| **Community marketplace** | Browse, install, remove — from your browser | `npx ai-nexus browse` opens a local web UI. 230+ community rules and skills available instantly after PR merge. |
 
 ---
 
@@ -85,9 +89,9 @@ npx ai-nexus install --rules github.com/your-org/team-rules
 
 | Tool | How it works | Token overhead |
 |------|--------------|----------------|
-| **Claude Code** | Semantic Router dynamically swaps rules per prompt | Only relevant rules loaded |
-| **Cursor** | Converts rules to `.mdc` format; Cursor's built-in search handles filtering | Depends on Cursor's search |
-| **Codex** | Aggregated `AGENTS.md` (rules merged into single file) | All rules loaded |
+| **Claude Code** | Semantic Router dynamically loads relevant rules and skills per prompt | Only 2-3 files loaded |
+| **Cursor** | Converts to `.mdc` format; Cursor's built-in search handles filtering | Depends on Cursor's search |
+| **Codex** | Aggregated `AGENTS.md` (all files merged into single file) | All files loaded |
 
 ---
 
@@ -95,7 +99,7 @@ npx ai-nexus install --rules github.com/your-org/team-rules
 
 ### Claude Code: Semantic Router
 
-A hook runs on every prompt, analyzing what rules you actually need:
+Unlike `alwaysApply: false` where Claude reads all descriptions inside its context, ai-nexus runs a hook **before** Claude starts. It moves relevant files into `rules/` and parks the rest in `rules-inactive/`. Claude never sees the irrelevant ones:
 
 ```
 ~/.claude/
@@ -112,12 +116,12 @@ export OPENAI_API_KEY=sk-xxx        # or ANTHROPIC_API_KEY
 export SEMANTIC_ROUTER_ENABLED=true
 ```
 
-GPT-4o-mini or Claude Haiku analyzes your prompt and picks the right rules. Cost: ~$0.50/month. Requires explicit opt-in.
+GPT-4o-mini or Claude Haiku analyzes your prompt and picks the right rules and skills. Cost: ~$0.50/month. Requires explicit opt-in.
 
 > **Full setup guide:** [Semantic Router Setup](https://jsk9999.github.io/ai-nexus/docs.html#semantic-router-setup) — provider selection, environment variables, custom models, and verification.
 
 **Without AI** (default):
-Keyword matching activates rules based on words in your prompt. Zero cost, no API key needed.
+Keyword matching activates rules and skills based on words in your prompt. Zero cost, no API key needed.
 
 ### Cursor: Rule Converter
 
@@ -398,26 +402,31 @@ node bin/ai-nexus.cjs test "your prompt"
 
 ## FAQ
 
-**How is this different from Claude Code skills (`alwaysApply: false`)?**
+**Do I actually need this?**
 
-Skills already handle on-demand loading within Claude Code. ai-nexus is for a different use case:
-- You use **multiple tools** (Claude Code + Cursor + Codex) and want one set of rules
-- You want **230+ community rules** without writing everything from scratch
-- You prefer routing via **keyword matching (free)** or a **cheaper model** instead of Claude
+If you use one tool with a few rules or skills, probably not — your tool's built-in settings are enough. ai-nexus is for people who:
+- Install a lot of rules/skills and want them loaded efficiently (200+ installed, 2-3 loaded)
+- Use **multiple tools** (Claude Code + Cursor + Codex) and want one source of truth
+- Want **230+ community rules and skills** without writing everything from scratch
 
-If you only use Claude Code and skills cover your needs, you may not need ai-nexus.
+**I only use skills, not rules. Is this relevant?**
 
-**Why not just put everything in CLAUDE.md or AGENTS.md?**
+Yes. The semantic router handles skills, rules, commands, and agents equally. Install 50 skills and only the relevant ones load per prompt. The "install everything without worrying about tokens" benefit applies to skills just as much as rules.
 
-You can — but it doesn't scale. CLAUDE.md loads on every prompt regardless of what you're doing. With 5 rules, that's fine. With 50+, you're burning tokens on Docker best practices while writing a commit message. The [ETH Zurich study](https://arxiv.org/pdf/2602.11988) shows this hurts both performance and cost.
+**How is this different from Claude Code skills (`alwaysApply: false`)?**
+
+Skills handle on-demand loading within Claude Code. ai-nexus adds:
+- **Cross-tool sync** — deploy skills to Cursor and Codex too, not just Claude Code
+- **Smarter routing** — keyword matching (free) or a cheaper model instead of Claude doing the filtering
+- **Community library** — 230+ rules and skills ready to use
 
-ai-nexus solves this by loading only 2-3 relevant rules per prompt, while keeping the rest parked.
+**Why not just put everything in CLAUDE.md or AGENTS.md?**
 
-**Why not just use Claude Code skills instead of rules?**
+Works fine with 5 files. With 50+, you're burning tokens on Docker best practices while writing a commit message. The [ETH Zurich study](https://arxiv.org/pdf/2602.11988) shows this hurts both performance and cost. ai-nexus loads only 2-3 relevant files per prompt.
 
-Skills are great for on-demand workflows you explicitly invoke (`/commit`, `/review`). But they don't replace rules — rules are passive guidelines that apply automatically (coding conventions, security standards, naming patterns). You shouldn't have to remember to invoke `/security-checklist` every time you write code.
+**Skills vs rules?**
 
-ai-nexus handles both: it routes rules *and* skills based on your prompt, so the right context loads automatically without you thinking about it.
+Skills are workflows you explicitly invoke (`/commit`, `/review`). Rules are passive guidelines that apply automatically (coding conventions, security standards, naming patterns). ai-nexus routes both based on your prompt — no need to remember which to invoke.
 
 ---
 

package/bin/ai-nexus.cjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const { program } = require('commander');
 const path = require('path');

package/config/skills/java-spring.md

@@ -0,0 +1,168 @@
+---
+description: Guidelines for building maintainable Java Spring Boot services and REST APIs using common production patterns
+---
+
+# Java & Spring Boot Development
+
+## Project Structure
+
+Prefer a clear layered structure.
+
+Typical layout:
+
+```
+src/main/java/com/example/app
+├── controller   → HTTP layer
+├── service      → business logic
+├── repository   → persistence
+├── entity       → JPA models
+├── dto          → request/response objects
+└── config       → security and configuration
+```
+
+Avoid putting business logic in controllers.
+
+---
+
+## REST Controller Design
+
+Controllers should only handle HTTP concerns.
+
+Responsibilities:
+
+- validate input
+- call service layer
+- return response objects
+
+Example pattern:
+
+```java
+@RestController
+@RequestMapping("/api/users")
+class UserController {
+
+    private final UserService userService;
+
+    UserController(UserService userService) {
+        this.userService = userService;
+    }
+
+}
+```
+
+Follow standard REST endpoints:
+
+```
+GET /users
+GET /users/{id}
+POST /users
+PUT /users/{id}
+DELETE /users/{id}
+```
+
+Return appropriate HTTP status codes.
+
+---
+
+## Service Layer
+
+Business logic belongs in services.
+
+Guidelines:
+
+- annotate with `@Service`
+- keep controllers thin
+- avoid database code in controllers
+
+Example:
+
+```java
+@Service
+class UserService {
+
+    private final UserRepository repo;
+
+    UserService(UserRepository repo) {
+        this.repo = repo;
+    }
+
+}
+```
+
+---
+
+## Persistence with JPA
+
+Use Spring Data JPA repositories.
+
+Guidelines:
+
+- annotate entities with `@Entity`
+- use `@Id` and generated IDs
+- prefer `FetchType.LAZY` for relations
+- avoid exposing entities directly in APIs
+
+Example:
+
+```java
+@ManyToOne(fetch = FetchType.LAZY)
+```
+
+Use DTOs for responses.
+
+---
+
+## Dependency Injection
+
+Prefer constructor injection.
+
+Good:
+
+```java
+UserService(UserRepository repo)
+```
+
+Avoid:
+
+```java
+@Autowired
+private UserRepository repo;
+```
+
+Constructor injection improves testability.
+
+---
+
+## Configuration
+
+Keep configuration external.
+
+Use:
+
+```
+application.yml
+```
+
+Profiles should separate environments:
+
+- dev
+- test
+- prod
+
+Example configuration:
+
+```yaml
+spring:
+  datasource:
+    url: jdbc:postgresql://localhost:5432/app
+```
+
+---
+
+## General Practices
+
+- keep classes small and focused
+- write meaningful method names
+- use validation annotations for request data
+- handle errors with `@ControllerAdvice`
+- log important application events

package/config/skills/tailwind.md

@@ -0,0 +1,67 @@
+---
+description: Tailwind CSS utility-first styling best practices
+keywords: [tailwind, tailwindcss, css, utility-first, styling]
+---
+
+# Tailwind CSS Best Practices
+
+## When to Apply
+- Styling components with Tailwind utility classes
+- Configuring themes and design tokens
+- Implementing responsive or dark mode layouts
+- Optimizing production CSS output
+
+## Critical Rules
+
+### 1. Utility-First Workflow
+- Compose designs directly in markup with utility classes
+- Avoid premature abstraction — inline utilities first, extract later
+- Follow consistent class ordering: layout → sizing → spacing → typography → visual → state
+- Use official Prettier plugin (`prettier-plugin-tailwindcss`) to auto-sort classes
+
+### 2. Responsive Design
+- Use mobile-first breakpoints: `sm:`, `md:`, `lg:`, `xl:`, `2xl:`
+- Prefer `min-width` breakpoints; use `max-*:` variants sparingly
+- Use container queries (`@container`, `@sm:`, `@lg:`) for component-level responsiveness
+- Group responsive variants logically: `flex flex-col md:flex-row md:items-center`
+
+### 3. Custom Theme Configuration
+- Extend the default theme via `tailwind.config.js` / `tailwind.config.ts`
+- Define design tokens for colors, spacing, and fonts under `theme.extend`
+- Use CSS variables for dynamic theming: `--color-primary` mapped in config
+- Keep config minimal — extend rather than override the defaults
+
+### 4. Component Extraction & @apply
+- Extract only when a pattern repeats ≥ 3 times across files
+- Prefer component abstractions (React, Vue, etc.) over `@apply`
+- If `@apply` is needed, keep rules in a dedicated layer: `@layer components { ... }`
+- Never use `@apply` for one-off styles — use inline utilities instead
+
+### 5. Dark Mode
+- Use `class` strategy for user-controlled toggling: `darkMode: 'class'`
+- Use `media` strategy when OS preference is sufficient
+- Apply dark variants consistently: `bg-white dark:bg-gray-900`
+- Define semantic color tokens that map to light/dark values
+
+### 6. Performance & Production
+- Enable JIT mode (default in Tailwind v3+)
+- Configure `content` paths to include all template files for tree-shaking
+- Avoid dynamic class construction: `bg-${color}-500` — use safelist or full classes
+- Remove unused base/component layers if not needed: `@tailwind base;`
+
+## File Structure
+```
+project/
+  tailwind.config.ts    # Theme, plugins, content paths
+  postcss.config.js     # PostCSS with tailwindcss + autoprefixer
+  src/
+    styles/
+      globals.css       # @tailwind directives, custom @layer rules
+    components/         # UI components using utility classes
+```
+
+## Common Pitfalls
+- Don't use string interpolation for class names — breaks tree-shaking
+- Don't override the entire theme — use `theme.extend` to preserve defaults
+- Don't mix Tailwind utilities with large custom CSS files — pick one approach
+- Don't forget `content` config — missing paths cause styles to be purged

package/dist/utils/config-scanner.js

@@ -48,44 +48,36 @@ function parseFileMeta(filePath) {
     }
 }
 /**
- * Scan a directory for markdown files and extract metadata
+ * Recursively scan a directory for markdown files
  */
-function scanCategoryDir(dir, category) {
-    const files = [];
-    if (!fs.existsSync(dir))
-        return files;
+function scanRecursive(dir, baseDir, category, files) {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-            // Scan subdirectory
-            const subEntries = fs.readdirSync(fullPath, { withFileTypes: true });
-            for (const subEntry of subEntries) {
-                if (!subEntry.isFile() || !subEntry.name.endsWith('.md'))
-                    continue;
-                const subFile = subEntry.name;
-                const subFilePath = path.join(fullPath, subFile);
-                const meta = parseFileMeta(subFilePath);
-                files.push({
-                    name: meta.name,
-                    file: `${entry.name}/${subFile}`,
-                    path: `${category}/${entry.name}/${subFile}`,
-                    description: meta.description,
-                    category,
-                });
-            }
+            scanRecursive(fullPath, baseDir, category, files);
         }
         else if (entry.isFile() && entry.name.endsWith('.md')) {
+            const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
             const meta = parseFileMeta(fullPath);
             files.push({
                 name: meta.name,
-                file: entry.name,
-                path: `${category}/${entry.name}`,
+                file: relativePath,
+                path: `${category}/${relativePath}`,
                 description: meta.description,
                 category,
             });
         }
     }
+}
+/**
+ * Scan a directory for markdown files and extract metadata
+ */
+function scanCategoryDir(dir, category) {
+    const files = [];
+    if (!fs.existsSync(dir))
+        return files;
+    scanRecursive(dir, dir, category, files);
     return files;
 }
 /**

package/dist/utils/semantic-router.js

@@ -249,6 +249,9 @@ const KEYWORD_MAP = {
     'nuxt': { skills: ['vue.md'] },
     'svelte': { skills: ['svelte.md'] },
     'sveltekit': { skills: ['svelte.md'] },
+    'tailwind': { skills: ['tailwind.md'] },
+    'tailwindcss': { skills: ['tailwind.md'] },
+    'utility-first': { skills: ['tailwind.md'] },
     'refactor': { commands: ['refactor.md'] },
     '리팩토링': { commands: ['refactor.md'] },
     'debug': { commands: ['debug.md'], contexts: ['debug.md'] },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-nexus",
-  "version": "1.5.1",
-  "description": "Claude Code loads all rules every session - ai-nexus loads only what you need, syncing rules across Claude, Cursor, and Codex",
+  "version": "1.5.2",
+  "description": "Install 200+ AI coding rules and skills — only 2-3 load per prompt. Write once, deploy across Claude Code, Cursor, and Codex.",
   "main": "dist/index.js",
   "bin": {
     "ai-nexus": "bin/ai-nexus.cjs"