실행 가능한 확장까지 갈 필요 없이 지침이나 문구만 추가하고 싶을 때 쓰는 수단이 스킬과 프롬프트 템플릿입니다. 둘 다 파일 하나로 시작할 수 있어 가장 가벼운 커스터마이징입니다.

스킬: 필요할 때만 로드되는 작업 지침

스킬은 특정 종류의 작업을 위한 전문 지침과 보조 파일을 묶은 것입니다. Pi는 각 스킬의 이름과 설명만 시스템 프롬프트에 올려 광고하고, 전체 지침은 작업이 요구할 때만 로드합니다. Pi는 Agent Skills 사양을 구현합니다.

만들기

스킬은 SKILL.md를 담은 디렉터리입니다.

pdf-tools/
├── SKILL.md
├── scripts/
│   └── extract.sh
├── references/
│   └── formats.md
└── assets/
    └── template.json

---
name: pdf-tools
description: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.
---

# PDF tools

Read `references/formats.md` before converting a document. Run scripts relative to this skill directory.

description이 라우팅의 전부입니다. 스킬이 무엇을 하는지와 언제 쓰는지 둘 다 적어야 모델이 제대로 불러옵니다. "PDF를 돕습니다" 같은 설명은 정보가 부족합니다. 동봉 파일을 참조할 때는 스킬 디렉터리 기준 상대경로를 사용합니다. Pi가 모델에게 스킬 위치를 알려 주기 때문에 그 경로로 해석할 수 있습니다.

로드 방식과 강제 호출

시작 시 Pi는 설정된 스킬 위치를 훑어 이름·설명·경로를 시스템 프롬프트에 추가합니다. 작업이 일치하면 모델이 SKILL.md를 읽고 지침을 따릅니다. 모델이 관련 스킬을 놓칠 수 있으므로 필요하면 /skill:name으로 강제할 수 있습니다. 인자를 붙이면 로드된 지침 뒤에 사용자 요청으로 추가됩니다.

/skill:pdf-tools extract report.pdf

frontmatter에 disable-model-invocation: true를 두면 명시적 명령으로만 열리는 스킬이 됩니다. enableSkillCommands 설정은 대화형 명령 탐색 노출을 조절합니다.

위치와 frontmatter

SKILL.md를 포함한 디렉터리를 재귀적으로 탐색합니다. 사용자·프로젝트 스킬 디렉터리(~/.pi/agent/skills/, .pi/skills/) 외에 Agent Skills 표준 위치인 ~/.agents/skills/, .agents/skills/도 지원합니다.

필드	용도
name	명령·표시 이름 (소문자·숫자·하이픈, 최대 64자)
description	모델에게 보이는 라우팅 설명 (최대 1024자)
license	라이선스 이름 또는 동봉 파일
compatibility	환경 요구 사항
metadata	추가 키값 메타데이터
allowed-tools	실험적 사전 승인 도구 목록
disable-model-invocation	자동 선택에서 숨김

잘못된 SKILL.md나 설명이 없는 스킬은 로드되지 않습니다. 이름 충돌 시 처음 발견된 것이 남고 경고가 납니다. 프로젝트 스킬은 모델에게 스크립트 실행이나 파일 수정을 지시할 수 있으므로, 신뢰를 주기 전에 낯선 스킬과 동봉 파일을 검토하세요. 예제는 Anthropic skills 컬렉션과 Pi skills 컬렉션 저장소를 참고할 수 있습니다.

프롬프트 템플릿: / 명령이 되는 재사용 프롬프트

같은 프롬프트를 반복하는데 실행 동작이나 무거운 지침이 필요 없다면 템플릿입니다. ~/.pi/agent/prompts/review.md처럼 만듭니다.

---
description: Review staged git changes
argument-hint: "[focus]"
---
Review the staged changes. Focus on ${1:-correctness, security, and error handling}.

파일명이 명령 이름이 되어 /review로 쓰습니다. description은 명령 자동완성에 표시되고, 생략하면 첫 비어 있지 않은 줄이 쓰입니다. argument-hint는 선택이며 필수 인자는 <꺾쇠 bracket>, 선택 인자는 [대괄호]로 표기합니다. 활성 세션에서 추가·수정했다면 /reload를 실행합니다.

인자 치환

/review
/review concurrency

문법	결과
$1, $2, …	위치 인자 하나
$@ 또는 $ARGUMENTS	모든 인자를 공백으로 연결
${1:-기본값}	첫 인자, 없으면 기본값
${@:-기본값}	모든 인자, 없으면 기본값
${@:N}	N번째부터의 인자
${@:N:L}	N번째부터 L개 인자

인자는 셸식 인용을 따릅니다. /review "API compatibility"는 공백을 포함한 인자 하나를 주고, 단어 속 아포스트로피(doesn't)는 텍스트로 남습니다. 템플릿은 사용자 입력이 에이전트로 들어가기 전에 확장되며, 확장 input 이벤트는 원본 입력을 먼저 받습니다.

템플릿도 사용자·프로젝트 프롬프트 디렉터리에 두거나 설정과 Pi 패키지로 로드할 수 있습니다. 프로젝트 템플릿은 신뢰 허용 후 명령이 되므로 낯선 프로젝트의 것은 검토가 필요합니다.