Kulaxyz/self-learning-skills

self‑learning‑skills – AI 코딩 에이전트를 위한 메타 스킬

개요

• 모든 AI 기반 코딩 어시스턴트(Claude Code, Cursor, Codex, Aider, Gemini‑CLI, Zed 등)에 추가할 수 있는 작은 "스킬"입니다.
• 목적은 코드를 직접 작성하는 것이 아니라, 디버깅이나 배포 세션 중에 에이전트가 발견한 단계를 기억하고 향후 세션에서 자동으로 재현하는 것입니다.

중요성

• LLM 기반 에이전트를 사용할 때, 새로운 세션을 시작할 때마다 "프로덕션 DB에 어떻게 연결하지?" 또는 "배포 명령어가 뭐였지?"와 같은 발견 과정을 반복해야 하는 경우가 많습니다. 이 스킬은 힘들게 얻은 "골든 패스"(실패한 방법 포함)를 캡처하여 에이전트가 다음에 자동으로 로드할 수 있는 곳에 저장함으로써, 임시방편적인 문제 해결을 재사용 가능한 지식으로 바꿉니다.

작동 방식

1. 인식 – 스킬은 에이전트의 출력을 모니터링하여 신호(예: 사용자가 *"이걸 기억해"*라고 말하거나, 에이전트가 여러 번의 시도 끝에 성공하는 경우)를 기다립니다.
2. 캡처 – 절차(또는 단일 사실)에 대한 간결하고 독립적인 설명을 생성하며, 관련이 있는 경우 피해야 할 실패한 시도에 대한 메모를 기록합니다.
3. 재사용 – 다음 세션에서는 저장된 항목이 새로운 스킬(다단계 워크플로우용) 또는 가벼운 메모(단일 사실용)로 자동 로드됩니다. 에이전트는 단계를 다시 도출할 필요 없이 이를 적용할 수 있습니다.

도구별 지속성

에이전트 / 도구	지식 저장 위치	자동 로드 방식
Claude Code, Codex, 기타 Agent Skills 클라이언트	skills/<name>/SKILL.md	Agent Skills 프레임워크의 스킬 매칭 로직
Cursor	.cursor/rules/learned/<name>.mdc	Cursor의 규칙 매칭 메커니즘
Zed, Aider, Gemini‑CLI, AGENTS.md를 읽는 도구	AGENTS.md (또는 프로젝트 전체 메모)	시작 시마다 파일 읽기

설치 옵션

• npx를 통한 한 줄 명령(권장) – 설치된 에이전트를 감지하고 적절한 파일을 배치합니다:

  npx skills add kulaxyz/self-learning-skills          # 현재 프로젝트에 로컬 추가
  npx skills add kulaxyz/self-learning-skills -g      # 모든 프로젝트에 전역 추가
  npx skills add kulaxyz/self-learning-skills -a claude-code  # Claude Code 전용
  

• Claude Code 플러그인 – 내장 마켓플레이스를 통해 추가:

  /plugin marketplace add kulaxyz/self-learning-skills
  /plugin install self-learning@self-learning-skills
  

• 수동 복사 – 리포지토리를 복제하고 관련 디렉토리/파일을 적절한 위치에 복사합니다(README의 "Manual" 섹션 참조).

승격 규칙(품질 가드) 캡처된 항목은 세 가지 조건 모두를 충족할 때만 스킬이 됩니다:

1. 절차가 검증됨(테스트 통과, 빌드 성공 등).
2. 피해야 할 실패 패턴이 명시적으로 명명됨.
3. 시도했다가 제외된 막다른 길(dead-end)이 최소 하나 이상 기록됨. 조건이 하나라도 부족하면 항목은 임시 메모로 남거나 삭제되어, 검증되지 않은 추측이 스킬 세트를 오염시키는 것을 방지합니다.

안전 고려 사항

• 이 스킬은 실제 비밀값을 절대 기록하지 않습니다. 비밀값이 어디에 있는지(예: 환경 변수 이름, 비밀 관리자 조회)만 기록합니다.
• 생성된 파일은 커밋될 것을 전제로 하므로, 설계상 자격 증명 유출을 의도적으로 방지합니다.

리포지토리 구조(빠른 지도)

self-learning-skills/
├─ AGENTS.md                # AGENTS 지원 도구를 위한 범용 루프 설명
├─ skills.sh.json           # `npx skills` 설치 프로그램용 매니페스트
├─ .claude-plugin/…         # Claude Code 마켓플레이스 메타데이터
├─ skills/self-learning/    # 핵심 스킬 파일 (SKILL.md, 템플릿, 문서)
└─ .cursor/rules/…          # Cursor 규칙 및 learned‑rules 폴더

일반적인 사용 사례

1. LLM 에이전트와 디버깅 세션을 시작합니다.
2. 여러 번의 시도 끝에 데이터베이스를 마이그레이션하는 올바른 명령어를 발견합니다.
3. *"이걸 기억해"*라고 말합니다(또는 스킬이 성공을 자동으로 감지합니다).
4. 스킬은 마이그레이션 단계와 실패한 시도를 설명하는 SKILL.md(또는 Cursor용 .mdc)를 작성합니다.
5. 다음 세션에서 에이전트는 스킬을 자동으로 로드하고, 시행착오를 다시 겪을 필요 없이 마이그레이션을 실행할 수 있습니다.

제한 사항

• Agent‑Skills 표준을 지원하거나 AGENTS.md를 읽는 기반 에이전트에 의존합니다. 이러한 후크가 없는 도구에서는 사용할 수 없습니다.
• "순간을 인식하는" 감지는 휴리스틱 방식입니다. 신호를 놓치면 지식이 캡처되지 않습니다.
• 승격 규칙은 검증 단계를 통과해야 하므로, 순수 정보성 사실(예: "프로덕션 DB URL은 DATABASE_URL에 있음")은 실행 가능한 스킬이 아닌 가벼운 메모로만 저장됩니다.

라이선스

• MIT © kulaxyz (LICENSE 참조).