Writing a Nova Skill

Nova 스킬을 작성/수정할 때 따라야 할 규약. Jesse Vincent(obra/superpowers)의 실측 발견 — "description이 workflow를 요약하면 Claude가 본문 대신 description을 따라간다" — 을 Nova에 흡수한 메타-스킬.

핵심 규약

1. Description = When-to-use only

description은 언제 발동하는가만 기술한다. HOW(동작 방식)은 본문으로.

금지:

• →, 파이프라인, 4단, Explorer×3 같은 단계 열거
• "X로 Y를 Z한다" 형식의 동작 기술 전체
• "엔진", "시스템"만 선언하는 정체성 홍보 (예: "Nova XXX 엔진 —")

요구:

• "...할 때.", "...가 필요한 경우" 같은 트리거 표현
• MUST TRIGGER: ... 섹션에 트리거 조건 3개 이상
• 사용자 요청 패턴 포함 (예: "사용자가 /nova:xxx 호출 시")

예시 (evaluator):

• ❌ "Nova Adversarial Evaluator — Nova Quality Gate의 핵심 검증 엔진. 독립 서브에이전트로 코드를 적대적 관점에서 검증."
• ✅ "코드 구현을 적대적 관점으로 검증해야 할 때. — MUST TRIGGER: /run, /check, /review 내부에서 독립 서브에이전트로 호출, 스프린트 완료 직후, 커밋 전 Evaluator PASS 필요 시."

2. 본문 구조

1. 한 문단 — 스킬 목적 + Nova 5기둥 내 위치
2. ## 핵심 원칙 — 설계 결정 3~5개
3. ## 적용 규칙 (on-demand 로드) — 참조하는 nova-rules §N 번호
4. ## 오케스트레이션 추적 — mcp__plugin_nova_nova__orchestration_update 호출 의무 (해당 시)
5. 예시 / 안티패턴

3. 트리거 회귀 테스트 (MUST)

새 스킬 추가 시 tests/skill-triggering/prompts/{name}-positive.txt 제출 의무.

• positive: 이 스킬이 반드시 발동해야 할 사용자 프롬프트 1개
• negative (선택): 이 스킬이 발동하면 안 되는 유사 맥락 프롬프트

tests/test-skill-triggering.sh가 각 skills/*/SKILL.md에 대응하는 positive fixture 존재를 강제한다. 누락 시 CI FAIL.

실제 LLM 트리거 검증은 Nova 개발자 전용 dev/skills/field-test/로 수동 수행 (사용자 플러그인에는 미포함).

4. 동기화 체크리스트 (CLAUDE.md와 일치)

새 스킬 추가 시:

1. hooks/session-start.sh 커맨드 목록 영향 여부 확인 (커맨드 아니면 대개 불필요)
2. tests/test-scripts.sh의 description lint 통과 확인
3. docs/nova-meta.json — bump-version.sh가 자동 재생성 (수동 편집 금지)
4. tests/skill-triggering/prompts/{name}-positive.txt 제출

안티패턴

• description을 짧게 만들려고 트리거를 생략한다 → Claude가 언제 쓸지 판단 못 함
• "5인 적대 평가자", "3단 파이프라인" 같은 숫자 홍보 → 본문 스킵 유발
• 여러 목적을 한 스킬에 몰아넣는다 → 트리거 모호, 본문 비대

근거 (왜 이 규약이 존재하는가)

• obra/superpowers/skills/writing-skills/SKILL.md — "Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content"
• memory/project_nova_competitive_analysis_2026_04_23.md — 경쟁 분석 결과 9개 Nova SKILL 중 5개가 이 안티패턴에 해당, Tier 1.1에서 일괄 리팩터
• Nova 5기둥 중 협업 기둥 — 스킬이 제 때 발동하지 않으면 에이전트 협업이 붕괴한다