장부 파일 옆에 SKILL.md 파일을 두면 bea ask가 여러분의 부기 규칙을 따릅니다 — 카테고리 이름, 보고서 형식, 내부 규칙 등 — 매 질문마다 반복하지 않아도 됩니다.
스킬은 간단한 YAML 헤더가 있는 일반 Markdown입니다. bea ask는 시작 시 이를 발견하여 호스팅된 어시스턴트에 제공하며, 어시스턴트는 질문이 필요할 때 전체 텍스트를 로드합니다.
이 페이지는 bea ask가 이미 작동하고 있다고 가정합니다. ask 추가 기능(uv tool install 'beancount-io[ask]')과 bea cloud login 또는 BEA_TOKEN을 통한 Beancount.io 자격 증명이 필요합니다. 쿼리는 로컬 장부에 대해 실행되지만, 질문과 스킬 컨텍스트는 호스팅된 Beancount.io AI 서비스로 전송됩니다. bea ask에는 JSON 출력이 없습니다. 전체 명령 계약은 CLI 참조를 참조하세요.
스킬이 위치하는 곳
bea ask는 다음 두 디렉토리를 이 순서로 읽습니다:
| 위치 | 범위 |
|---|---|
<ledger-dir>/.agents/skills/ | 프로젝트 수준 — 하나의 장부, 보통 저장소에 커밋됨 |
~/.config/bea/skills/ | 사용자 수준 — 이 머신에서 여는 모든 장부 |
프로젝트 디렉토리는 --file이 아닌 bea ask를 실행하는 작업 디렉토리에서 결정됩니다. 두 디렉토리에 같은 name을 가진 스킬이 있을 때 프로젝트 복사본이 우선하며 사용자 복사본은 무시됩니다.
BEA_CONFIG_DIR는 사용자 수준 디렉토리를 재배치합니다: 설정하면 스킬은 $BEA_CONFIG_DIR/skills/에서 읽힙니다. 그렇지 않으면 $XDG_CONFIG_HOME/bea/skills/가 적용되며, 이도 없으면 ~/.config/bea/skills/로 대체됩니다.
스킬 파일 작성하기
스킬당 하나의 디렉토리에 SKILL.md라는 이름의 파일 하나를 둡니다:
.agents/skills/
└── monthly-report/
└── SKILL.md파일은 YAML 헤더 뒤에 지침이 옵니다:
---
name: monthly-report
description: Generates monthly expense summaries grouped by category.
---
When the user asks for a spending summary or monthly report:
1. Group all expenses by the top-level account category.
2. Show totals for each category, sorted highest to lowest.
3. Include a grand total at the end.
4. Always specify the currency next to each amount.두 필드는 필수입니다. 둘 중 하나라도 없는 파일은 조용히 건너뛰므로, 스킬이 없는 경우는 대개 헤더 문제입니다.
| 필드 | 필수 | 기능 |
|---|---|---|
name | 예 | 소문자와 하이픈으로 구성. 디렉토리 이름과 동일하게 유지하세요 — 두 위치 간 우선순위는 이 값으로 매칭되므로, 불일치하면 재정의를 예측하기 어렵습니다. |
description | 예 | 어시스턴트에게 스킬을 언제 적용할지 알려주는 한 줄. 어시스턴트가 본문을 로드하기 전에 보는 내용입니다. |
license | 아니요 | 자유 텍스트, 스킬과 함께 기록됩니다. |
compatibility | 아니요 | 자유 텍스트, 스킬과 함께 기록됩니다. |
metadata | 아니요 | 키-값 맵, 스킬과 함께 기록됩니다. |
allowed-tools | 아니요 | 공백으로 구분된 목록, 파싱되어 기록됩니다. |
본문은 동료에게 지시하듯 작성하세요: 무엇을, 어떤 순서로, 결과를 어떻게 제시할지. 진정으로 여러분의 것인 규칙만 유지하세요. 어시스턴트가 장부에서 직접 읽을 수 있는 사실은 스킬에 포함할 필요가 없습니다.
allowed-tools는 권한 경계가 아닙니다. bea 0.1.0은 필드를 파싱하지만 그 외에는 아무것도 읽지 않으므로, 아무것도 제한하지 않습니다. 의도 문서로 취급하세요. 실제로 적용되는 제어는 명령 자체에 있습니다: 대화형 쓰기는 파일에 적용되기 전에 미리 보기, 확인, 검증이 이루어지며, 전역 --yes는 쓰기 권한을 부여하지 않고, --print 모드는 제안된 쓰기를 절대 적용하지 않습니다.
로드되었는지 확인하기
일회용 스킬에 절대 놓칠 수 없는 지침을 넣고, 아무 질문이나 하세요.
스킬을 만드세요:
mkdir -p .agents/skills/test-skill
cat > .agents/skills/test-skill/SKILL.md << 'EOF'
---
name: test-skill
description: Test skill to verify skill loading works.
---
IMPORTANT: Whenever the user asks any question, start your response with the exact phrase "SKILL LOADED".
EOF한 답변 모드에서 질문하세요:
bea ask "what accounts do I have?" --printSKILL LOADED로 시작하는 응답은 스킬이 발견되어 어시스턴트에게 제공되었음을 의미합니다.
그런 다음 그 문구가 스킬에서 나온 것임을 증명하려면, 디렉토리를 스킬 트리 밖으로 옮기고 다시 질문하세요:
mv .agents/skills/test-skill ./test-skill.off
bea ask "what accounts do I have?" --print
mv ./test-skill.off .agents/skills/test-skill문구가 사라져야 합니다. 디렉토리를 제자리에서 이름을 바꾸지 말고 .agents/skills/ 밖으로 옮기세요: 발견은 헤더의 name 필드로 매칭되므로, test-skill.bak으로 이름을 바꾼 디렉토리는 여전히 발견되고 로드됩니다.
사용자 수준 스킬을 확인하려면 같은 파일을 ~/.config/bea/skills/test-skill/SKILL.md에 두고 반복하세요. 우선순위를 확인하려면 같은 name으로 두 복사본을 유지하고 서로 다른 문구를 주세요: 프로젝트 문구가 보여야 합니다.
테스트 스킬은 끝나면 정리하세요. 해당 디렉토리에서 하는 모든 질문에 적용됩니다.
bea ask용 스킬은 에이전트용 스킬이 아닙니다
이 스킬들은 내장된 bea ask 도우미만 확장합니다. 이는 Claude Code나 Codex와 같은 외부 코딩 에이전트에 설치하여 외부에서 bea 명령을 구동하는 정식 Beancount.io 스킬과는 다른 것입니다. 이 목적이라면 AI 에이전트로 회계하기를 대신 읽으세요 — 외부 에이전트 레시피를 처음부터 끝까지 다루며, ask 추가 기능이나 호스팅 계정이 필요하지 않습니다.