스킬 추가하기
이 저장소에서 공개 스킬 작업 시 이 문서를 사용하세요. 일반적인 스킬 변경 사항은
skills/<skill-name>/에 유지하고, 저장소 전용 안내는 .agents/skills/ 아래에 보관하세요.
먼저 스킬 종류 결정하기
- 일반 공개 스킬:
skills/<name>/아래에SKILL.md가 있는 일반 폴더입니다. 이것이 가장 일반적인 경우입니다.@agent-native/skills는BuilderIO/skills@main에서 이를 동적으로 발견하므로npx @agent-native/skills@latest add --skill <name>을 작동하게 하기 위해 프레임워크 레지스트리를 편집할 필요가 없습니다. - 명령형 스킬: 사용자가
--update-instructions를 전달할 때 선택적으로 항상 활성화된 관리형AGENTS.md/CLAUDE.md라인을 작성해야 하는 일반 스킬입니다. 이러한 스킬은 하나의 추가 프레임워크 변경이 필요합니다. 아래 "관리형 명령 블록"을 참조하세요. - 앱 기반 / MCP 스킬: 호스팅/로컬 MCP 서버를 등록하거나 프레임워크 소유 설치 동작을
사용하는 스킬입니다. 일반 공개 스킬이 아닙니다;
../agent-native/framework/packages/core/src/cli/skills.ts와../agent-native/framework/packages/skills/src/built-in-apps.ts를 검사하세요. - Plan 스킬:
visual-plan과visual-recap은 이 저장소와../agent-native/framework사이에 생성/동기화된 복사본이 있습니다. 독립형 산문 폴더처럼 취급하지 마세요.
일반 공개 스킬 체크리스트
-
skills/<skill-name>/SKILL.md를 생성하거나 업데이트하세요. -
스킬이 공개 카탈로그에 표시되어야 하는 경우
skills/<skill-name>/README.md를 추가하세요. 이 저장소는 공개 스킬 페이지에 README를 의도적으로 사용합니다. -
컬렉션 위치가 변경되면 루트
README.md,.codex-plugin/plugin.json,.claude-plugin/plugin.json, 그리고package.json설명을 업데이트하세요. -
스킬을 간결하게 유지하세요. 필수 에이전트 지침만
SKILL.md에 넣고; 스킬을 직접 지원하지 않는 추가 문서는 피하세요. -
다음 명령으로 검증하세요:
python3 /Users/steve/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/<skill-name> -
CLI 경로가 작동한다고 주장하기 전에 로컬에서 설치 검색을 테스트하세요:
node ../agent-native/framework/packages/skills/dist/cli.js add --copy . --skill <skill-name> --client codex --scope project --dry-run --json -
npm run check를 실행하세요. 변경 사항과 관련 없는visual-plan/visual-recap동기화에서 실패하면 해당 스킬을 무심코 다시 작성하는 대신 구체적으로 보고하세요.
@agent-native/skills 설치 경로
일반 공개 스킬의 경우 설치 경로는 동적입니다:
-
../agent-native/framework/packages/skills/src/index.ts는DEFAULT_SKILLS_SOURCE = "BuilderIO/skills"로 설정합니다. -
해당 저장소를 구체화하고,
resolveSkillsRoot를 통해 플러그인 매니페스트를 읽고,discoverSkills를 통해 모든skills/*/SKILL.md를 발견합니다. -
따라서
skills/<name>/아래에 새 폴더를 만드는 것만으로도 다음 명령이 작동합니다:npx @agent-native/skills@latest add --skill <name>
스킬이 앱 기반이거나 사용자 지정 설치 동작이 필요한 경우가 아니라면
@agent-native/core 내장 레지스트리 변경이 필요하지 않습니다.
관리형 명령 블록
스킬이 --update-instructions를 통해 AGENTS.md / CLAUDE.md에
영향을 주어야 하는 경우 프레임워크 래퍼를 업데이트하세요:
-
../agent-native/framework/packages/skills/src/index.ts의instructionContentForSkill(skillName)내부에 간결한 라인을 추가하세요. -
../agent-native/framework/packages/skills/src/index.spec.ts에서 테스트를 추가하거나 업데이트하세요. -
다음을 실행하세요:
pnpm --filter @agent-native/skills test -- src/index.spec.ts --runInBand
quick-recap, efficient-fable, stay-within-limits와 같은 지속적인 동작 규칙과
read-the-damn-docs와 같은 문서 우선 동작에 이 기능을 사용하세요.
앱 기반 또는 MCP 스킬
스킬에 호스팅된 도구, 인증, MCP 등록, 로컬 파일 모드 또는 특수 설치 플래그가 필요한 경우 편집 전에 프레임워크를 검사하세요:
../agent-native/framework/packages/core/src/cli/skills.ts../agent-native/framework/packages/skills/src/built-in-apps.ts../agent-native/framework/packages/skills/src/sync-with-core.spec.ts
핵심 및 독립형 @agent-native/skills MCP 설명자를 동기화된 상태로 유지하세요.
Plan 스킬 동기화 주의사항
visual-plan과 visual-recap은 특별합니다:
- 프레임워크에는 정식/생성된 복사본과 Plan 마켓플레이스 번들이 포함되어 있습니다.
- 이 저장소의
npm run check는 이러한 복사본을 비교하며 새 일반 스킬과 관련 없는 드리프트로 인해 실패할 수 있습니다. - Plan 스킬을 의도적으로 변경할 때는 생성된 복사본을 수동 편집하는 대신
프레임워크 동기화 경로를 사용하세요. 프레임워크에서
sync-plan-marketplace,sync-workspace-skills, 그리고skills.sync.spec.ts를 검색하세요.
최종 보고
스킬 변경을 완료하면 사용자에게 다음을 알리세요:
- 어떤 스킬 파일이 변경되었는지.
@agent-native/skills동적 설치 검색으로 충분한지.- 프레임워크 관리형 명령 변경이 추가되었는지 또는 의도적으로 후속 작업으로 남겨졌는지.
- 어떤 검증 명령이 통과 또는 실패했는지, 관련 없는 Plan 동기화 실패를 포함하여.