Analyze the repository structure to add Skill-based rules in the appropriate locations and convert existing rule files (.mdc, .cursorrules, etc.) into Skills.
Core Principles
- Ask when ambiguous: Always confirm unclear requirements
- Analyze structure first: Decide after identifying existing patterns
- User confirmation required: Always request approval before adding/modifying
- Apply Progressive Disclosure: Apply the 3-stage loading principle to rules as well
- Stage 1: Trigger keywords in description → automatic activation
- Stage 2: Core rules in the SKILL.md body (<500 lines)
- Stage 3: Details/examples in references/
- Skill-based trigger integration: Automatically activate rules via description keywords
Progressive Disclosure integration
When adding rules as Skills, apply the 3-stage loading principle:
| Stage | Role | Rule perspective | Location |
|---|---|---|---|
| Stage 1 | Discovery | Determine activation via trigger keywords | frontmatter description |
| Stage 2 | Activation | Core rules only (<500 lines) | SKILL.md body |
| Stage 3 | Execution | Detailed rules, examples, edge cases | references/ |
Criteria:
- Core rules that must be referenced every time → body (Stage 2)
- Example collections, detailed options, background explanations → references/ (Stage 3)
- Execution scripts, analysis tools → scripts/ (Stage 3)
- Static resources, templates → assets/ (Stage 3)
Workflow Overview
[1. 요청 분석] → [2. 구조 분석] → [3. 통합 패턴 결정] → [4. 사용자 확인] → [5. 규칙 추가]
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
대상 디렉토리 scripts/ 4가지 패턴 중 제안 검토 패턴별 실행
+ 모호함 확인 analyze-structure.sh 최적 선택 승인/수정
활용
Step 1: Request analysis
Always check the target skill directory first.
The skill directory may differ depending on the repository:
- General project:
.claude/skills/(the project's own skills) - Skill library repo:
skills/(collection of skills for distribution) - Other custom paths
규칙을 추가할 **대상 스킬 디렉토리**를 확인합니다:
- 이 프로젝트에서 실제 사용되는 스킬 디렉토리는 어디인가요?
- 예: `.claude/skills/`, `skills/`, 기타 경로
- (라이브러리 레포인 경우) 배포용 스킬과 프로젝트 자체 스킬을 구분해야 하나요?
Additional confirmations afterward:
| Confirmation item | Example question |
|---|---|
| Purpose of the rule | "What problem does this rule solve?" |
| Scope of application | "Does it apply only to specific files/directories?" |
| Trigger conditions | "When should this rule be activated?" |
| Conflict with existing rules | "Is there a similar existing rule?" |
Step 2: Structure analysis
Analyze by passing the skill directory specified by the user as an argument:
bash skills/add-rules/scripts/analyze-structure.sh {skills_dir}
# 예: bash skills/add-rules/scripts/analyze-structure.sh .claude/skills
# 예: bash skills/add-rules/scripts/analyze-structure.sh skills
Step 3: Determine integration pattern (choose among 4 patterns)
Step 4: User confirmation (create proposal → approval)
Step 5: Add rules (execute per pattern)
Detailed workflow is references/workflow.md reference.
4 integration patterns
| Pattern | Description | user-invocable | When to use |
|---|---|---|---|
| A. Standalone Rule-Skill | Create new skill directory | false (auto-applied) |
New standalone domain rule |
| B. Embedded Rules | assets/rules/ pattern |
N/A (follows host skill) | Include rules in existing workflow |
| C. Extend Existing Skill | Add section/ref to existing skill | Keep existing configuration | 80%+ related to existing skill |
| D. Rule Conversion | Convert existing rule file → Skill | Determined by source | Convert .mdc, .cursorrules, etc. |
Pattern A: Standalone Rule-Skill
Create rules of a new standalone domain as a separate skill.
{skills_dir}/{rule-name}/
├── SKILL.md # user-invocable: false (자동 적용)
└── references/ # 필요시
└── detail.md
user-invocable: falseSet to auto-apply- Must include trigger keywords in description
Pattern B: Embedded Rules (assets/rules/)
Embed rules into host skill's assets/rules/in the feature-workflow manner.
{skills_dir}/{host-skill}/
├── SKILL.md # "규칙 로드" 섹션에서 참조
└── assets/
└── rules/
├── AGENTS.md # 규칙 인덱스
├── MUST/ # 필수 규칙
│ └── core-rule.md
└── domain/ # 도메인 규칙
└── specific-rule.md
Pattern C: Extend Existing Skill
Add a rules section or references file to an existing skill.
- If under 500 lines: add section directly to SKILL.md
- If expected to exceed 500 lines: separate into references/ file
- Add trigger keywords to existing description
Pattern D: Rule Conversion
Convert existing rule files (.mdc, .cursorrules, rules/*.md) into a Skill.
| Source | Location | Conversion target |
|---|---|---|
| Claude rules | .claude/rules/*.md |
Skill frontmatter + body |
| Cursor rules | .cursorrules, *.mdc |
Restructure into Skill |
| Project rules | rules/*.md |
Convert to suitable pattern (A/B/C) |
For details, see references/conversion.md reference.
Pattern selection criteria
새 독립 도메인? → 패턴 A (독립 Rule-Skill)
기존 워크플로우에 규칙 포함 필요? → 패턴 B (임베디드)
기존 skill과 80%+ 관련? → 패턴 C (기존 확장)
기존 rule 파일 변환? → 패턴 D (변환)
Score-based detailed decision (Pattern A vs C):
| Criteria | Score |
|---|---|
| Existing skill of same domain exists | +3 |
| Similar trigger conditions | +2 |
| Same scope of application | +2 |
| Existing skill under 500 lines | +1 |
| Can be naturally mentioned in description | +1 |
Total score 5 or more → Pattern C (extend existing) recommended, below → Pattern A (standalone creation)
For details, see references/patterns.md reference.
Trigger design
Auto-apply vs explicit invocation
| Rule type | user-invocable | Description example |
|---|---|---|
| Coding conventions | false |
"TypeScript coding conventions. Auto-applied when writing or reviewing code." |
| Style guide | false |
"React component style guide. Auto-applied when creating components." |
| Work instructions | true (default) |
"Code review checklist. Activated when a review is requested." |
| Checklist | true (default) |
"Pre-deployment checklist. Used when deploying or when a deploy request is made." |
Good/bad trigger examples
# 좋은 description: 구체적 키워드 + 상황
description: >
TypeScript 네이밍 컨벤션. 변수명, 함수명, 클래스명 작성 시 자동 적용.
TypeScript, 네이밍, naming convention 관련 작업 시 활성화.
# 나쁜 description: 모호하고 광범위
description: >
코드 품질을 높이는 규칙입니다.
Validation
After completing rule addition, verify:
[ ] name이 1-64자, 소문자/숫자/하이픈만 사용하는가?
[ ] name이 디렉토리명과 일치하는가?
[ ] description이 무엇+언제를 명확히 설명하는가?
[ ] 트리거 키워드가 포함되어 있는가?
[ ] SKILL.md가 500줄 이하인가?
[ ] 상세 내용이 references/로 분리되었는가?
[ ] 파일 참조가 상대 경로, 1단계 깊이인가?
[ ] 기존 규칙과 충돌이 없는가?
[ ] 사용자 승인을 받았는가?
[ ] Progressive Disclosure 단계별 분리가 적절한가?
For detailed validation of create-skill, see create-skill/references/validation.md refer to.
Completion report
## 규칙 추가 완료
- **이름**: {name}
- **패턴**: A/B/C/D
- **경로**: {skills_dir}/{name}/ 또는 기존 skill 경로
### 생성/수정된 파일
| 파일 | 역할 | 줄 수 |
|------|------|-------|
| ... | ... | ... |
### 사용 방법
- 자동 적용: {조건}
- 수동 호출: `/{name}` (user-invocable인 경우)
### 검증 결과
[체크리스트 통과 여부]