project-rules

어떤 스킬인가요?

Use when the user wants to understand or configure skill routing logic, create IDE-specific rule files, set up conditional skill loading, or customize how skills are automatically invoked. Also use when troubleshooting skill loading issues or when working with IDE rule templates. Do NOT use for general IDE configuration unrelated to skill routing.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

---
name: project-rules
description: >
  Use when the user wants to understand or configure skill routing logic, create IDE-specific
  rule files, set up conditional skill loading, or customize how skills are automatically
  invoked. Also use when troubleshooting skill loading issues or when working with IDE
  rule templates. Do NOT use for general IDE configuration unrelated to skill routing.
---

# Project Rules

## When to Invoke
- User asks about skill routing logic or how skills are automatically loaded
- User wants to customize IDE rule generation
- User is troubleshooting skill loading issues
- User mentions conditional skill loading or file-based triggers
- User wants to understand the templates in project-rules/templates/
- User asks how to prevent skills from loading when not needed
- NOT: General IDE setup unrelated to skill routing
- NOT: Installing or managing skills themselves

## Prerequisites
This skill is typically invoked by the `setup` skill but can be used independently for customization.

## Reference

This skill contains the core routing logic and templates that enable automatic skill loading based on project context. The goal is **zero manual skill invocation** - skills should load automatically when relevant and stay out of the way when not needed.

### Core Routing Principles

1. **Conditional Loading**: Language skills only load when working with files of that language
2. **File Type Triggers**: Document skills load based on file extensions
3. **Universal Rules**: Some rules (like "read SKILL.md before coding") apply everywhere
4. **Single Source of Truth**: All logic is defined once in templates, then generated for each IDE
5. **Modular Installation**: Skills can be installed independently from different branches
6. **Additive Configuration**: New skills integrate without affecting existing ones
7. **Skill Detection**: Setup automatically scans for installed skills and configures accordingly

### Routing Logic

The templates implement this trigger hierarchy:

#### File Type Triggers (Always Apply)
```
.docx files → skills/docx/SKILL.md
.pdf files → skills/pdf/SKILL.md  
.pptx files → skills/pptx/SKILL.md
.xlsx files → skills/xlsx/SKILL.md
Uploaded files not in context → skills/file-reading/SKILL.md (load first)
```

#### Language Triggers (Conditional - Only When Primary Language)
```
.go, go.mod, go.sum → skills/go/SKILL.md
.py files → skills/python/SKILL.md
.ts, .tsx files → skills/typescript/SKILL.md
.rs files → skills/rust/SKILL.md
```

#### Framework & Technology Triggers (Conditional - When Working with Specific Tech)
```
React components, JSX → skills/react/SKILL.md
Auth directories, login flows → skills/auth/SKILL.md  
Dockerfile, docker-compose → skills/docker/SKILL.md
Kubernetes manifests → skills/kubernetes/SKILL.md
Terraform files → skills/terraform/SKILL.md
```

#### Universal Rules (Always Apply)
```
- Read relevant SKILL.md BEFORE writing any code or creating any file
- Never skip skill loading even for "simple" versions of covered tasks
```

### IDE-Specific Implementation

Each IDE has different syntax for conditional loading:

#### Cursor (.cursor/rules/*.mdc)
- **Split into multiple files**: One per trigger group
- **Use `globs` + `alwaysApply: false`** for language rules
- **Only universal rules use `alwaysApply: true`**
- **Keep universal rules under 10 lines**

Example structure:
```
.cursor/rules/
├── universal.mdc (alwaysApply: true, <10 lines)
├── go.mdc (globs: ["**/*.go"], alwaysApply: false)
├── python.mdc (globs: ["**/*.py"], alwaysApply: false)
└── typescript.mdc (globs: ["**/*.ts", "**/*.tsx"], alwaysApply: false)
```

#### Claude Code (CLAUDE.md)
- **Single file at root** with routing logic
- **Keep under 80 lines total**
- **Language rules go in separate `.claude/rules/<lang>.md` files**
- **Reference skills/ directory for SKILL.md files**

#### Windsurf (.windsurf/rules/skills.md)
- **Single markdown file** with conditional syntax
- **Use Windsurf-specific conditional formatting**

#### GitHub Copilot (.github/copilot-instructions.md)
- **Append to existing file** if present
- **Use GitHub Copilot instruction format**
- **Include file pattern matching**

### Template Structure

Each template in `templates/` contains:

1. **IDE-specific header/frontmatter** (if required)
2. **Universal rules** (always active)
3. **File type triggers** (document processing)
4. **Language triggers** (conditional on file patterns)
5. **Skill reference paths** pointing to skills/ directory

### Template Rendering Process

When `setup` skill runs:

1. **Scan installed skills**: Check which `skills/<name>/SKILL.md` files exist
2. **Detect IDE**: Check for IDE-specific directories/files
3. **Render base template**: Replace {SKILL_LIST} with detected skills
4. **Create modular files**: Generate separate config files per skill (for Cursor/Claude Code)
5. **Write to targets**: Place files in IDE-expected locations
6. **Create directories**: Make parent directories if needed
7. **Handle conflicts**: Merge with existing files rather than overwrite

### Versioned Skill Architecture

This design supports mixed skill installation with version selection:

```bash
# Primary installation with version picker
npx skills add Krushnal121/agentic
# Shows: ☑ go (1.26 - latest, enterprise patterns) ☑ python (3.12 - latest) etc.

# Direct version installation (for specific requirements)
npx skills add https://github.com/Krushnal121/agentic/skills/go/1.25

# Mix different versions as needed
# Install Go 1.26, Python 3.11, React 17 - all work together

# Re-run setup to detect new skills and versions
```

**Result**: All skills and versions work independently without conflicts:
- **Cursor gets**: `agentic-go-1.26.mdc`, `agentic-python-3.12.mdc`, `agentic-react-18.mdc`
- **Claude Code gets**: Individual `.claude/rules/agentic-{skill}-{version}.md` files for each
- **Universal rules**: Stay consistent across all skill types and versions
- **Trigger patterns**: Each skill version defines its own file patterns and trigger conditions

### Skill Type Examples

The system supports any skill type with appropriate trigger patterns:

| Skill Type | Version Example | Trigger Patterns | Use Case |
|------------|----------------|------------------|----------|
| **Language** | `go/1.26` | `*.go`, `go.mod`, `go.sum` | Version-specific language features |
| **Framework** | `react/18` | `*.jsx`, `*.tsx`, `components/**` | Framework-specific patterns |
| **Auth** | `auth/oauth2` | `**/auth/**`, `**/*oauth*`, login flows | Authentication implementation |
| **Infrastructure** | `docker/24` | `Dockerfile`, `docker-compose*` | Container orchestration |
| **Database** | `postgres/15` | `*.sql`, migrations, schema files | Database-specific patterns |

### Customization

To customize routing for your project:

1. **Modify templates**: Edit files in `skills/project-rules/templates/`
2. **Re-run setup**: Execute setup skill to regenerate IDE files
3. **Test loading**: Verify skills load only when expected

### Debugging Skill Loading

If skills aren't loading as expected:

1. **Check file patterns**: Ensure your files match the glob patterns
2. **Verify IDE rules**: Confirm the rule file exists in the right location
3. **Test conditions**: Check if the trigger conditions are met
4. **Review logs**: Look for IDE-specific skill loading messages

### Adding New IDEs

To support a new IDE:

1. **Create template**: Add new template in `templates/` directory
2. **Update setup skill**: Add IDE detection logic
3. **Define target path**: Specify where the IDE expects rule files
4. **Test integration**: Verify skill loading works with new IDE

## Constraints

- Templates must use conditional loading for language skills (not always-on)
- Universal rules should be minimal and under 10 lines where possible
- Never duplicate skill content between templates and SKILL.md files
- Templates reference skills/ directory, never embed skill content
- All templates must be IDE-agnostic content delivered through IDE-specific wrappers
- Language skills only load when that language is the primary focus of the task
- File type skills load whenever those file types are involved
- Keep template complexity minimal - prefer simple pattern matching over complex logic

# Agentic Skills - Auto-Loading Rules

This file enables automatic skill loading based on your project context. Skills are loaded conditionally to minimize context overhead while ensuring the right expertise is available when needed.

## Universal Rules (Always Active)

- **ALWAYS** read the relevant `skills/<skill-name>/SKILL.md` BEFORE writing any code or creating any file (if the skill exists)
- **NEVER** skip skill loading even for "simple" versions of covered tasks
- Skills contain critical patterns, constraints, and best practices for their domain

## File Type Triggers (When Skills Are Installed)

When working with these file types, the corresponding skill loads automatically if installed:

- **Word documents** (`.docx`) → Load `skills/docx/SKILL.md` (if exists)
- **PDF files** (`.pdf`) → Load `skills/pdf/SKILL.md` (if exists)
- **Presentations** (`.pptx`) → Load `skills/pptx/SKILL.md` (if exists)
- **Spreadsheets** (`.xlsx`) → Load `skills/xlsx/SKILL.md` (if exists)
- **Uploaded files** not yet in context → Load `skills/file-reading/SKILL.md` (if exists)

## Language-Specific Rules

Language skills are stored in separate `.claude/rules/agentic-<lang>-<version>.md` files to avoid bloating this root file. The setup skill creates these files only for installed skills with their specific versions.

**Installed Skills with Versions** (setup detects these automatically):
{SKILL_LIST}

## Versioned Skill Installation

This configuration supports mixed skill and version installation:
- Install Go 1.26: Gets `.claude/rules/agentic-go-1.26.md`
- Install Python 3.12: Gets `.claude/rules/agentic-python-3.12.md`
- All skills and versions work independently without conflicts

## How It Works

1. **Conditional Loading**: Language skills only activate when you're primarily working with that language
2. **Context Optimization**: Only installed skills load, keeping context lean and focused
3. **Expertise On-Demand**: The right domain knowledge appears exactly when needed
4. **Zero Manual Invocation**: You never need to say "use the go skill" - it just works
5. **Additive Installation**: New skills integrate seamlessly with existing ones

## Troubleshooting

If a skill isn't loading when expected:

1. Check that you're working with files of the expected type/extension
2. Ensure the skill file exists at `skills/<skill-name>/SKILL.md`
3. Verify the language is the primary focus of your current task
4. Check `.claude/rules/` for `agentic-<lang>.md` rule files
5. Re-run setup skill if you've installed new skills

## Customization

To modify skill loading behavior:
1. Edit the templates in `skills/project-rules/templates/`
2. Re-run the setup skill to regenerate this file
3. The setup skill will detect newly installed skills automatically

# GitHub Copilot - Agentic Skills Integration

Auto-loading skill configuration for GitHub Copilot.

## Core Instruction

**Before writing any code or creating any file, consult the relevant skill documentation from the `skills/` directory.**

## Skill Loading Rules

### Universal Requirements

- Always read the appropriate `skills/<skill-name>/SKILL.md` before coding
- Never skip skill loading, even for simple tasks within a skill's domain
- Skills contain critical patterns, constraints, and best practices

### File Type Triggers

Load these skills automatically based on file context (only if installed):

- **Word Documents (`.docx`)**: Load and follow `skills/docx/SKILL.md` (if exists)
- **PDF Files (`.pdf`)**: Load and follow `skills/pdf/SKILL.md` (if exists)
- **Presentations (`.pptx`)**: Load and follow `skills/pptx/SKILL.md` (if exists)
- **Spreadsheets (`.xlsx`)**: Load and follow `skills/xlsx/SKILL.md` (if exists)
- **Uploaded Files**: If files are uploaded but not in context, load `skills/file-reading/SKILL.md` (if exists)

### Language-Specific Skills

Load these skills when the specified language is the primary focus (only if installed):

**Installed Skills**: {SKILL_LIST}

Example triggers (only active for installed skills):
- **Go (`.go`, `go.mod`, `go.sum`)**: Load and follow `skills/go/SKILL.md`
- **Python (`.py`)**: Load and follow `skills/python/SKILL.md`
- **TypeScript (`.ts`, `.tsx`)**: Load and follow `skills/typescript/SKILL.md`
- **Rust (`.rs`)**: Load and follow `skills/rust/SKILL.md`

## Implementation Guidelines

### Conditional Loading
- Language skills only activate when that language is the primary task focus
- Don't load multiple language skills simultaneously unless truly needed
- File type skills load whenever those file formats are involved

### Context Optimization  
- Only load relevant skills to keep suggestions focused and efficient
- Skills are loaded automatically based on project context
- No manual skill invocation should be required

### Skill Reference Format
When a skill is loaded, reference it in responses like:
```
Following skills/go/SKILL.md guidelines for Go development...
```

## Usage Notes

- Skills are located in the `skills/` directory relative to project root
- Each skill has comprehensive documentation in its `SKILL.md` file
- Skills may have prerequisites or dependencies listed in their documentation
- Some skills are versioned (like Go) - check branches for specific versions

## Troubleshooting

If skills aren't being applied correctly:

1. Verify the skill file exists at `skills/<skill-name>/SKILL.md`
2. Check that file extensions match the trigger patterns
3. Ensure the language/file type is the primary focus of the current task
4. Confirm GitHub Copilot is reading instructions from `.github/copilot-instructions.md`

## Customization

To modify skill loading:
1. Edit the template at `skills/project-rules/templates/copilot.md`
2. Re-run the setup skill to update `.github/copilot-instructions.md`
3. Changes will apply to all team members using GitHub Copilot

# Cursor Agentic Skills - Base Configuration

This is the base template for Cursor IDE skill routing. The setup skill uses this to create the core infrastructure, then adds language-specific rules based on installed skills.

## Base Universal Rules

Creates `.cursor/rules/agentic-universal.mdc`:
```yaml
---
description: Universal agentic skill routing — always active
alwaysApply: true
---
Before writing any code or creating any file, read the SKILL.md for the relevant skill if available.
Never skip skill loading even for simple tasks.

File uploads not yet in context → load skills/file-reading/SKILL.md if available.
```

## Language-Specific Rule Templates

The setup skill scans for installed skills and creates individual `.mdc` files only for detected skills:

### If skills/go/*/SKILL.md exists → Create `.cursor/rules/agentic-go-<version>.mdc`:
```yaml
---
description: Go skill routing (version <version>)
globs: ["**/*.go", "**/go.mod", "**/go.sum"]
alwaysApply: false
---
Read skills/go/<version>/SKILL.md before writing or editing Go code.
```

### If skills/python/*/SKILL.md exists → Create `.cursor/rules/agentic-python-<version>.mdc`:
```yaml
---
description: Python skill routing (version <version>)
globs: ["**/*.py"]
alwaysApply: false
---
Read skills/python/<version>/SKILL.md before writing or editing Python code.
```

### If skills/typescript/SKILL.md exists → Create `.cursor/rules/agentic-typescript.mdc`:
```yaml
---
description: TypeScript skill routing
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---
Read skills/typescript/SKILL.md before writing or editing TypeScript code.
```

### If skills/rust/SKILL.md exists → Create `.cursor/rules/agentic-rust.mdc`:
```yaml
---
description: Rust skill routing
globs: ["**/*.rs"]  
alwaysApply: false
---
Read skills/rust/SKILL.md before writing or editing Rust code.
```

## Framework & Technology-Specific Skills

The setup skill also detects and configures non-language skills:

### If skills/react/SKILL.md exists → Create `.cursor/rules/agentic-react.mdc`:
```yaml
---
description: React skill routing
globs: ["**/*.jsx", "**/*.tsx", "**/package.json", "**/components/**/*"]
alwaysApply: false
---
Read skills/react/SKILL.md when working with React components and patterns.
```

### If skills/auth/SKILL.md exists → Create `.cursor/rules/agentic-auth.mdc`:
```yaml
---
description: Authentication skill routing
globs: ["**/auth/**/*", "**/login/**/*", "**/oauth/**/*", "**/*auth*", "**/*saml*"]
alwaysApply: false
---
Read skills/auth/SKILL.md when working with authentication and authorization code.
```

### If skills/docker/SKILL.md exists → Create `.cursor/rules/agentic-docker.mdc`:
```yaml
---
description: Docker skill routing
globs: ["**/Dockerfile", "**/docker-compose*.yml", "**/.dockerignore", "**/k8s/**/*"]
alwaysApply: false
---
Read skills/docker/SKILL.md when working with containerization and deployment.
```

## Document Processing (Optional)

If document skills are installed → Create `.cursor/rules/agentic-documents.mdc`:
```yaml
---
description: Document file skill routing
globs: ["**/*.docx", "**/*.pdf", "**/*.pptx", "**/*.xlsx"]
alwaysApply: false
---
File type skill loading (only for installed skills):
- .docx files → load skills/docx/SKILL.md (if exists)
- .pdf files → load skills/pdf/SKILL.md (if exists)
- .pptx files → load skills/pptx/SKILL.md (if exists)
- .xlsx files → load skills/xlsx/SKILL.md (if exists)
```

## How Setup Works with Branch-Based Installation

1. **Scan for skills**: Check what skills/<name>/<version>/ directories exist
2. **Create base rules**: Always create universal rules
3. **Add skill-specific rules**: Only for detected skills with version information
4. **Additive approach**: Mix and match any skills and versions
5. **No conflicts**: Each skill gets its own .mdc file with unique naming (agentic-{skill}-{version}.mdc)

**Examples of supported skill combinations:**
```bash
# Install skills with version selection
npx skills add Krushnal121/agentic
# Shows picker with versions: go 1.26, python 3.12, etc.

# Specific version installations still supported
npx skills add https://github.com/Krushnal121/agentic/tree/go/1.25/skills/go/1.25

# Mix and match - all work together!
```

**Result:** Each gets its own configuration:
- `.cursor/rules/agentic-go-1.26.mdc` (Go 1.26 enterprise patterns)
- `.cursor/rules/agentic-python-3.12.mdc` (Python 3.12 patterns) 
- `.cursor/rules/agentic-react-18.mdc` (React 18 patterns)
- Universal rules stay consistent across all installations

# Agentic Skills - Windsurf Rules

Auto-loading skill configuration for Windsurf IDE.

## Universal Rules

**Always apply these rules:**

- Read the relevant `skills/<skill-name>/SKILL.md` BEFORE writing any code or creating any file
- Never skip skill loading even for "simple" versions of covered tasks
- When files are uploaded but not yet in context → load `skills/file-reading/SKILL.md` FIRST

## Conditional Skill Loading

### Language Skills (Load only when working primarily with these file types)

**Installed Skills** (detected by setup skill):
{SKILL_LIST}

Example rules (only created for installed skills):

**Go Development** - If `skills/go/SKILL.md` exists, triggers on: `*.go`, `go.mod`, `go.sum`
```
When editing Go files → load skills/go/SKILL.md
```

**Python Development** - If `skills/python/SKILL.md` exists, triggers on: `*.py`  
```
When editing Python files → load skills/python/SKILL.md
```

**TypeScript Development** - If `skills/typescript/SKILL.md` exists, triggers on: `*.ts`, `*.tsx`
```
When editing TypeScript files → load skills/typescript/SKILL.md
```

**Rust Development** - If `skills/rust/SKILL.md` exists, triggers on: `*.rs`
```
When editing Rust files → load skills/rust/SKILL.md
```

### Document Processing Skills (Load when working with these file types)

**Microsoft Word** - If `skills/docx/SKILL.md` exists, triggers on: `*.docx`
```
When working with Word documents → load skills/docx/SKILL.md
```

**PDF Documents** - If `skills/pdf/SKILL.md` exists, triggers on: `*.pdf`
```
When working with PDF files → load skills/pdf/SKILL.md
```

**PowerPoint Presentations** - If `skills/pptx/SKILL.md` exists, triggers on: `*.pptx`
```
When working with presentations → load skills/pptx/SKILL.md
```

**Excel Spreadsheets** - If `skills/xlsx/SKILL.md` exists, triggers on: `*.xlsx`
```
When working with spreadsheets → load skills/xlsx/SKILL.md
```

## Configuration Notes

- **Conditional Loading**: Language skills only activate when those file types are the primary focus
- **Context Optimization**: Only installed skills load to keep context lean
- **Zero Manual Invocation**: Skills auto-load based on project context
- **Single Source of Truth**: Skill content lives in `skills/` directory, not in these rules
- **Branch Compatible**: Supports installing individual skills from different branches
- **Additive Installation**: New skills integrate without affecting existing ones

## Troubleshooting

If skills aren't loading as expected:

1. Verify you're working with files matching the trigger patterns
2. Check that skill files exist at `skills/<skill-name>/SKILL.md`  
3. Ensure the language is the primary focus of your current task
4. Confirm Windsurf is reading from `.windsurf/rules/skills.md`

## Customization

To modify loading behavior:
1. Edit `skills/project-rules/templates/windsurf.md`
2. Re-run the setup skill to regenerate `.windsurf/rules/skills.md`
3. Ask and Commit changes to share with your team