Community라이팅 & 에디팅github.com

FrancescoBorzi/agent-toolkit

미니멀하고 프로젝트에 독립적인 AI 코딩 에이전트용 스킬 및 규칙 모음입니다.

agent-toolkit란 무엇인가요?

이 스킬은 AI 코딩 에이전트(Claude Code, Cursor, Codex 등)가 다양한 이슈 트래커(Azure DevOps, Jira, GitHub 등)에서 티켓을 가져와 프로젝트 로컬에 구조화된 `.TICKET.md` 파일로 저장하는 방법을 제공합니다. 에이전트는 입력된 URL이나 ID를 기반으로 적절한 MCP 서버를 찾아 연결하고, 티켓의 모든 필드, 댓글, 첨부 파일, 관련 링크를 가져옵니다. 첨부 파일은 디스크에 직접 저장되며, 이미지는 포함(embed)되고, PDF 등의 파일은 연결(link)됩니다. 이 도구는 티켓을 분석하거나 수정하지 않고 순수하게 가져오기(fetch)만 수행하며, 작업 완료 후 정리된 명령어를 제공하여 다음 단계(예: 티켓 리파인)로 쉽게 넘어갈 수 있도록 돕습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add FrancescoBorzi/agent-toolkit

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

미리보기

스킬 README에서

attachment-1
figma-<nodeId>

문서

Ticket Fetcher

가져오기만 — 분석, 요구사항 도출, 계획 수립 없음. 결과는 자체 포함된 .TICKET.md 파일입니다.

출처 및 접근

입력(URL 호스트 또는 ID 형태)에서 트래커를 식별하고 일치하는 MCP 서버를 통해 가져옵니다. 예를 들어 Azure DevOps MCP는 ADO 작업 항목, Atlassian MCP는 Jira 이슈, **GitHub MCP / gh**는 GitHub 이슈를 처리합니다. 연결된 동등한 도구를 사용하세요. 도구 이름 접두사는 구성에 따라 다릅니다. MCP에 필요한 핸들(예: Atlassian cloudId, ADO 프로젝트)을 한 번 확인하고 재사용합니다. 입력이 모호하면 사용자에게 물어보고 추측하지 마세요. 일치하는 MCP가 연결되지 않은 경우: 공개 티켓은 URL에서 대체 수단으로 스크래핑할 수 있습니다(일치하는 MCP를 설치하는 것이 더 나을 경우 제안 가능). 비공개 티켓은 URL이 로그인 페이지만 반환하므로 가져올 수 없습니다. 이 경우 중단하고 사용자에게 일치하는 MCP 서버를 설치하고 인증한 후 다시 실행하도록 안내하세요.

작업 내용

  1. 입력 해석. 전체 티켓 URL 또는 bare ID/키를 받아 식별자를 추출합니다. 트래커가 키 접두사(예: XX-1234)를 사용하면 유지하고, 그렇지 않으면 숫자만 사용합니다. 입력을 인식할 수 없으면 질문합니다.
  2. 티켓 가져오기. 전체 필드 세트, 인라인 댓글, 관련 링크/관계를 포함한 작업 항목/이슈를 가져옵니다. 티켓이 담고 있는 모든 것을 캡처합니다. 고정된 필드 집합으로 미리 필터링하지 마세요. 받은 리치 텍스트 형식(HTML, ADF 등)을 깨끗한 Markdown으로 변환합니다.
  3. 슬러그 선택. 제목/요약에서 3-5단어로 된 짧은 케밥-케이스 슬러그를 만듭니다. 검색 가능해야 하며, 지나치게 고민하지 마세요.
  4. 출력 디렉토리 결정. 프로젝트의 계획 디렉토리(예: .claude/plans/) 내에 프로젝트 상대 경로인 <id>-<slug>/ 하위 디렉토리를 만듭니다. 프로젝트/사용자의 계획 저장 규칙을 따르고, 정의되지 않은 경우 사용자에게 물어보세요. 추측하지 마세요. 디렉토리가 이미 존재하면 <id>-<slug>-v2, -v3 등을 제안하세요. 기존 계획 디렉토리를 덮어쓰지 마세요. 재가져오기 시 히스토리가 의도적으로 보존됩니다.
  5. 티켓 파일 작성 <output-dir>/<id>-<slug>.TICKET.md
  6. 첨부 파일 다운로드 출력 디렉토리로 다운로드하고 실패 시 경고합니다(첨부 파일 참조).
  7. 결과 출력 — 프로젝트 상대 경로 및 다음 단계 라인(다음 단계 참조).

티켓 파일 구조

자체적으로 완결되어야 합니다: 재가져오기 없이도 새 세션이 출처를 식별할 수 있을 만큼 충분한 메타데이터와 함께 티켓의 완전하고 읽기 쉬운 버전입니다.

헤더

출처 메타데이터가 포함된 일반 마크다운 헤더입니다. 값이 없는 줄은 생략합니다. 트래커가 제공하는 모든 것을 포함합니다. 예시:

# <제목 / 요약>

> **출처** [<id>](<url>)
> **유형** {type}
> **상태** {status}
> **담당자** {표시 이름 또는 "—"}
> **보고자 / 작성자** {표시 이름}
> **레이블 / 태그** {연결된 값 또는 "—"}
> **가져온 날짜** {오늘 YYYY-MM-DD}

본문 섹션

존재하고 비어 있지 않은 경우에만 다음 순서로 작성합니다:

  1. ## 설명
  2. ## 수락 기준 — 트래커에 전용 AC 필드가 채워져 있는 경우
  3. ## <기타 필드> — 실제 콘텐츠를 담고 있는 다른 채워진 필드(기술 노트, 사용자 정의 필드 등)당 하나의 섹션, 필드의 표시 이름을 제목으로 사용합니다. 티켓이 보유한 모든 것을 캡처합니다.
  4. ## 댓글 — 가장 오래된 것부터, 각각 ### <작성자> — <날짜> 다음에 본문이 옵니다. 최선의 노력: 댓글이 반환되지 않으면 간략히 언급하거나 섹션을 생략합니다.
  5. ## 관련 티켓 — 아래 참조
  6. ## 첨부 파일 — 아래 참조
  7. ## 디자인 참조 — 아래 참조

제목 계층 구조, 글머리 기호 구조, 강조, 코드 블록을 유지합니다. 필드 내 하위 제목은 ####로 매핑합니다. 빈 섹션은 생략합니다. 사용자 대상 문자열, 코드 식별자, 파일 경로, i18n 키 및 URL은 그대로 인용합니다. 절대 변경하거나 번역하지 마세요.

관련 티켓

응답의 링크/관계(및 원격 링크 도구)에서, 연결된 각 고유 티켓(현재 티켓 제외)에 대해 제목 + 상태 + 유형만 간단한 호출로 가져옵니다. 전체 본문은 가져오지 않습니다. 주요 목표는 모든 관련 티켓의 추적을 남겨 나중에 필요할 때 가져올 수 있도록 하는 것입니다. 사용 가능한 관계와 함께 각각 한 줄의 글머리 기호로 표시합니다:

- [<id>](<url>) — (<type>, <status>) <title>

비-티켓 원격 링크(예: 위키/Confluence 페이지)의 경우 제목과 URL을 일반 글머리 기호로 표시합니다. 가져오기에 실패하면 전체 실행을 실패로 처리하지 않고 (가져올 수 없음)과 함께 링크를 나열합니다.

첨부 파일

설명/필드에서 참조된 모든 첨부 파일과 인라인 이미지를 식별하고, 처음 나타난 순서대로 번호를 매깁니다(attachment-<N>.<ext>). 원본 확장자를 유지합니다. <N>은 두 가지를 합쳐서 순서대로 적용됩니다.

항상 가져오기를 시도합니다 — 연결된 모든 MCP를 통해. 트래커 호스팅 첨부 파일 외에도 티켓은 외부 자산(예: Confluence/ADO 리소스 — Figma 또는 Zeplin 같은 디자인 도구 링크는 아래 디자인 참조 참조)을 연결할 수 있으며, 해당 자체 MCP를 통해 접근 가능합니다. 연결된 git 저장소의 spec/doc 파일(내용을 git 또는 저장소 MCP를 통해 가져와 출력 디렉토리에 자체 파일명으로 저장)도 포함됩니다. 소스에 맞는 MCP를 사용하여 다운로드합니다. 링크를 미리 가져올 수 없다고 선언하지 마세요. 적합한 MCP가 연결되어 있지만 인증되지 않은 경우, 조용히 건너뛰지 말고 요청을 기다리지 않고 적극적으로 인증 흐름을 실행(로그인 URL 표시, 핸드셰이크 완료)한 다음 가져옵니다. 자산을 다운로드할 수 있는지 또는 다운로드해야 하는지 불분명한 경우 사용자에게 문의하세요.

각 파일을 디스크에 직접 다운로드합니다. curl -fSL <url> -o attachment-<N>.<ext> 또는 MCP 첨부 파일 도구의 save-to-path 변형을 사용합니다. 절대 첨부 파일을 인라인 base64로 모델을 통해 라우팅하고 다시 내보내지 마세요. 출력 제한(~100k 문자)으로 인해 조용히 잘릴 수 있습니다. 유효한 헤더에 누락된 트레일러가 있어 파일이 열리지 않습니다. 일부 첨부 파일 MCP 도구는 save-to-path 옵션 없이 base64만 반환합니다(예: ADO wit_get_work_item_attachment). 바이너리의 경우 이를 사용하지 말고, 대신 전달자 토큰을 사용하여 트래커의 REST API에서 디스크로 직접 가져옵니다(ADO: az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv, 그 다음 curl -H "Authorization: Bearer <token>" "<attachmentUrl>" -o attachment-<N>.<ext>). (콘텐츠 URL은 종종 MCP의 인증을 공유합니다. 401 오류 시 획득 가능한 트래커의 전달자 토큰으로 재시도합니다.)

전송 여부뿐만 아니라 무결성을 확인합니다. 비어 있지 않은지, Content-Length가 전송되면 일치하는지, 유형 트레일러가 있는지(PNG IEND, JPEG FFD9, PDF %%EOF) 확인합니다. 크기가 3의 정확한 배수이면서 반올림 문자 경계에 가까우면 base64 잘림을 나타냅니다. 실패 시 디스크에 다시 다운로드합니다. 여전히 문제가 있으면 다운로드되지 않은 것으로 처리하고 경고합니다. 손상된 파일을 참조하지 마세요. 그런 다음 파일별로:

  • 다운로드됨 → 로컬 파일을 참조합니다.
  • 다운로드되지 않음(적합한 MCP/첨부 파일 도구 없음, 완료할 수 없는 인증 등) → 로컬 파일과 소스 URL을 계속 참조하고 경고 목록에 추가합니다. 차단하지 마세요. 티켓은 어느 쪽이든 사용할 수 있습니다.

이미지는 포함(embed), 비-이미지(PDF, .docx 등)는 링크:

### 첨부 파일 1

![attachment-1](attachment-1.png)
_원본 파일명: image.png_

### 첨부 파일 2

[attachment-2.pdf](attachment-2.pdf) — _원본 파일명: design-spec.pdf_

다운로드할 수 없는 파일의 경우 사용자가 수동으로 가져올 수 있도록 소스를 추가합니다: — 다운로드되지 않음; 다음에서 가져와서 여기에 attachment-<N>.<ext>로 저장하세요: <url>.

디자인 참조

설명/댓글에 있는 디자인 도구 링크(Figma, Zeplin, Sketch, Adobe XD 등)의 경우 attachment-<N>으로 번호를 매기지 마세요. 그것들은 연결된 파일이 아닌 실시간 참조입니다. 해당 도구의 MCP(예: Figma MCP get_screenshot)를 통해 각 참조된 프레임/화면을 캡처하고, 반환된 단기 URL을 디스크에 <tool>-<id>-<slug>.png로 직접 다운로드합니다(필요하면 먼저 해당 MCP를 인증합니다. 첨부 파일 참조). 해당 도구의 MCP가 연결되지 않은 경우, 이름과 소스 URL로 항목을 기록하고 경고 목록에 추가합니다. 다운로드되지 않은 첨부 파일과 동일하게 처리합니다. 각 링크당 하나의 항목을 기록하며, 로컬 미리보기와 해당 도구에서 다시 열기 위해 필요한 식별자를 포함합니다:

### <디자인 이름>

![figma-<nodeId>](figma-<nodeId>-<slug>.png)
_Figma · 파일 `<fileKey>` · 노드 `<nodeId>` · [출처](<url>)_

경계

  • 분석, 계획 또는 코드베이스 탐색을 수행하지 마세요. 이는 티켓이 명시적으로 링크한 파일(첨부 파일 참조)을 가져오는 것을 면제하지 않습니다.
  • 트래커에서 티켓을 수정하지 마세요. 가져오기는 읽기 전용(댓글, 상태 변경, 편집, 작업 기록 불가)입니다.
  • 생성하는 유일한 파일: .TICKET.md, 첨부 파일, 가져온 연결된 문서.

다음 단계

완료 시 프로젝트 상대 경로(절대 경로 사용 금지)를 사용하여 명확히 상태를 표시합니다: 출력 디렉토리, 티켓 파일, 첨부 파일. 첨부 파일을 다운로드할 수 없는 경우, 먼저 명확한 경고를 표시하여 누락된 각 attachment-<N>.<ext>와 해당 소스 URL을 나열하고, 사용자에게 해당 정확한 이름으로 다운로드하여 저장하도록 지시하여 임베드가 해결되도록 합니다. 그런 다음 다음 단계를 단일 복사-붙여넣기 가능한 실행 명령어로 전달합니다. 세션 이름과 프롬프트를 결합하여 한 번의 붙여넣기로 세션이 시작됩니다. 사용 중인 에이전트 도구의 실행 구문을 사용하고(공급업체 중립적 — 아래 claude는 예시일 뿐), 세션 이름을 refine-<slug>로 지정합니다:

claude --name refine-<slug> "/refine-ticket <output-dir>/<id>-<slug>.TICKET.md"

그런 다음 대안 — 현재 세션을 지우는 방법을 제시합니다(공급업체 중립적 — 아래 /clear는 예시일 뿐, 사용 중인 에이전트 도구의 지우기 명령어를 사용하세요):

OR /clear 후 실행:

/refine-ticket <output-dir>/<id>-<slug>.TICKET.md

관련 스킬