notes

Harness Engineering - Cursor: Skill.md / Rules로 작업 가이드 붙이기

2026-01-18수정 2026-10-084 min read

Harness Engineering에서 Cursor Skill.md·Rules로 작업 가이드를 적용하는 메모.

Kim mr.

프론트엔드 · 기술 블로그

Skill 과 Rule 은 뭐가 다른가

둘 다 에이전트에게 일하는 법을 알려주는 문서지만 붙는 시점이 다르다.

Claude 의 Skill 과 제일 비슷한 건 Cursor 의 Agent Skill 이다. "이 프로젝트는 무조건 이렇게" 에 가까운 건 Rule 이다.

Cursor 는 .claude/skills/, .codex/skills/ 에 있는 스킬도 같이 읽는다. Claude Code 용으로 만든 스킬을 그대로 재활용할 수 있다는 뜻이다.

~/.cursor/skills-cursor/ 는 Cursor 내장 스킬 자리다. 여기에 내 스킬을 만들지 않는다.

my-skill/
├── SKILL.md        # 필수
├── references/     # 선택: 긴 문서
├── scripts/        # 선택: 실행 스크립트
└── assets/         # 선택: 템플릿, 데이터

YAML 프론트매터 + 본문이다.

---
name: my-skill
description: 무엇을 하는지, 언제 쓸지(트리거 키워드 포함).
disable-model-invocation: true
---

# 스킬 제목

## 지시
에이전트가 따라야 할 단계, 규칙.

name: 소문자, 숫자, 하이픈만 쓴다. 폴더 이름과 같아야 한다.
description: 에이전트가 이 스킬을 켤지 판단할 때 읽는다. 무엇을 하고 언제 쓰는지, 트리거 단어까지 3인칭으로 구체적으로 쓴다.
disable-model-invocation: 선택이다. 생략하면 맥락에 맞을 때 자동으로 켜지고, true 면 /스킬이름 으로 부를 때만 켜진다.
특정 파일에서만 켜고 싶으면 paths 에 glob 을 적는다. 예전 globs 도 아직 먹힌다.

본문은 짧게 쓴다. create-skill 가이드는 500줄 이하를 권한다. 길어지면 references/ 로 빼고 필요할 때만 읽게 하는 점진적 공개 패턴을 쓴다.

스킬을 직접 안 써도 된다. Cursor 에는 /create-skill, /create-rule 같은 내장 스킬이 있고, 기존 rule 을 스킬로 옮기는 /migrate-to-skills 도 있다.

---
description: 이 규칙이 하는 일 한 줄
globs: "**/*.tsx"
alwaysApply: false
---

# 규칙 제목
본문

규칙 하나는 짧게, 대략 50줄 안쪽으로 쓰고 주제별로 파일을 나누는 게 좋다.

Claude 프로젝트나 Skill 에 길게 적어 두던 걸 Cursor 로 가져올 때는 둘로 쪼갠다.

스킬을 마무리하기 전에는 네 가지만 본다. description 에 무엇을 하고 어떤 말이나 상황에서 쓸지 적었는지, 트리거가 구체적인지, SKILL.md 가 너무 길지 않은지, 경로를 skills-cursor 가 아니라 skills 로 잡았는지.

아래는 회사 모노레포의 .cursor/rules 에 앱별 rule 을 붙이던 화면이다. 레포, 조직, rule 파일 이름과 터미널 출력은 흐리게 가렸다.