게시된 스킬(Published skills)
Backstage는 정제된 AI 스킬 세트를 게시합니다 — AI 코딩 어시스턴트에게 일반적인 Backstage 엔지니어링 작업을 수행하는 방법을 가르치는 자체 포함된 안내 파일입니다. 스킬은 backstage.io의 well-known 엔드포인트에 게시되며, skills.sh 도구로 저장소에 설치할 수 있습니다.
출처: 문서
본문
Backstage는 정제된 AI 스킬 세트를 게시합니다 — AI 코딩 어시스턴트에게 일반적인 Backstage 엔지니어링 작업을 수행하는 방법을 가르치는 자체 포함된 안내 파일입니다. 스킬은 backstage.io의 well-known 엔드포인트에 게시되며, skills.sh 도구로 저장소에 설치할 수 있습니다.
스킬 설치하기
npx를 실행하려면 Node.js가 필요합니다.
npx skills add https://backstage.io
이 명령은 https://backstage.io/.well-known/skills/index.json에서 게시된 인덱스를 읽고, 사용 가능한 스킬 중 저장소에 설치할 것을 선택할 수 있게 해줍니다.
스킬이 설치되는 위치
skills.sh는 스킬 파일을 관리하는 디렉토리(일반적으로 .github/skills/ 또는 구성에 따라 비슷한 위치) 아래의 저장소에 복사합니다. 대상 경로와 사용자 지정 방법에 대한 자세한 내용은 skills.sh 문서를 참조하세요.
설치 후에는 설치된 파일을 프로젝트의 규칙에 맞게 수정할 수 있습니다. 이후 npx skills add 업데이트는 업스트림 변경 사항을 병합할 것을 제안합니다.
AI 어시스턴트와 함께 스킬 사용하기
스킬이 저장소에 설치되면, AI 코딩 어시스턴트로 작업을 시작할 때 관련 SKILL.md 파일을 첨부하거나 참조하세요. VS Code 같은 편집기의 대부분의 AI 어시스턴트는 저장소에 커밋된 지시 파일을 자동으로 인식합니다.
예를 들어 Material-UI에서 Backstage UI로 플러그인을 마이그레이션할 때 mui-to-bui-migration 스킬을 포함하세요. 공식 codemod 레시피를 실행하고 남은 부분을 마무리할지, 아니면 독립형 안내로 직접 마이그레이션할지 선택하세요. 스킬은 기계적인 변경에는 codemod를 권장하지만, 두 경로 모두 지원합니다. 요청에서 선호 사항을 명시하세요. 그렇지 않으면 어시스턴트가 시작 전에 물어봅니다. 예: "codemod를 실행하지 말고 독립형 안내로 이 플러그인을 Backstage UI로 마이그레이션해 줘."
새 스킬 기여하기
스킬은 Backstage 모노레포의 docs/.well-known/skills/에 작성됩니다. 각 스킬은 자체 하위 디렉토리에 있으며, 기본 진입점으로 SKILL.md 파일을 포함해야 합니다.
스킬 디렉토리 레이아웃
docs/.well-known/skills/ index.json # Published index of all skills <skill-name>/ SKILL.md # Primary skill entry point (required) <optional-supporting-files>
SKILL.md 작성하기
SKILL.md 파일은 다음 필드를 가진 YAML front matter 블록을 포함해야 합니다.
---name: <skill-name>description: <short description used in the published index>---# Skill TitleIntroductory paragraph explaining when and why to use this skill....
name은 디렉토리 이름과 일치해야 합니다. description은 사용자가 스킬을 탐색하거나 설치할 때 표시되며, 스킬이 다루는 작업을 설명하는 한두 문장이어야 합니다.
스킬을 단일하고 명확하게 정의된 작업에 집중하게 유지하세요. 너무 많은 시나리오를 다루려는 스킬은 효과적으로 사용하기 어렵습니다. 구체적이고 단계별 안내, 작동하는 코드 예시, 일반적인 함정에 대한 명시적 메모를 선호하세요.
인덱스에 스킬 등록하기
docs/.well-known/skills/index.json에 항목을 추가하세요.
{ "skills": [ { "name": "<skill-name>", "description": "<same description as in SKILL.md front matter>", "files": ["SKILL.md"] } ]}
스킬에 추가 지원 파일이 포함되어 있다면 각각을 files 배열에 나열하세요.
검토 프로세스
스킬에 대한 모든 변경은 표준 Backstage 풀 리퀘스트 프로세스를 거칩니다. 스킬을 작성하거나 검토할 때 다음을 고려하세요.
-
정확성(Accuracy) — 스킬이 현재 Backstage API와 규칙을 반영하나요?
-
완전성(Completeness) — 개발자가 마주칠 가장 일반적인 경우를 다루나요?
-
안전성(Safety) — 보안이나 정확성 문제를 도입할 수 있는 패턴을 피하나요?
-
범위(Scope) — 스킬이 단일 작업에 집중되어 있나요, 아니면 분할해야 하나요?
스킬은 게시된 Backstage 문서 표면의 일부이므로, 나머지 문서와 동일한 기여 지침을 따릅니다. 전체 기여 프로세스는 CONTRIBUTING.md를 참조하세요.