Written with AI assistance from the source video. The video is the authority.
1:03:28Vercel
Log in to leave a comment
No posts yet
시스템 프롬프트 하나에 온갖 가이드라인과 도구를 밀어 넣는 모놀리식 구조는 금방 밑천을 드러냅니다. 대화가 조금만 길어져도 에이전트는 프롬프트 중간에 적어둔 지침을 잊어버립니다. 매 요청마다 수만 토큰을 중복 전송하느라 추론 비용은 치솟고 첫 토큰이 뜨기까지 한참을 기다려야 합니다.
실무에서는 agentskills.io 오픈 스펙 기반의 단계적 컨텍스트 로딩 구조로 이 문제를 풉니다. 필요한 순간에만 적절한 스킬을 불러와 토큰을 아끼는 방식입니다.
모놀리식 시스템 프롬프트는 도메인 경계, 도구 실행 권한, 실행 빈도를 기준으로 쪼개야 합니다. 단일 세션에서 동시에 활성화하는 스킬을 3개 이하로 유지해야 임베딩 유사도 검색 시 스킬끼리 충돌하는 현상을 막습니다.
분리한 스킬 파일 상단에는 하이픈과 영문 소문자, 숫자만 사용한 식별자와 동작 목적을 명시한 YAML 프런트매터를 적어줍니다.
---
name: backend-api-generator
description: Generates Spring Boot REST API controller and service boilerplate code. Use when the user asks to create API endpoints, build REST controllers, or define DTO mappings for backend services.
when_to_use:
- User requests new REST API endpoint creation
- User provides database schema and asks for controller layer implementation
- Do NOT use for: database migration SQL, frontend component generation
allowed-tools:
- read_file
- write_file
- list_directory
effort: medium
---
단계적 로딩 구조를 만드는 과정은 단순합니다.
15,000~30,000 토큰을 상시 점유하던 모놀리식 구조를 SKILL.md 지연 로딩 구조로 바꾸면 초기 토큰 오버헤드가 90% 이상 줄어듭니다. Anthropic 내부 테스트 자료 기준 p95 지연 시간을 12%에서 40%까지 단축하고 대화당 평균 토큰 소모량을 29.6% 절감할 수 있습니다.
여러 스킬이 연쇄 로드될 때 이전 스킬의 지침이 세션에 남아서 다음 작업을 왜곡하는 현상이 자주 일어납니다. 고위험 검사나 로그가 많이 남는 작업에는 YAML 프런트매터에 하위 컨텍스트 분기(context: fork) 설정을 넣어서 프로세스 수준으로 격리해야 합니다.
---
name: security-vulnerability-auditor
description: Audits backend source code for OWASP top 10 security flaws. Use when auditing code security or checking for SQL injection vulnerabilities.
context: fork
model: claude-sonnet-4-20250514
effort: high
---
입출력 데이터 계약(Data Contract)을 명확히 정의하는 작업도 빠질 수 없습니다.
### Output Schema Contract
All responses must strictly adhere to the following JSON structure without markdown wrapping:
{
"status": "SUCCESS" | "FAILED",
"generated_files": [
{
"path": "string",
"content": "string"
}
],
"error_message": "string | null"
}
하위 프로세스로 격리하면 도구 호출 로그가 메인 세션으로 쏟아지는 사태를 막을 수 있습니다. 메인 대화 세션이 깨끗하게 유지되니 서브 에이전트 사이에서 데이터를 주고받을 때 에러가 날 확률도 줄어듭니다.
요구사항이 모호하거나 도구 호출 에러가 반복되면 에이전트는 무한 재시도 루프에 빠집니다. 몇 분 만에 API 비용 수십 달러가 날아가는 순간입니다. 스킬 파일 본문에 단계별 정적 검증 체크리스트(Verification Checklist)를 넣어두면 에이전트가 작업을 끝내기 전에 스스로 검증을 수행합니다.
### Execution & Self-Testing Protocol
Before declaring the task finished, you MUST sequentially execute the following verification checklist:
1. [Pre-check] Verify that all required input parameters are present. If mandatory arguments are missing, STOP immediately and ask the developer for input.
2. [Generation] Write the requested implementation code.
3. [Syntax Verification] Check the written code for missing imports, unresolved symbols, and syntax errors.
4. [Self-Correction] If a syntax error is identified, attempt correction ONCE. Do not re-run the file write tool more than twice for the same error.
물리적으로 루프를 끊어버리는 서킷 브레이커(Circuit Breaker) 작성법도 간단합니다.
[SKILL EXECUTION HALTED]
Skill Name: backend-api-generator
Failure Reason: [Brief error description]
Attempts Made: [Number of retries]
Suggested Action: [Action required by backend developer]
파일 삭제나 DB 드롭처럼 위험한 작업에는 disable-model-invocation: true 옵션을 걸어두는 편이 안전합니다. 에이전트가 알아서 호출하지 못하게 막고 개발자가 직접 슬래시 명령(/skill-name)을 입력할 때만 실행되도록 제한하는 겁니다.
팀원들이 함께 스킬을 작성할 때는 agentskills.io 표준 디렉터리 아키텍처를 따라야 마크다운 파일 충돌로 고생하지 않습니다. 상위 폴더 안에 본문, CLI 스크립트, 참조 문서, 정적 템플릿 자산을 명확히 나눠 배치합니다.
| 디렉터리 및 파일 경로 | 역할 | 작성 지침 |
|---|---|---|
| skills/api-generator/SKILL.md | 필수 진입점 문서 | YAML 프런트매터와 핵심 절차 지침 포함 (500줄 이내) |
| skills/api-generator/scripts/ | Executable 코드 폴더 | 에이전트가 필요 시 호출하는 Python/Bash CLI 스크립트 위치 |
| skills/api-generator/references/ | 보조 참조 문서 폴더 | 대용량 API 명세, DB 스키마, 스타일 가이드 문서 수재 |
| skills/api-generator/assets/ | 정적 자원 템플릿 폴더 | 생성 코드 보일러플레이트, 설정 파일 샘플 저장 |
스킬 품질을 검증할 때는 promptfoo 평가 프레임워크를 활용합니다.
description: "Backend Agent Skills Validation Suite"
prompts:
- "file://skills/api-generator/SKILL.md"
providers:
- id: "anthropic:messages:claude-3-5-sonnet-20241022"
tests:
- description: "Test automatic skill activation for REST API generation query"
vars:
user_query: "Create a Spring Boot REST Controller for User Management."
assert:
- type: icontains
value: "backend-api-generator"
- type: javascript
value: "output.includes('@RestController') && output.includes('ResponseEntity')"
배포할 때는 짧은 호흡의 브랜치를 사용하는 트렁크 기반 개발 전략과 Git 태그(v1.2.0)를 조합합니다. 프로덕션에서 에이전트가 엉뚱한 동작을 하면 git checkout tags/v1.1.0 -b hotfix/rollback 명령으로 이전 태그 시점으로 바로 롤백할 수 있습니다.