몇 달 전, 나는 npm, React, 백엔드 없이 단일 HTML 파일로 작은 도구들을 만들기 시작했습니다. 브라우저에서 열리고 오프라인에서도 작동하는 단 하나의 파일일 뿐입니다.

나는 이런 방식으로 4개의 실제 제품을 만들었습니다:

DarkenAmber IT Tools - 194KB에 담긴 17개 이상의 개발자 도구
ZeroOffice - PDF, 이미지, AI 도구가 하나의 파일에 포함
PrivacyKit - 업로드가 필요 없는 사진 개인정보 보호 도구
ElectroKit - CIS 시장을 위한 전기 계산기 + 비용 추정

모든 제품이 단 하나의 .html 파일로 이루어져 있습니다. 오프라인에서 작동하며, 즉시 열리고, 서버가 필요 없습니다.

AI 코딩 어시스턴트의 문제점

Claude나 Copilot에게 간단한 것을 만들어 달라고 요청할 때마다, 나는 다음과 같은 결과물을 받았습니다:

src/ 폴더가 포함된 React 프로젝트
12개의 의존성(dependencies)이 포함된 package.json
webpack 설정
TypeScript 설정

...실제 로직을 단 한 줄도 쓰기 전의 모습입니다.

나는 계속해서 수동으로 수정해야 했습니다. "아니, 파일 하나로 해줘. npm 쓰지 마. Vanilla JS로 해줘."

그러다 깨달았습니다. 그냥 한 번 가르쳐 주고 그 지식을 재사용하면 된다는 것을요.

Claude 스킬(Skill)이란 무엇인가?

스킬은 특정 컨텍스트에 대해 Claude가 생각하는 방식을 바꾸는 YAML 프론트매터(frontmatter)가 포함된 Markdown 파일입니다.

이것은 프롬프트(prompt)가 아닙니다. 시스템 메시지(system message)도 아닙니다. Claude가 추론하는 방식, 무엇을 우선시하는지, 무엇을 피해야 하는지를 형성하는 재사용 가능한 규칙 세트입니다.

---
name: single-file-app
description: "Build complete web tools as a single HTML file - vanilla JS, inline CSS, localStorage, offline-first."
tags:
- html
- vanilla-js
- offline
version: 1.2
---

내가 만든 두 가지 스킬

1. single-file-app

Claude에게 하나의 HTML 파일로 완전한 웹 도구를 만드는 법을 가르칩니다.

변경되는 사항:

정말로 정당한 이유가 없는 한 React, npm, 빌드 도구 사용 금지
항상 Vanilla JS 우선 사용
데이터 지속성을 위한 localStorage 사용
시스템 설정을 감지하는 다크/라이트 테마
접근성(Accessibility) 내장 (labels, aria, 키보드 네비게이션)
사용자 입력을 위한 XSS 방지
사용자 데이터를 위한 내보내기/가져오기(Export/import)

방지하는 안티 패턴(Anti-patterns):

❌ "React 프로젝트를 설정해 드릴게요"
❌ 단순한 도구를 위해 src/ 폴더 생성하기

❌ 계산기에 npm install 제안하기
✅ "여기 완성된 HTML 파일이 있습니다"

1. ship-it

초기 단계의 MVP (Minimum Viable Product)를 위해 계획보다는 실행(shipping)에 치중하도록 Claude를 학습시킵니다.

기능:

• 의사결정을 차단하는 대신 트레이드오프 (Trade-offs)를 보여줌
• 핵심 아이디어를 증명하는 범위로 스코프 (Scope)를 축소함
• 적용하지 말아야 할 때를 인지함 (결제, 인증, 라이선스, 되돌릴 수 없는 작업 등)

트레이드오프 테이블 (차단용 테이블이 아님):

사용자의 말	Claude의 답변
"확장 가능하게 만들어야 해요"	"지금 확장성을 확보하려면 X일이 추가로 소요됩니다. 현재 사용자가 거의 없거나 없습니다. 그 시간을 확장성에 쓰시겠습니까, 아니면 첫 사용자 확보에 쓰시겠습니까?"
"배포하기 전에 리팩터링(Refactor)할게요"	"지금 리팩터링할 것인가요 (더 깔끔하지만 피드백이 지연됨), 아니면 배포 후 사용자가 돌아오면 리팩터링할 것인가요 (더 빠른 검증, 더 지저분한 코드). 결정은 당신의 몫입니다."

핵심 통찰: 스킬은 방해꾼이 아니라 조언자가 되어야 합니다.

설치 방법

Claude Code

bash

single-file-app

curl -o CLAUDE.md https://raw.githubusercontent.com/DarkenAmber/claude-skills/main/single-file-app/SKILL.md

두 스킬을 함께 설치

curl https://raw.githubusercontent.com/DarkenAmber/claude-skills/main/single-file-app/SKILL.md > CLAUDE.md
curl https://raw.githubusercontent.com/DarkenAmber/claude-skills/main/ship-it/SKILL.md >> CLAUDE.md

Claude.ai Projects

모든 SKILL.md의 내용을 프로젝트 지침 (Project Instructions)에 복사하세요.

이것들을 만들며 배운 점

1. 스킬은 결정을 내리는 것이 아니라 트레이드오프 (Trade-offs)를 보여줘야 한다

ship-it의 초기 버전에는 "출시 전에 테스트가 필요합니다"라고 말하는 테이블이 있었습니다. → "수동으로 스모크 테스트 (Smoke test)를 수행하고, 검증 후에 테스트 코드를 작성하세요"로 바뀌었습니다. 이전 방식은 스킬이 당신을 대신해 결정을 내리는 것이었습니다. 나쁜 방식입니다.

더 나은 방식: 각 옵션의 비용을 보여주고 개발자가 결정하게 하는 것입니다.

1. 예외 사항이 규칙보다 더 중요하다

ship-it의 가장 가치 있는 부분은 규칙이 아니라, '사용하지 마시오 (Do NOT use when)' 섹션입니다:

결제 및 빌링 (Payments and billing)
인증 및 라이선싱 (Auth and licensing)
되돌릴 수 없는 데이터 작업 (Irreversible data operations)

이 섹션이 없다면, 해당 스킬은 결제 모듈에 대한 테스트를 건너뛰라고 말할 것입니다. 그것은 위험합니다.

1. 하나의 파일은 제약이 아니라, 명확성을 강제하는 제약 조건 (constraint)입니다

컴포넌트로 분리할 수 없을 때, 여러분은 실제로 무엇이 존재해야 하는지에 대해 더 깊이 고민하게 됩니다. 모든 코드 한 줄이 그 자리에 있을 가치를 증명하게 됩니다.

1. 스킬은 반복 (iteration)을 통해 개선됩니다

두 스킬 모두 3회 이상의 리뷰 과정을 거쳤습니다. 각 라운드마다 이전 단계에서 놓쳤던 것들을 잡아냈습니다. 이 프로세스 자체가 ship-it의 철학, 즉 '빨리 출시하고(ship early), 피드백을 통해 반복하라(iterate on feedback)'를 보여주었습니다.

저장소 (The repo)

gitub.com/DarkenAmber/claude-skills

두 개의 스킬, MIT 라이선스, 기여 환영.

이 스킬들로 무언가를 만드신다면, 꼭 보고 싶습니다.

여러분은 AI 코딩 어시스턴트에게 어떤 규칙을 부여하시나요? 여러분이 신뢰하는 CLAUDE.md 또는 .cursorrules 파일이 있나요?