활성화 계약
Pi 또는 다른 에이전트 런타임용 재사용 가능한 AI 스킬을 생성하거나 업데이트할 때 이 스킬을 사용하십시오.
다음과 같은 경우 스킬을 생성하십시오:
- 워크플로우나 규칙이 여러 세션에 걸쳐 재사용되는 경우;
- 일반적인 에이전트 동작에 프로젝트별 제약 조건이 필요한 경우;
- 의사 결정 트리가 에이전트의 안전한 선택을 돕는 경우;
- 예제, 템플릿, 또는 참조 자료가 향후 실행을 더 안정적으로 만드는 경우.
일회성 작업, 일반 문서, 또는 코드/테스트에 속하는 규칙에 대해서는 스킬을 생성하지 마십시오.
엄격한 규칙
docs/skill-style-guide.md를 스킬 구조와 스타일에 대한 규범적 출처로 따르십시오.- 스킬은 사람을 위한 문서가 아닌 LLM 런타임 계약입니다.
SKILL.md를 간결하게 유지하십시오: 목표 180–450 토큰, 최대 1000.- 명령형 지시와 구체적인 게이트를 사용하고, 튜토리얼이나 배경 설명은 피하십시오.
- 프론트매터
description은 하나의 물리적인 YAML 안전 줄이어야 하며 트리거 단어를 먼저 포함해야 합니다. Keywords섹션을 추가하지 말고, 필수 트리거 단어는description에 넣으십시오.- 템플릿, 스키마, 생성된 예제는
assets/에 넣으십시오. - 더 긴 설명이나 로컬 문서 링크는
references/에 넣으십시오. - 프로젝트 스킬을 변경한 후에는 가능할 때
/skill-registry:refresh로 레지스트리를 새로고침하십시오.
의사 결정 게이트
| 필요 사항 | 조치 |
|---|---|
| 작은 재사용 가능 동작 | skills/{skill-name}/SKILL.md만 생성 |
| 템플릿, 스키마, 픽스처 | skills/{skill-name}/assets/ 추가 |
| 더 긴 설명 또는 에지 케이스 | skills/{skill-name}/references/ 추가 |
| 기존 스킬이 해당 사항을 다룸 | 기존 스킬 업데이트 |
| 스킬이 위임 검색에 영향을 미침 | description에 트리거 단어가 포함되도록 보장 |
실행 단계
- 스킬을 생성하거나 업데이트하기 전에
docs/skill-style-guide.md를 읽으십시오. - 기존 스킬을 검사하고 새 스킬이 중복되지 않는지 확인하십시오.
- 사용자 대상 트리거와 일치하는 케밥-케이스 스킬 이름을 선택하십시오.
- 다음 구조를 생성하거나 업데이트하십시오:
skills/{skill-name}/
├── SKILL.md
├── assets/ # 선택 사항
└── references/ # 선택 사항
- 다음 프론트매터 형태를 사용하십시오:
---
name: {skill-name}
description: "트리거: {사용자 또는 에이전트가 말할 구문}. {이 스킬이 하는 일}."
license: Apache-2.0
metadata:
author: gentleman-programming
version: "1.0"
---
- 섹션을 다음 순서로 작성하십시오: 활성화 계약, 엄격한 규칙, 의사 결정 게이트, 실행 단계, 출력 계약, 참조 자료.
- 이것이 패키지된
gentle-pi스킬인 경우scripts/verify-package-files.mjs에 추가하십시오. - 스킬 레지스트리 업데이트 경로를 새로고침하거나 문서화하십시오.
출력 계약
반환:
- 생성되거나 수정된 파일.
- 새 스킬을 생성했는지 또는 기존 스킬을 업데이트했는지 여부.
- 추가된 지원
assets/또는references/파일. - 패키지 검증 또는 스킬 레지스트리 새로고침이 필요한지 여부.
참조 자료
docs/skill-style-guide.md— 규범적인 LLM 우선 스킬 스타일 가이드.skills/skill-registry/SKILL.md— 레지스트리 새로고침 및 인덱싱 계약.