Smart Rules is a high-efficiency context management utility designed to optimize AI agent performance by dynamically loading only the most relevant project-specific guidelines. It solves the problem of context window clutter and 'instruction drift' by scanning project directories, auto-categorizing documentation, and injecting precise rules based on real-time prompt analysis. This ensures the agent consistently adheres to your project's unique coding standards, architectural patterns, and UI/UX requirements without manual overhead.

When should I use smart-rules?

smart-rules is useful in the following scenarios: • Post-Task Analysis: Automatically triggers after using a 'TodoWrite' tool to analyze the task content and load relevant documentation (e.g., loading UI components rules when the task mentions 'dialog implementation'). • Project Onboarding: Automatically scans a new codebase on the first run to generate a 'smart-rules.yaml' mapping, instantly organizing scattered .md files into actionable rule categories. • Context Window Optimization: Prevents the AI from becoming overwhelmed by large documentation sets by filtering and loading only the top-priority documents that match the current user intent. • Enforcing Coding Standards: Ensures that during refactoring or feature implementation, the agent proactively loads 'coding' or 'architecture' rules to maintain consistency with the existing codebase. • Manual Rule Governance: Provides developers with slash commands like '/smart-rules [category]' to manually force the agent to focus on specific sets of rules during complex debugging or security audits.

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-rules command
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`

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 init checks for .smart-rules.yaml in project root
If missing → scans project and creates .smart-rules.yaml at root
If exists → uses existing config (no conflict with skill folder)
/smart-rules rescan deletes .smart-rules.yaml and rescans

smart-rules

When & Why to Use This Skill

Use Cases