smart-rules
[Utility] Analyzes user prompts and efficiently loads only relevant rule documents. Auto-generates category-document mapping config file on first invocation by scanning project documents. Supports both automatic and manual invocation. (project)
When & Why to Use This Skill
Smart Rules is an advanced context-optimization skill for Claude that automates the retrieval of project-specific guidelines. By analyzing user prompts and task triggers, it intelligently loads only the relevant documentation—such as coding standards, UI patterns, or architectural rules—ensuring the AI agent remains compliant with local project conventions without exhausting the context window. It features an automated scanning system that maps your project's documentation structure into an actionable configuration on the first run.
Use Cases
- Automated Compliance: Automatically loads 'Coding Conventions' and 'Architecture' rules whenever a user requests a code refactor or a new feature implementation.
- Post-Task Rule Loading: Triggers immediately after a 'TodoWrite' action to analyze the task keywords and provide the AI with the specific documentation needed to complete that specific todo.
- Context Window Optimization: Prevents 'context stuffing' by filtering out irrelevant documents and only injecting the top 5 most pertinent rule files based on the current workflow.
- Project Initialization: Rapidly scans directories like .claude/rules/ or Docs/ to generate a smart-rules.yaml mapping, making legacy documentation instantly accessible to the AI agent.
- Manual Knowledge Retrieval: Allows developers to use commands like '/smart-rules ui' to manually force-load all UI and design-related specifications during a frontend session.
| name | smart-rules |
|---|---|
| description | "[Utility] Analyzes user prompts and efficiently loads only relevant rule documents. Auto-generates category-document mapping config file on first invocation by scanning project documents. Supports both automatic and manual invocation. (project)" |
| user_invocable | true |
Smart Rules
A skill that analyzes user prompts and efficiently loads only relevant rule/guide documents.
Key Features
- Auto-initialization: Scans project documents and auto-generates config file on first invocation
- Config-based: Category-document mapping defined in project-specific
smart-rules.yaml - Efficient loading: Skips if no match, loads only what's needed
- Dual invocation: Auto-execute before tasks or manual
/smart-rulescommand - Post-TodoWrite trigger: Analyzes todo content and loads relevant rules after TodoWrite
⛔ CRITICAL: Auto-Invocation Rules
AI MUST automatically invoke smart-rules in these situations:
1. After TodoWrite Tool Usage
When AI uses the TodoWrite tool, AI MUST invoke smart-rules to analyze the todo content and load relevant rules:
[AI uses TodoWrite tool]
↓
[Analyze todo content keywords]
↓
[Smart Rules] Loaded documents for: [matched categories based on todo content]
Example:
TodoWrite: "Export 다이얼로그 UI 구현"
↓
Keywords: Export, 다이얼로그, UI, 구현
↓
[Smart Rules] Loaded 3 documents for categories: [ui, design, patterns]
- Docs/UX/IA.md
- Docs/UX/DesignSystem/Components.md
- Docs/Patterns/Flutter-Desktop-Window-Management-Pattern.md
Why? 에이전트가 작업할 todo와 관련된 규칙을 미리 숙지하여 올바른 패턴과 컨벤션을 따르도록 합니다.
2. Before Implementation Tasks
When user requests feature implementation, bug fix, or code changes:
[User requests implementation]
↓
[Smart Rules] Analyzing keywords...
[Smart Rules] Loaded documents for: [coding, patterns, ...]
Auto-Invocation Triggers
| Trigger | Action |
|---|---|
| TodoWrite 사용 직후 | Todo 내용 키워드 분석 → 관련 규칙 로드 |
| 구현 요청 | 사용자 요청 키워드 분석 → 관련 규칙 로드 |
| 버그 수정 요청 | 사용자 요청 키워드 분석 → 관련 규칙 로드 |
| 리팩토링 요청 | 사용자 요청 키워드 분석 → 관련 규칙 로드 |
Commands
| Command | Description |
|---|---|
/smart-rules init |
Scan project and generate config file |
/smart-rules rescan |
Delete existing config and rescan |
/smart-rules |
Load documents based on current context |
/smart-rules [category] |
Load specific category documents only |
/smart-rules all |
Load all category documents |
Workflow
1. Initialization (init) - When config file missing
[1. Detect Missing Config]
└─ Check if smart-rules.yaml exists
↓
[2. Scan Project Documents]
└─ Scan standard paths:
- .claude/rules/*.md
- Docs/**/*.md
- .claude/CLAUDE.md, CLAUDE.md
- README.md
↓
[3. Analyze & Categorize]
└─ Classify discovered documents by category
↓
[4. Extract Keywords]
└─ Extract keywords from document titles/headers
↓
[5. Generate Config]
└─ Create smart-rules.yaml file
└─ Report generated config to user
2. Document Loading - When config file exists
[1. Load Config]
└─ Read smart-rules.yaml
↓
[2. Analyze Prompt]
└─ Extract keywords from user prompt
↓
[3. Match Categories]
└─ Match keywords → categories
└─ Check composite categories
↓
[4. Skip if No Match]
└─ Skip if no matches found
↓
[5. Load Documents]
└─ Load matched category documents
└─ Remove duplicates, apply max_documents limit
↓
[6. Report]
└─ Output loaded document list
Auto-categorization Rules
Documents are auto-classified by filename/path patterns during scanning:
| Pattern | Category |
|---|---|
| architecture, arch, structure | architecture |
| coding, convention, style, lint | coding |
| UX, UI, screen, layout, component | ui |
| design, color, theme, typography | design |
| task, todo, backlog | task |
| spec, prd, requirement | spec |
| pattern | patterns |
| security, critical | security |
| others | misc |
Excluded Categories
AI MUST NOT scan or load documents for these categories:
| Pattern | Reason |
|---|---|
| label, labeling | 라벨링 시스템 - 필요시 수동 조회 |
| history | 히스토리 로깅 - 작업 완료 시만 사용 |
| brain, canvas | Brain 캔버스 - 별도 스킬로 관리 |
These files should be excluded from scanning:
.claude/rules/labeling.md.claude/rules/history.mdDocs/Labels/**/*.mdDocs/History/**/*.mdDocs/Brain/**/*
Config File Schema (smart-rules.yaml)
version: 1
# 스캔된 문서 경로 (자동 생성 시 기록)
scanned_paths:
- .claude/rules/
- Docs/
# 옵션
options:
max_documents: 5 # 최대 로드 문서 수
auto_invoke: true # 작업 시작 전 자동 실행 여부
show_loaded_report: true # 로드된 문서 목록 출력 여부
# 카테고리 정의
categories:
category_name:
keywords:
- 키워드1
- keyword2
documents:
- path/to/document1.md
- path/to/document2.md
# 복합 카테고리 (여러 카테고리 조합)
composites:
composite_name:
keywords:
- 복합 키워드
includes:
- category1
- category2
Usage Examples
Example 1: Feature Implementation Request
User: "로그인 화면을 구현해줘"
AI Analysis:
- Keywords: 로그인, 화면, 구현
- Matched: ui, design, coding
[Smart Rules] Loaded 3 documents for categories: [ui, design, coding]
- Docs/UX/IA.md
- Docs/UX/DesignSystem/Components.md
- Docs/Index/CODING_CONVENTIONS.md
Example 2: Specific Category Load
User: "/smart-rules task"
[Smart Rules] Category 'task' loaded:
- .claude/rules/task-management.md
Example 3: No Match
User: "git commit 해줘"
[Smart Rules] No matching rules for this task. Proceeding without rule documents.
Output Format
On Match Success
[Smart Rules] Loaded N documents for categories: [cat1, cat2]
- path/to/doc1.md
- path/to/doc2.md
On No Match
[Smart Rules] No matching rules for this task. Proceeding without rule documents.
On Initialization
[Smart Rules] Initializing...
Scanned paths: .claude/rules/, Docs/
Found N documents across M categories.
Generated: .smart-rules.yaml
Categories created:
- architecture (2 docs)
- coding (2 docs)
- ui (3 docs)
...
Limitations
| Item | Default | Description |
|---|---|---|
| max_documents | 5 | Maximum documents to load at once |
| Keyword matching | Case-insensitive | Supports both Korean and English |
| No config file | Auto init | Auto-initializes if smart-rules.yaml missing |
Config File Location
IMPORTANT: Config file is stored in project root, SEPARATELY from skill definition.
.smart-rules.yaml ← Project-specific config (generated at root)
.claude/skills/smart-rules/SKILL.md ← Skill definition only (do NOT touch)
| File Type | Location | Purpose |
|---|---|---|
| Skill Definition | .claude/skills/smart-rules/SKILL.md |
Read-only skill spec (managed by Droid) |
| Project Config | .smart-rules.yaml (project root) |
Project-specific category mappings |
Why Separate?
- Skill folder is managed by Droid (synced, updated, reset)
- Config file is project-specific and persists across skill updates
- Prevents "folder already exists" conflicts during
init
Init Behavior
/smart-rules initchecks for.smart-rules.yamlin project root- If missing → scans project and creates
.smart-rules.yamlat root - If exists → uses existing config (no conflict with skill folder)
/smart-rules rescandeletes.smart-rules.yamland rescans