에이전트 스킬

검색 방식

q는 휴대 가능한 SKILL.md Agent Skills 형식을 필요할 때 검색하는 계층으로 구현합니다. 전체 카탈로그와 스킬 본문은 기본 프롬프트 밖에 둡니다.

새 사용자 턴, task_start, ask_to_user가 반환한 답변에서 q는 스킬 메타데이터를 검색하고 이전에 보지 않은 후보 힌트를 최대 네 개까지 추가할 수 있습니다. 힌트 자체는 지침이 아닙니다. 모델은 스킬을 따르기 전에 반드시 get_skill을 호출해야 합니다.

스킬 도구가 있는 역할은 새 정보로 인해 추가 지침이 필요해졌을 때 search_skills를 직접 호출할 수도 있습니다.

어휘 순위는 스킬 이름, 태그, 설명 순으로 높은 가중치를 둡니다. 임베딩이 구성되면 q는 BM25와 벡터 후보를 융합합니다. 의미 후보의 신뢰도가 높지만 어휘 점수가 잡음 수준이라면 약한 BM25 기여를 제외해 언어 불일치가 강한 의미 결과를 묻지 않도록 합니다. 의미 신뢰도가 충분하지 않으면 전체 어휘 분기를 그대로 유지합니다.

검색 위치

q는 다음 위치를 낮은 우선순위부터 읽습니다.

가장 가까운 Git 루트 위치는 활성 워크스페이스와 다를 때만 사용합니다. 따라서 q를 하위 디렉터리에서 시작해도 파일 도구 경계를 넓히지 않고 휴대 가능한 저장소 스킬을 볼 수 있습니다.

제한된 두 결과 집합에 같은 스킬 이름이 있으면 워크스페이스 정의가 우선합니다.

스킬 작성

SKILL.md가 들어 있는 디렉터리를 만드세요.

frontmatter의 name은 정규 이름이지만 디렉터리 이름과 같을 필요는 없습니다. description은 선택 사항입니다. 지침이 결과를 실질적으로 바꾸는 작업에만 적용되도록 본문의 범위를 명확히 하세요.

스킬 관리

/skills를 열거나 q skills를 실행하세요. 두 패널은 q가 관리하는 위치를 나타냅니다.

왼쪽/오른쪽 또는 Tab으로 범위를 바꾸고, 위/아래로 선택합니다. A는 Git 저장소 복제, U는 fast-forward 업데이트, D는 확인 후 제거, R은 모든 루트 재검색과 인덱스 조정을 수행합니다.

.agents/skills에서 찾은 스킬은 카탈로그에 표시되지만 q 소유 디렉터리가 아니므로 읽기 전용입니다. 관리형 저장소는 루트에 SKILL.md가 있어야 하며, 목적지 이름은 저장소 URL이 아니라 검증된 frontmatter에서 가져옵니다.

새로고침과 인덱싱

임베딩 모델이 없으면 BM25 메타데이터 검색만 사용합니다. /model에서 모델을 할당하면 q는 BM25와 HNSW 벡터 결과를 결합합니다. 새 임베딩 모델을 할당하면 벡터 프로젝션을 다시 만들고 백필합니다.

q가 실행 중일 때 마지막 확인 후 30초 이상 지났다면 스킬 사용 시 워크스페이스 스킬 루트를 다시 조정합니다. /skills에서 q 소유 스킬을 관리하거나 명시적으로 재인덱싱할 수 있습니다.