SuperAPI AI Directory

add-rules

General & other

View repository

Updated 10-15 20:24

About this skill

Add Rules

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

  1. Ask when ambiguous: Always confirm unclear requirements
  2. Analyze structure first: Decide after identifying existing patterns
  3. User confirmation required: Always request approval before adding/modifying
  4. 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/
  5. 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인 경우)

### 검증 결과
[체크리스트 통과 여부]

Detailed guide