agent-skills
무엇인가
Qt 애플리케이션 개발과 품질 보증에 필요한 판단 절차를 에이전트에 주입하는 공식 스킬 묶음이다. C++·QML 리뷰, QML 테스트 작성과 실행, CMake 프로젝트 구성, UI 설계, 문서 생성, QML 프로파일링 영역을 각각 별도 스킬 디렉터리로 나누어 규율한다. 리뷰 계열은 결정적 린터와 AI 심층 분석을 결합하고, 개념 계열은 LLM이 반복적으로 틀리는 선언형 QML, C++/QML 경계, Widgets 패턴 같은 지점의 멘탈 모델을 교정한다.
어떻게 동작하나
각 스킬은 디렉터리 하나에 SKILL.md 진입점을 두고, YAML frontmatter의 name과 description으로 자신을 설명한다. name은 소문자·하이픈 조합 64자 이하로 디렉터리명과 일치해야 하고, description은 무엇을 하는지와 언제 쓰는지를 첫 250자 안에 담아야 한다. 에이전트는 시작 시 name·description만 읽고, 스킬이 발동하면 SKILL.md 본문을 읽으며, references/ 아래 린트 스크립트와 체크리스트는 필요할 때만 가져온다. 본문은 500줄 이하로 유지하고 상세 내용은 references/로 분리하는 점진적 공개 규약을 쓴다.
무엇과 다른가
프롬프트에 Qt 규칙을 직접 적어 넣는 방식과 달리 규칙이 저장소 안 파일로 존재해 버전 관리되고 여러 프로젝트에서 재사용된다. 단일 CLAUDE.md나 AGENTS.md에 모든 지침을 몰아넣는 방식과도 다르다. 스킬별로 디렉터리를 분리하고, 결정적 린터 스크립트와 병렬 분석 에이전트를 references/에 함께 두며, 다중 파일 디렉터리를 읽지 못하는 도구를 위한 자체 완결형 축약본을 platforms/ 아래 별도로 둔다.
어떻게 쓰나
Claude Code에서는 플러그인 마켓플레이스를 등록한 뒤 플러그인을 설치하거나, 스킬 디렉터리를 ~/.claude/skills/로 심볼릭 링크·복사해 붙인다. Claude Code는 스킬을 자동 발견하므로 재시작이 필요 없다. Codex CLI에서는 Vercel의 크로스 플랫폼 설치기로 저장소를 지정하거나 ~/.codex/skills/로 직접 복사한다. 저장소에는 Claude Code 플러그인 설정과 Gemini CLI 확장 매니페스트, Qt 문서 MCP 서버 등록 파일이 함께 들어 있다.
전제와 한계
Claude Code, Codex CLI, GitHub Copilot에서 네이티브로 동작하고 Gemini CLI용 확장 매니페스트도 제공한다. 다만 스크립트나 서브에이전트를 실행할 수 없는 도구는 정적 지침만 읽어 결과가 얕아진다. 예를 들어 GitHub Copilot은 리뷰 스킬의 린터와 병렬 에이전트 없이 정적 가이드만 로드한다. Qt 상용 라이선스로 사용하려면 Qt AI Services 약관에 대한 동의가 선행되어야 하며, 출력은 AI 생성물이므로 검증이 필요하다.