요즘은 Agentic Coding이 많이 발전해서 개인의 코딩능력이 그렇게 중요한 시대는 지났다고 생각한다.
하지만, 개인적인 생각으로 CS나 아키텍처 등의 기초 지식이 있고, 핵심이 되는 기술들을 이해하고 있어야 AI Agent를 제대로 사용해서 서비스를 지속적으로 관리할 수 있다고 생각한다. (특히, 보안적인 부분은 정말 신경을 많이 써야한다.)
도메인 구조가 정말 잘 잡혀있는 프로젝트라도 규모가 커지고 복잡해질수록 Agent의 작업물에 대한 신뢰도가 떨어질 수 있기 때문에 점점 검토 과정이 번거로워진다.
(다음에 올 단어의 확률을 예측하는 방식으로 동작하는 LLM의 특성상 오류를 유발하지 않고 유지보수 측면에서도 문제가 없는 100% 신뢰할 수 있는 코드를 작성하는 것은 불가능하다고 생각한다.)
나처럼 AI Agent를 통해 조금 더 빠르고 효율적으로 개발하고, 검토 과정의 피로를 줄이고 싶어하는 개발자들이 많을 거라고 생각한다.
원래는 Rules를 사용해서 Agent의 동작을 제한하고, MCP 서버를 활용해서 문서를 작성한다거나 한정적인 기능을 통해 조금이라도 편하게 사용하고자 했었다.
Skills
그런데 ! ! ! ! !
2025년 말부터 Agents Skills라는 새로운 개념이 등장했다.
Skills.md라는 Markdown 문서를 작성해두기만 하면 적절한 때에 AI가 스스로 필요한 skill을 선택해서 사용한다.
이미 Claude Code에서는 편리하게 사용할 수 있는 plugin도 지원하고, 여러 skill을 만들어 공유하는 skills.sh 같은 서비스도 활성화되어 있다.
Skill: LLM이 직접 호출해서 “행동”을 수행할 수 있는 기능 단위
Skill.md의 기본 구조
SKILL.md는 Skill의 핵심 설명서 역할을 하는 파일이다.
구조는 크게 두 영역으로 나뉜다.
- YAML Frontmatter
- Markdown Instructions
1. YAML Frontmatter
파일 맨 위의 ---로 감싼 영역이다.
---
name: accessibility
description: Audit and improve web accessibility following WCAG 2.2 guidelines.
license: MIT
metadata:
author: web-quality-skills
version: "1.1"
---이 영역에는 Skill의 메타데이터가 들어간다.
특히 중요한 값은 다음 두 가지다.
name: Skill의 이름description: 언제 이 Skill을 사용할지 설명
description은 AI가 해당 Skill을 언제 불러야 하는지 판단하는 기준이 된다.
2. Markdown Instructions
Frontmatter 아래에 오는 본문 영역이다.
# Accessibility (a11y)
## Perceivable
Use descriptive alt text for meaningful images.
## Operable
Ensure all interactive elements are keyboard accessible.이 영역에는 모델이 실제로 따라야 할 작업 지침을 작성한다.
일반적인 설명문보다는, 모델에게 직접 행동을 지시하는 Instruction 형태로 쓰는 것이 좋다.
❌ 일반 설명문
Accessibility is important because users need keyboard navigation.
✅ Instruction 형태
Ensure all interactive elements are keyboard accessible.
Do not remove focus outlines.
Use semantic HTML whenever possible.일반 설명문과 Instruction의 차이
| 일반 설명문 | Instruction |
|---|---|
| 개념 설명 중심 | 행동 지시 중심 |
| Why 중심 | What / How 중심 |
| 사람이 읽는 문서에 가까움 | 모델이 따라야 할 규칙에 가까움 |
skills.sh
vercel, facebook, microsoft 등 인지도 높은 조직에서 skill을 작성해서 공유하는 vercel에서 운영하는 서비스이다.
npx 명령어 한 줄 실행으로 전문적으로 작성된 skill을 간편하게 사용할 수 있다는 장점이 있다.
pc의 모든 프로젝트에 전역적으로 skill을 적용할 수도 있고, 한 프로젝트에만 적용할 수도 있으며,
Claude Code, Cursor 등 여러 Agent의 skill 사용법에 맞게 자동으로 파일을 적절한 위치에 추가해주기 때문에 정말 편하다!
skill 사용법
간단하게 말해서, SKILL.md 파일을 적절한 위치(경로)에 추가해주기만 하면 Agents가 자동으로 인식하여 사용할 수 있게 된다.
모든 프로젝트에서 skill을 사용하려면 Codex가 인식할 수 있는 ~/.agents/skills 경로에 아래와 같이 skill들을 저장하면 Codex에서 각 skill을 사용할 수 있다. (Claude의 경우 ~/.claude/skills)
전역이 아닌 한 프로젝트에만 skill을 적용하고 싶다면, <프로젝트 루트>/.agents/skills 폴더에 추가하면 된다.
아래와 같이 skill을 직접 호출해 사용할 수도 있고,
이렇게 자동으로 사용되기도 한다.
프로젝트에 필요한 Skill을 직접 작성해서 개발팀 전체의 생산성을 향상시킬 수도 있으니, 잘 활용하면 좋을 것 같다!
