netlify-deploy

netlify-deploy 스킬 개요

netlify-deploy는 Netlify CLI를 사용해 웹 프로젝트를 Netlify에 배포하는 데 초점을 맞춘 배포용 스킬입니다. 로컬 리포지토리에서 미리보기 배포나 프로덕션 배포까지 반복 가능한 경로가 필요한 사용자에게 특히 적합하며, 프로젝트를 먼저 연결(link)하거나 초기화(init)하거나 인증해야 할 수도 있을 때 가장 유용합니다.

netlify-deploy 스킬은 단순히 “배포를 실행한다”가 아니라, “이 리포지토리에 맞는 Netlify 흐름을 찾아낸다”가 핵심일 때 가장 빛납니다. 사이트가 이미 연결되어 있는지 확인하고, preview와 production 중 무엇을 선택할지 정하고, netlify.toml 기반의 빌드 설정을 처리하는 작업까지 포함됩니다.

이 스킬은 무엇을 위한 것인가

netlify-deploy 스킬은 다음이 필요할 때 사용하세요:

• 로컬 웹 앱, 정적 사이트, 프레임워크 앱을 Netlify에 배포
• 새 프로젝트의 첫 배포 생성
• 기존 Git 리포지토리나 로컬 폴더를 기존 Netlify 사이트에 연결
• 프로덕션 배포 전에 미리보기 배포 생성

무엇이 다른가

netlify-deploy의 핵심 가치는 단순한 명령어 목록이 아니라 워크플로 안내에 있습니다. Netlify CLI를 중심에 두고, 먼저 인증 상태를 확인하며, 연결되지 않은 사이트, 누락된 publish 디렉터리, 불완전한 빌드 설정 같은 흔한 막힘까지 고려합니다.

언제 가장 잘 맞는가

이 스킬은 이미 실제 프로젝트 디렉터리가 있고, 신뢰할 수 있는 배포 경로를 찾고 싶은 사용자에게 잘 맞습니다. 특정 리포지토리에 바로 적용할 준비가 되어 있지 않다면, “Netlify를 어떻게 쓰나요?” 같은 추상적인 질문에는 상대적으로 덜 유용합니다.

netlify-deploy 스킬 사용법

먼저 설치하고 스킬을 읽으세요

netlify-deploy install에서는 먼저 스킬 항목 자체를 확인한 뒤, 명령 선택을 좌우하는 보조 문서를 읽으세요:

• SKILL.md
• references/cli-commands.md
• references/deployment-patterns.md
• references/netlify-toml.md

여기에는 별도의 스크립트 계층이 없기 때문에, 중요한 의사결정 지원은 참조 문서에 있습니다. login, link, init, preview deploy, production deploy 중 무엇을 선택해야 할지 헷갈리면 deployment-patterns.md부터 읽는 것이 좋습니다.

모호한 목표를 실행 가능한 프롬프트로 바꾸세요

이 스킬은 사용자가 리포지토리 상태와 배포 대상을 분명히 말할수록 더 잘 작동합니다. 좋은 netlify-deploy usage 프롬프트에는 다음이 포함됩니다:

• 프레임워크 또는 빌드 도구(알고 있다면)
• 사이트가 이미 Netlify에 존재하는지 여부
• 목표가 preview인지 production인지
• 예상 빌드 출력 폴더(알고 있다면)
• netlify.toml의 존재 여부

예시:
“이 Vite 앱을 Netlify에 배포해 주세요. 아직 연결되어 있지 않고, 프로덕션 배포가 목표이며 빌드 출력은 dist입니다.”

약한 입력:
“내 사이트를 배포해 주세요.”

권장 워크플로

실용적인 netlify-deploy guide 흐름은 다음과 같습니다:

1. npx netlify status로 인증 상태를 확인합니다.
2. 필요하면 npx netlify login으로 인증합니다.
3. 기존 사이트를 연결할지, 아니면 npx netlify link 또는 npx netlify init로 새로 만들지 결정합니다.
4. netlify.toml에서 빌드 출력과 설정을 확인합니다.
5. 미리보기 배포는 npx netlify deploy, 프로덕션 배포는 npx netlify deploy --prod를 실행합니다.

설정 파일을 활용해 추측을 줄이세요

배포 전에 netlify.toml이 있다면 먼저 살펴보세요. 가장 중요한 항목은 build.command, build.publish, 그리고 컨텍스트별 환경 설정입니다. publish 경로가 실제 빌드 출력과 맞지 않으면 배포는 성공해도 잘못된 디렉터리를 서빙하거나 검증에서 실패할 수 있습니다.

netlify-deploy 스킬 FAQ

netlify-deploy는 Netlify CLI 사용자만 위한 것인가요?

네. 이 스킬은 npx netlify와 CLI 워크플로를 중심으로 설계되었습니다. 대시보드만으로 배포하고 싶다면, 이 스킬은 적합하지 않을 가능성이 큽니다.

사용하려면 프로젝트가 이미 연결되어 있어야 하나요?

아니요. netlify-deploy skill은 처음 설정과 기존 사이트 모두를 다룹니다. 리포지토리가 아직 연결되지 않았다면 배포 전에 link 또는 init 단계로 흐름이 바뀌어야 합니다.

일반적인 배포 프롬프트보다 나은가요?

대체로 그렇습니다. netlify-deploy는 인증 → link 또는 init → 설정 확인 → 배포라는 Netlify의 실제 순서를 내장하고 있기 때문입니다. 배포를 막는 선행 조건을 건너뛸 위험을 줄여 줍니다.

언제 사용하면 안 되나요?

프로젝트가 웹 앱이 아니거나, CLI 명령을 실행할 수 없거나, Netlify 전용 흐름보다 더 넓은 호스팅 비교가 필요하다면 netlify-deploy를 쓰지 마세요.

netlify-deploy 스킬 개선 방법

배포 경로를 바꾸는 리포지토리 사실을 알려 주세요

품질을 가장 크게 높이는 방법은 스킬이 안전하게 추정할 수 없는 정보를 분명히 주는 것입니다:

• 프레임워크: Next.js, Astro, Vite, SvelteKit 등
• 빌드 명령: npm run build, pnpm build, 또는 커스텀 명령
• publish 디렉터리: dist, build, .next 등
• 사이트 상태: 새 사이트, 연결됨, 이미 배포됨
• 대상: preview 또는 production

이 정보가 있어야 netlify-deploy 스킬이 시행착오 없이 올바른 CLI 경로를 고를 수 있습니다.

설정 불일치는 초기에 드러내세요

흔한 실패 원인은 Netlify가 모든 것을 정확히 감지할 것이라고 가정하는 데 있습니다. 앱이 비표준 출력 디렉터리를 쓰거나, 모노레포 구조를 가지거나, 커스텀 base path를 사용한다면 처음부터 그 사실을 밝히고 스킬이 netlify.toml을 보도록 하세요. 특히 모노레포나 프레임워크 특화 빌드에서의 netlify-deploy for Deployment에는 이 점이 중요합니다.

명령어만이 아니라 첫 배포의 형태를 요청하세요

가장 좋은 결과는 단일 명령이 아니라 순서를 포함한 출력을 요청할 때 나옵니다. 예를 들면:
“이 리포지토리를 인증하고, 연결하고, netlify.toml을 확인한 뒤, 프로덕션으로 배포하는 정확한 절차를 보여 주세요.”

이렇게 요청하면 스킬이 배포 명령 실행 전에 중요한 판단 지점을 설명하게 됩니다.

첫 배포 결과를 바탕으로 반복하세요

첫 배포가 실패하면 처음부터 다시 묻기보다, 실제 실패 내용과 현재 파일 구조를 그대로 전달하세요. 가장 유용한 후속 입력은 다음과 같습니다:

• npx netlify의 오류 메시지
• netlify.toml의 내용
• 프레임워크가 실제로 생성한 빌드 출력 폴더
• 실패 전에 사이트가 연결되어 있었는지 여부

이렇게 하면 다음 netlify-deploy usage 단계가 더 정확해지고, 이미 성공한 인증이나 연결 단계를 다시 반복하는 일을 피할 수 있습니다.