query

query 스킬 개요

query 스킬이 하는 일

query 스킬은 연결된 작업용 데이터베이스나 직접 지정한 파일을 대상으로 DuckDB 쿼리를 실행하는 데 도움을 줍니다. 질문에서 결과까지 가장 빠르게 가고 싶은 사람을 위해 만들어졌으며, 즉석 SQL, 자연어 데이터 질문, DuckDB Friendly SQL을 이용한 간단한 파일 기반 분석에 잘 맞습니다.

어떤 사람에게 가장 잘 맞는가

이미 DuckDB 안에 데이터가 있거나, 프로젝트 상태 파일이 있거나, CSV/Parquet 같은 로컬 파일을 바로 분석하려는 경우라면 데이터 분석용으로 query 스킬을 쓰는 것이 좋습니다. 전체 파이프라인을 따로 세팅하지 않고도 즉시 답이 필요할 때 특히 유용하며, 분석가, 엔지니어, 그리고 데이터를 빠르게 반복 점검해야 하는 AI 에이전트에 잘 맞습니다.

이 스킬이 다른 이유

query의 핵심 차별점은 모드 선택입니다. 이전 DuckDB 상태가 있으면 세션 모드로 동작하고, 입력이 파일을 가리키거나 상태가 없으면 ad-hoc 모드로 전환합니다. 덕분에 추측이 줄어들고, query skill은 지속적인 워크플로와 일회성 워크플로 모두에서 쓸 수 있습니다.

query 스킬 사용 방법

설치와 기본 실행

npx skills add duckdb/duckdb-skills --skill query로 query 스킬을 설치합니다. 그런 다음 SQL이나 질문 형태로 호출하면 됩니다. 예: query "show daily revenue by country" 또는 query "select count(*) from 'events.csv'". query usage 패턴은 요청이 한 번의 명확한 쿼리로 바로 바뀔 수 있을 만큼 구체적일 때 가장 잘 작동합니다.

스킬이 세션 모드와 ad-hoc 모드를 고르는 방식

query 스킬은 먼저 .duckdb-skills/state.sql 또는 ~/.duckdb-skills/<project-id>/state.sql에 기존 DuckDB 상태 파일이 있는지 확인합니다. 파일을 찾고 연결된 데이터베이스도 정상적으로 동작하면 세션 모드를 사용합니다. --file을 넘기거나, 파일 경로를 참조하거나, 사용 가능한 상태가 없으면 ad-hoc 모드로 전환해 파일을 직접 조회하며, 필요할 때는 :memory:를 사용합니다. 이것은 query guide에서 가장 중요한 부분입니다. 실제로 원하는 모드에 맞게 입력해야 하기 때문입니다.

저장소에서 먼저 읽을 부분

먼저 SKILL.md를 보세요. 실행 흐름, 모드 규칙, 폴백 동작이 들어 있습니다. 설치 판단만 하려는 경우에는 보통 이것만으로 충분합니다. 이 스킬을 자신의 워크플로에 맞게 조정하려면 저장소 트리의 참조 파일들도 함께 살펴보는 것이 좋습니다. 특히 상태 처리나 프롬프트 제약을 정의하는 파일을 확인하세요. 이 repo에는 추가로 알아야 할 rules/, resources/, 보조 스크립트가 없습니다.

더 좋은 쿼리를 위한 프롬프트 작성

스킬이 올바른 쿼리를 만들 수 있도록 필요한 최소한의 맥락만 주세요: 대상 파일이나 테이블, 메트릭, 집계 단위, 필터, 시간 범위입니다. 좋은 입력 예시는 query "For orders.csv, show revenue by month for 2024 and exclude refunds"이고, 약한 입력 예시는 query "analyze the sales data"입니다. 첫 번째 예시는 파일 기반 접근을 써야 하는지, 무엇을 집계해야 하는지, 어떤 예외를 고려해야 하는지까지 알려줍니다.

query 스킬 FAQ

query 스킬은 SQL 전문가만 쓰는 도구인가요?

아닙니다. query 스킬은 raw SQL도 받고 자연어 질문도 받아서, 초보자도 기본적인 분석에 사용할 수 있습니다. 다만 정확한 조인, 필터, 집계 규칙이 필요할 때는 SQL이 여전히 유리합니다.

언제 query 스킬을 쓰지 말아야 하나요?

노트북, ETL 작업, 애플리케이션 코드에 들어갈 다단계 변환 로직이 필요한 작업이라면 사용하지 않는 것이 좋습니다. 이 스킬은 데이터 질문을 묻고 답하는 데 최적화되어 있으며, 완전한 데이터 제품을 만드는 용도는 아닙니다.

일반 프롬프트와 비교하면 어떤가요?

일반 프롬프트는 그럴듯한 쿼리를 만들어낼 수는 있지만, query 스킬은 운영 규칙이 추가됩니다. DuckDB 상태를 확인하고, session 모드와 ad-hoc 모드를 고르며, DuckDB 사용 가능 여부를 검증하고, 연결 실패 시 안전하게 폴백합니다. 그래서 설치 시 평가나 반복적인 query usage에서 더 신뢰할 수 있습니다.

파일과 로컬 분석에 잘 맞나요?

네. 로컬 CSV, Parquet, 또는 다른 DuckDB-readable 파일에 대해 query for Data Analysis를 하고 싶다면 이 스킬은 매우 잘 맞습니다. 세션 상태가 없거나 적절하지 않을 때 파일을 직접 조회하도록 설계되어 있기 때문입니다.

query 스킬 개선 방법

정확한 데이터 형태를 알려 주세요

가장 큰 개선 효과는 소스와 출력 형태를 정확히 적는 데서 나옵니다. 테이블 이름, 파일 이름, 관심 있는 컬럼, 원하는 반환 단위를 포함하세요. 예를 들어 query "from sessions.parquet, group by user_id and return avg session length for paid users only"처럼 쓰면, 스킬이 너무 넓거나 모호한 결과를 피하기 위한 구조를 충분히 얻을 수 있습니다.

첫 실행 전에 모호함을 줄이세요

흔한 실패 유형은 무엇을 세어야 하는지, 비교해야 하는지, 필터링해야 하는지 말하지 않은 채 “insights”를 요청하는 것입니다. 알고 있는 메트릭, 날짜 범위, 세그먼트 규칙이 있다면 처음부터 넣으세요. 그러면 왕복 질문이 줄고 첫 답변이 훨씬 유용해집니다.

모드별 제약을 초기에 확인하세요

세션 모드를 기대한다면 프로젝트 상태가 존재하고 연결된 데이터베이스가 아직 열려 있는지 확인하세요. 파일 모드를 기대한다면 프롬프트에서 파일을 직접 참조하거나 --file을 넘기세요. query 스킬은 기존 상태를 재사용할 수 있는지, 아니면 ad-hoc으로 처리해야 하는지에 따라 다르게 동작하기 때문에 이 점이 중요합니다.

쿼리 목표를 점점 좁히며 반복하세요

첫 결과를 받은 뒤에는 한 번에 하나씩 제약을 더해 다음 프롬프트를 개선하세요. 더 좁은 기간, 더 적절한 조인 키, 다른 그룹핑 수준, 반드시 제외해야 하는 항목 같은 것들입니다. 이렇게 해야 query skill이 막연한 요약이 아니라 의사결정에 바로 쓸 수 있는 결과로 수렴합니다.