에이전트 스킬 표준
NPM Version
License: MIT
GitHub Stars
SkillSpector Verified
AI 코딩 에이전트를 위한 포터블 표준 계층입니다. 한 번 동기화하고, 자체 런타임에서 작업하세요.
목적 (Purpose)
에이전트 스킬 표준은 모듈식이며 버전 관리되는 엔지니어링 가이드라인 및 개발 워크플로우 카탈로그를 제공합니다. 이 카탈로그는 코딩 에이전트(Cursor, Claude Code, GitHub Copilot, Gemini CLI, Windsurf, Trae, Kiro, Roo 등)의 네이티브 구성으로 동기화됩니다. 시스템 프롬프트에 수천 개의 지침을 패킹하지 않으면서 팀 전체에서 엔지니어링 관행을 일관되게 유지할 수 있도록 합니다.
의도된 개발자 (Intended Developer)
AI 코딩 어시스턴트를 사용하며 아키텍처 경계, 엄격한 타입 검사(strict type checking), 보안 규칙, 테스트 패턴 등 여러 도구와 환경 전반에 걸쳐 포터블하게 유지되는 공유 가능하고 감사 가능한 표준을 원하는 개발자 및 엔지니어링 팀을 위해 구축되었습니다.
[!NOTE]
사양 및 런타임 경계 (Specification & Runtime Boundary): 이 저장소는 오픈 소스 카탈로그, 배포 CLI, 그리고 MCP 서버입니다. 이는 개방형 Agent Skills 형식에 맞는 스킬을 제공하지만, 근본적인 사양(specification)을 소유하거나 관리하지 않으며, 기존 에이전트 런타임이나 IDE를 대체하지 않습니다.
구체적인 사용 사례 (Concrete Use Case)
에이전트가 API 엔드포인트를 생성하거나 리팩토링할 때, 활성 파일 패턴 및 작업 개념(예: NestJS 컨트롤러 컨벤션, TypeScript 엄격 타입 지정, API 응답 래퍼 등)과 일치하는 집중적인 온디맨드 스킬 파일을 참조하여, 모놀리식 지침에 비해 불필요한 프롬프트 컨텍스트를 줄이면서 구조화된 도메인 가이던스를 제공할 수 있습니다.
다음 단계: 빠른 설정 (Next Action: Quick Setup)
전역으로 설치하고 프로젝트 저장소에서 초기화하세요:
npm install -g agent-skills-standard@latest
ags init
...
전역 설치 없이 직접 실행하거나:
npx agent-skills-standard@latest init
npx agent-skills-standard@latest sync
엔지니어가 아니신가요? 위 명령어들을 실행할 필요는 없습니다. 단순히 아이디어를 AI 에이전트에게 설명하기만 하면 됩니다. Product Owner용 시작 가이드를 참조하세요.
문제점 (The Problem)
모든 팀에는 코딩 표준(coding standards)이 있습니다. 하지만 AI 에이전트는 이를 알지 못합니다.
결과적으로 다음과 같은 지침을 반복해야 합니다: "OnPush 변경 감지를 사용하세요", "오류는 항상 컨텍스트와 함께 래핑하세요", "핸들러에 비즈니스 로직을 넣지 마세요". 그리고 매번, 당신은 동일한 트레이드오프(trade-off)에 직면합니다:
- 규칙이 너무 많음 = AI가 규칙을 잊거나, 토큰을 낭비하거나, 혼란스러워함
- 규칙이 너무 적음 = AI가 표준과 맞지 않는 일반적인 코드를 작성함
.cursorrules 복사/붙여넣기 = 일주일 만에 구식이 되고, 팀 규모로 확장되지 않음
해결책 (The Solution)
Agent Skills Standard는 엔지니어링 규칙을 어떤 AI 에이전트든 필요할 때 로드할 수 있는 모듈식(modular), 버전 관리형 스킬로 변환합니다.
| 스킬 없이 | 스킬 사용 시 |
|---|
| 모든 채팅에 필요한 대규모 올인원 아키텍트 프롬프트 | 관련성이 있을 때만 로드되는 집중된 스킬 |
| ... | |
또 다른 에이전트 런타임이 아닙니다 (Not Another Agent Runtime)
Agent Skills Standard는 새로운 일일 명령어 시스템을 강요하지 않습니다. ags는 설정(setup), 동기화(sync), 유효성 검사(validation), MCP 와이어링, 업데이트를 위한 것입니다. 동기화가 완료된 후, 당신의 AI 도구는 네이티브 자산(native assets)을 받게 됩니다:
- Claude/Roo/OpenCode 명령어
- Codex/Cursor/Trae 스킬
- Gemini TOML 명령어
- Copilot 프롬프트
- Antigravity/Kiro 워크플로우 파일
- 런타임 지침 전달을 위한 MCP 도구 (로딩 영수증 제공 — 라우팅, 모델, 계정 또는 작업 준수를 보장하지는 않음)
당신은 파일을 레포지토리(repo)에 유지하고, .skillsrc 및 custom_overrides를 사용하여 사용자 정의하며, 이미 사용 중인 에이전트 내부에서 워크플로우를 실행합니다.
작동 방식 (How It Works)
You run: npx agent-skills-standard sync
What your AI gets:
...
AI는 활성 파일 패턴 및 프롬프트를 기반으로 일치하는 스킬 파일을 접근하여, 모든 것을 포함한(all-in-one) 프롬프트에 비해 토큰 오버헤드를 줄입니다. 스킬 지침은 구조화된 가이드를 제공하지만, 행동 준수 여부는 모델에 따라 달라집니다.
아키텍처 및 토큰 경제 (Architecture & Token Economy)
본 프로젝트는 제로 트러스트(Zero-Trust) 아키텍처 모델을 따르며, 이는 **Rust Token Killer (RTK)**에서 영감을 받았습니다. 모든 규칙을 매 프롬프트에 주입하는 대신, 현재 파일 및 작업과 일치하는 인덱스 행과 스킬만 읽는 계층적 로딩 시스템을 사용합니다.
자세한 문서는 ARCHITECTURE.md에 있으며, 다음 내용을 다룹니다:
- 계층적 해상도 (Hierarchical Resolution): 라우터 테이블 (
AGENTS.md) -> 카테고리 인덱스 (_INDEX.md) -> 스킬 (SKILL.md).
- 통합 분류법 (Integration Taxonomy): Cursor, Claude, Copilot, Windsurf, Trae, Roo 등 다중 에이전트 브릿지 지원.
- 고밀도 설계 (High-Density Design): 모든 스킬은 100줄 미만이어야 하며 토큰 경제에 최적화되어야 합니다.
빠른 시작 (Quick Start)
필수 조건 (Prerequisites)
- Consumer CLI (
ags): Node 22 LTS >= 22.13 버전의 22.x 라인 또는 더 새로운 지원되는 LTS에서 지원됩니다. 지원된다는 것은 정확히 선언된 의존성 교차점 ^22.13.0 || >= 23.5.0(commander 15는 >= 22.12.0을, inquirer 14는 >= 23.5.0 || ^22.13.0 || ^20.17.0을 선언)을 의미합니다. CLI의 package.json에는 자체적인 engines 필드가 없으므로, 중간 Node 버전은 선언된 지원 범위에 포함되지 않습니다.
- 저장소 루트 및 도구 (Repository Root & Tooling): 루트
package.json은 node: ">= 20.0.0"과 [email protected]을 선언합니다. 이는 루트 스크립트에 대한 매니페스트 선언일 뿐, CLI나 웹사이트 빌드가 Node 20을 지원한다는 증거는 아닙니다.
- 기여자 및 웹사이트 (Contributors & Website): 전체 개발자 요구 사항(지원되는 Node 22 LTS 또는 더 새로운 지원되는 LTS, pnpm
10+)은 CONTRIBUTING.md를 참조하십시오.
1. 초기화 (Initialize)
기술 스택을 감지하고 .skillsrc 설정을 생성합니다:
npm install -g agent-skills-standard@latest
ags init
...
2. 동기화(Sync)
구성된 AI 에이전트 디렉터리에 스킬을 다운로드하고, .skills-lock.json v2에 소유권을 기록하며, 인덱스를 생성합니다:
[!경고]
최초 사용 확인, 관찰일 2026-11-03: @latest는 게시된 2.6.6으로 해석되었습니다. 격리된 전역 설치 및 ags init (Next.js/Codex 템플릿, MCP 비활성화)은 성공했지만, 후속 ags sync는 구성된 카테고리 참조(refs)인 common-v2.9.3과 quality-engineering-v1.6.2를 사용할 수 없었기 때문에 거부되었습니다. 네이티브 에이전트 자산이나 .skills-lock.json 파일은 설치되지 않았으며, CLI 종료 코드가 포착되지 않았습니다. 별도로, specialists 참조 v1.5.2도 사용 불가능했으며, 네이티브 내보내기(export)의 완전성은 검증되지 않았습니다. 이는 해당 시도의 기록일 뿐 다른 릴리스에 대한 예측은 아닙니다: 설치된 버전을 확인하려면 ags --version을 실행하고, 동기화가 실패하면 GitHub Issues를 사용하십시오.
[!팁]
릴리스 및 PATH 참고 사항:
- 게시 버전: npm 패키지 페이지 배지 또는 설치된 바이너리(
ags --version)에서 확인하십시오. 이것이 @latest를 사용하는 소비자가 얻는 버전입니다.
- 소스 대상: 이 체크아웃의 CLI 매니페스트와 변경 로그는
cli-v2.7.0을 대상으로 합니다( CHANGELOG.md 참조). 소스 버전은 개발 목표일 뿐, 동일한 빌드가 npm에 게시되었다는 증거는 아닙니다.
- 재설치 후에도
ags -V가 이전 버전을 표시하는 경우, 셸의 PATH 순서(예: ~/Library/pnpm이 ~/Library/pnpm/bin보다 앞)를 확인하고, hash -r을 실행한 다음, 다시 ags -V로 확인하십시오.
안전한 설치 및 로컬 편집
- 편집 보호(Edit Protection): 사용자가 수정한 소유 파일은 보존 및 보고되며, 절대 조용히 덮어쓰여지지 않습니다.
ags sync --dry-run: 파일을 수정하지 않고 변경될 내용을 미리 보여줍니다.ags sync --dry-run --verbose: 영향을 받는 모든 파일 경로를 나열합니다.ags sync --dry-run --json: CI 또는 자동화를 위해 설치 계획을 JSON 형식으로 출력합니다.ags sync --force <paths...>: 백업을 자동으로 수행한 후 보존된 파일을 덮어씁니다.- 범위별 백업(Scoped Backups): 삭제되거나 강제 덮어쓰인 파일은
.ags/backups/에 저장됩니다 (최신 3개 유지).
- 복원(Restore):
ags restore <id>를 사용하여 파괴적인 변경 사항을 되돌리거나, ags restore --list로 백업 목록을 확인할 수 있습니다.
- 안전한 제거(Safe Uninstall):
ags uninstall [--all] [--agent <agents...>] [--category <categories...>]는 소유하고 변경되지 않은 파일만 제거하며, 사용자 편집 내용은 보존하고 먼저 백업합니다.
3. (선택 사항) 스킬 선택 관리
[!중요]
ags skills는 현재 소스 대상(cli-v2.7.0)에 존재하지만 모든 배포된 릴리스에서 사용 가능한 것은 아닙니다. 배포된 [email protected] 패키지(검증 중 @latest에서 설치됨)는 init, sync, verify 및 기타 명령을 노출하지만, skills 하위 명령은 없습니다. 이 단계를 신뢰하기 전에 설치된 빌드에 대해 ags --help를 실행하십시오. 만약 해당 명령이 없다면, .skillsrc 파일을 직접 편집해야 합니다.
YAML을 수정하거나 릴리스 태그를 조회하지 않고 가이던스를 추가하거나 제거할 수 있습니다:
카테고리는 현재의 .skillsrc에서 확인됩니다. 새로 활성화된 카테고리는 해당 배포 릴리스를 자동으로 해결하는 반면, 기존에 고정된(pinned) 항목은 변경되지 않습니다. 선택적으로 중첩 스킬을 사용자 정의하거나 (검색 기능 사용), 카테고리를 배포 릴리스로 전환하고 전체 효과를 검토한 후 한 번 확인하면 됩니다. 이 명령은 선택 사항을 저장하고 구성된 모든 에이전트에 대해 설치합니다. 취소하거나 변경되지 않은 선택은 아무것도 기록하지 않습니다. 실제 변경이 발생할 경우, 해당 명령은 skills_mode: explicit를 기록하므로, 나중에 일반적인 sync를 실행해도 제거한 카테고리나 스킬을 조용히 다시 추가하지 않습니다.
4. 코드
사용자의 AI 에이전트는 이제 AGENTS.md 파일을 자동으로 읽습니다. 스킬은 사용자가 편집하는 파일과 요청 내용에 따라 활성화됩니다.
Cursor, Claude Code, GitHub Copilot, Gemini CLI, Windsurf, Trae, Kiro, Roo와 즉시 작동합니다. 플러그인이나 확장 프로그램이 필요하지 않습니다 — CLI가 각 에이전트의 네이티브 형식으로 코드를 생성합니다.
5. (선택 사항) MCP 서버를 통한 런타임 전송 활성화
CLI는 스킬을 디스크에 배포합니다. 동반되는 MCP 서버는 이 스킬들을 런타임 시 명시적인 도구 호출(explicit tool calls)로 AI 에이전트에 제공하여, 에이전트가 AGENTS.md를 읽지만 일치하는 SKILL.md 파일을 로드하는 것을 잊어버리는 간극(특히 서브 에이전트의 경우)을 메워줍니다.
동의 모델 — 범위를 선택하세요
init과 sync는 MCP 활성화 여부와 범위를 한 번만 묻습니다. 굵게 표시된 세 가지 선택지 중 하나를 권장합니다:
| 범위 | 작성되는 내용 | $HOME 접근 여부 |
|---|
project (권장) | ./mcp-config-snippets/*.json + 프로젝트 범위 런타임 설정 (./.mcp.json, ./.cursor/mcp.json 등) | ❌ 아니요 |
| ... | | |
CLI는 사용자가 명시적으로 user 범위를 선택하고 각 쓰기를 확인하지 않는 한, 사용자 홈 파일을 읽거나 수정하지 않습니다. 모든 결정은 .skillsrc에 기록되므로 매번 동기화할 때마다 다시 프롬프트되지 않습니다.
mcp 하위 명령어를 사용하여 MCP 통합 관리
ags mcp status
ags mcp enable
ags mcp disable
...
실행 모드 — 한 번 선택하고 잊어버리세요
생성된 항목은 npx를 통해서 또는 전역으로 설치된 ags-mcp 바이너리를 통해 서버를 시작합니다. 이 선택 사항은 .skillsrc 파일에 mcp.via로 저장되며, 기본값은 auto입니다.
