AI에게 매번 같은 지시를 쓰는 것을 그만둔 이야기 ── Copilot CLI × Agent Skills 입문

서론

주식회사 SonicMove에서 프론트엔드 엔지니어로 일하고 있는 Ishiguro006입니다.

이 기사에서 전하고 싶은 것은 하나입니다.

copilot-instructions.md

와 Agent Skills를 준비하는 것만으로, 매번 같은 지시를 프롬프트(Prompt)에 쓸 필요가 없게 됩니다. 게다가 코드 생성 품질도 올라갑니다.

구체적으로는, 다음과 같은 변화가 일어났습니다.

Skills 없음	Skills 있음
스타일	인라인 스타일
...

"매번 프롬프트에 같은 내용을 쓰고 있다", "AI가 생성한 코드에 대한 리뷰 지적이 항상 똑같다"라고 느끼는 분들에게 꼭 읽어보시길 권합니다!

대상 독자

• GitHub Copilot CLI를 사용해보고 싶은 사람
• Copilot에게 팀의 코딩 규약(Coding Convention)을 학습시키고 싶은 사람
• Agent Skills라는 개념을 실제로 시도해보고 싶은 사람

Copilot CLI란

공식 문서에는 다음과 같이 적혀 있습니다.

The command-line interface (CLI) for GitHub Copilot allows you to use Copilot directly from your terminal. You can use it to answer questions, write and debug code, and interact with GitHub.com.

터미널에서 직접 Copilot을 사용할 수 있는 도구입니다. 질문에 대한 답변, 코드 생성, 디버깅부터 GitHub.com과의 연동까지 대응합니다. IDE 플러그인과는 달리 CLI 기반으로 동작하기 때문에 스크립트나 자동화와의 궁합이 좋다는 것이 특징입니다.

Agent Skills란

공식 문서에는 다음과 같이 적혀 있습니다.

Agent skills are folders of instructions, scripts, and resources that Copilot can load when relevant to improve its performance in specialized tasks.

특정 태스크(Task)에 대해 Copilot의 퍼포먼스를 향상시키기 위한 지시(Instructions), 스크립트(Scripts), 리소스(Resources)를 모아둔 것입니다. "이 프로젝트에서는 CSS Modules를 사용한다", "접근성(Accessibility) 요구사항은 이것이다"와 같은 팀의 규약을 적어두면, 이후의 생성에 자동으로 반영됩니다.

우선 실행하기까지 (5분)

설치

① GitHub CLI 설치

brew install gh

이미 설치되어 있는 경우에는 Warning: gh X.X.X is already installed and up-to-date.

라고 표시됩니다. 그 경우에는 그대로 다음 단계로 진행해도 괜찮습니다.

② GitHub 로그인

gh auth login

몇 가지 질문이 나오므로 답변해 나갑니다. 기본적으로 기본값(Default) 그대로 두어도 괜찮습니다.

? Where do you use GitHub? → GitHub.com
? What is your preferred protocol for Git operations on this host? → SSH 또는 HTTPS (환경에 맞춰 선택)
? Upload your SSH public key to your GitHub account? → 사용 중인 키를 선택 (SSH를 선택한 경우)
...

마지막에 브라우저가 열리고 원타임 코드(One-time code)를 입력하면 완료됩니다👏

③ Copilot CLI 활성화

gh copilot --version

실행하면 설치할 것인지 확인 창이 뜹니다. Yes를 선택하면 완료됩니다.

GitHub Copilot CLI X.X.XX.
Run 'copilot update' to check for updates.

이상! 생각보다 간단했습니다 🎉

기본 사용법

-p로 프롬프트(Prompt)를 전달하는 것이 기본 형태입니다.

gh copilot -p "카レント 디렉토리의 파일 목록을 크기 순으로 표시하고 싶어" --allow-tool 'shell(ls)'

출력은 다음과 같습니다.

ls -lSh
- `-l` : 상세 표시
- `-S` : 크기 순 (큰 순서대로)
...

명령어 제안뿐만 아니라, 옵션의 의미나 응용 방법까지 설명해 줍니다. 생각보다 친절해서 깜짝 놀랐습니다!

자주 사용하는 옵션

옵션	내용
-p "..."	프롬프트 (Prompt)를 지정하여 실행
--allow-tool='shell(git:*)'	특정 도구만 허용
--deny-tool='shell(git push)'	특정 도구를 금지
--allow-all	모든 조작을 허용 (⚠️ 후술)
--plan	실행 전에 계획만 수립
--share	세션을 Markdown으로 저장

--allow-all

은 신중하게

⚠️ --allow-all

은 셸 명령어 (Shell Command)의 자동 실행, 임의 파일에 대한 접근, 외부 URL에 대한 접근을 일괄적으로 허용합니다. --yolo라고 쓸 수도 있습니다. "You Only Live Once", 즉 인생은 한 번뿐. 모든 것을 한꺼번에 허용하는 태도가 이름에 드러나 있습니다!

git 조작으로 한정한다면 다음과 같이 작성할 수 있습니다.

gh copilot -p "최근 3개의 커밋 로그를 보여줘" \
--allow-tool='shell(git:*)' \
--deny-tool='shell(git push)' # push만 금지

--plan

과 --share

도 은근히 편리합니다 👀

** --plan** 은 실행하지 않고 계획만 세운 뒤 멈추는 모드입니다. 큰 변경을 하기 전에 "AI가 무엇을 할 계획인지" 확인할 수 있습니다. 확인 사항을 제시한 후 멈추기 때문에 의도하지 않은 변경을 방지할 수 있습니다.

** --share** 는 세션 전체를 타임스탬프가 포함된 Markdown으로 내보내 줍니다. 작업 로그를 남기고 싶을 때 사용할 수 있습니다.

copilot-instructions.md

를 두면 무엇이 변하는가

본론: 동일한 프롬프트를 .github/copilot-instructions.md가 없는 경우와 있는 경우의 두 가지 조건으로 테스트합니다.

❌ 파일 없음

gh copilot -p "React로 심플한 버튼 컴포넌트를 만들어줘" --allow-all

생성된 것은 Button.tsx 파일 1개입니다.

// 색상이 하드코딩되어 있음
const styles = { primary: { backgroundColor: "#0070f3", color: "#fff" }, ...

작동은 하지만, 프로젝트의 규칙과는 무관한 결과물이 생성되었습니다. 리뷰할 때마다 매번 똑같은 지적을 하게 될 전형적인 사례입니다.

copilot-instructions.md

를 두기

✅ .github/copilot-instructions.md를 생성합니다.

# Copilot Instructions
## 컴포넌트 설계 규칙
- props는 `label` 대신 `children`을 사용할 것
...

동일한 프롬프트를 다시 실행하면...

// Button.tsx
import styles from "./Button.module.css"; // ← CSS Modules로 변경됨
export const Button = ({ children, variant = "primary", onClick }: Props) => (
...

/* Button.module.css */
:root {
--color-primary: #0070f3; /* ← CSS 변수로 정의 */
...

프롬프트는 바꾸지 않았습니다. 파일을 두었을 뿐인데 이 정도로 변했습니다. 효과가 확실하네요 🙌

규칙은 나중에 추가하기만 하면 된다

copilot-instructions.md의 장점은 나중에 내용을 추가하기만 해도 즉시 반영된다는 점입니다. "구현 전 사양 정리"를 추가해 보았습니다.

cat >> .github/copilot-instructions.md << 'EOF'
## 구현 전 사양 정리
컴포넌트를 구현하기 전에 반드시 다음 사항을 정리할 것:
...
EOF

테스트 삼아 다른 컴포넌트로 모달 (Modal)을 생성해 보았습니다.

gh copilot -p "Reactでモーダルコンポーネントを作って" --allow-all

다음과 같이 자동으로 입력되었습니다!

• ✅ role="dialog", aria-modal, aria-labelledby
• ✅ Esc 키로 닫는 처리
• ✅ 포커스 (Focus) 자동 이동

버튼을 만들 때는 이런 것들이 전혀 없었습니다. 규칙을 키운 만큼, 생성 결과가 점점 똑똑해지는 느낌이 듭니다.

더욱 진화: Agent Skills로 분리하기

copilot-instructions.md에 무엇이든 계속 써 내려가다 보면, 언젠가는 관리하기 어려워집니다. 그래서 시도해 본 것이 Agent Skills 파일로 분리하여 참조하게 하는 구조입니다.

참고로, GitHub Copilot에는 기본적으로 사용할 수 있는 Agent Skills가 몇 가지 준비되어 있습니다. 자세한 내용은 공식 문서를 확인해 주세요. 이번에는 팀의 규칙을 독자적인 Skill로 만들어 보겠습니다.

① Skill 파일 만들기

mkdir -p ~/.copilot/skills
cat > ~/.copilot/skills/accessibility.skill.md << 'EOF'
# Skill: Accessibility Check
...

② copilot-instructions.md에서 참조하기

cat >> .github/copilot-instructions.md << 'EOF'
## Skills
다음 Skill 파일을 참조하여 구현에 반영할 것:
...

③ 실제로 사용해 보기

gh copilot -p "Reactでドロップダウンコンポーネントを作って" --allow-all

실행 로그를 보면, Copilot CLI가 자동으로 Skill 파일을 가져가고 있었습니다!

● Read accessibility.skill.md
│ ~/.copilot/skills/accessibility.skill.md
└ 21 lines read

그리고 생성물에는 Skill의 규칙이 모두 반영되어 있었습니다 🎯

Skill에 작성한 규칙	실제로 생성된 구현
role을 명시	role="combobox", role="listbox"
aria 속성	aria-expanded, aria-haspopup
키보드 조작	↑↓ / Enter / Escape
포커스 관리	선택된 항목으로의 스크롤 추적
시맨틱스 (Semantics)	useId()로 ID 자동 생성

Skill 파일을 분리함으로써 "이 프로젝트에는 이 Skill을 사용한다"라는 조합도 만들 수 있게 됩니다. 재사용성이 높아지는 점이 반갑습니다!

보너스: 글로벌 설정으로 모든 리포지토리에 적용하기

~/.copilot/copilot-instructions.md에 작성하면, 리포지토리와 관계없이 모든 세션에 적용됩니다.

cat > ~/.copilot/copilot-instructions.md << 'EOF'
# Global Instructions
- 답변은 반드시 일본어로 할 것
...

.github/copilot-instructions.md가 없는 다른 디렉토리에서 테스트해 본 결과, 주석이 일본어로 생성되었습니다! 팀의 규약은 리포지토리에, 개인의 취향은 글로벌에 나누어 작성하면 사용하기 편리할 것 같습니다.

파일 위치	스코프 (Scope)	우선순위
~/.copilot/copilot-instructions.md	모든 리포지토리	낮음
.github/copilot-instructions.md	해당 리포지토리	높음 (덮어씀)

요약

오늘 한 일을 정리하면 다음과 같습니다.

1. copilot-instructions.md를 배치한다
→ 팀의 규약에 따른 코드가 생성되게 된다
2. 규칙을 추가한다
...

"AI를 위한 지시서"라기보다, 팀의 설계 지식을 AI에게 전달하기 위한 자산으로서 키워나가는 이미지가 더 가깝다고 생각합니다. 조금씩 키워나가는 것이 즐겁습니다 🌱

다음에 하고 싶은 것

• 팀에서 Skills를 공유하여 동일한 결과가 재현되는지 확인하기
• 보다 실무에 가까운 주제(폼, 테이블, 유효성 검사 (Validation) 등)로 검증하기
• Claude Code와의 비교

이 글이 같은 고민을 가진 누군가에게 참고가 된다면 좋겠습니다!

참고

Discussion