# Obsidian Writer

> Obsidian vault 문서를 새로 만들거나 서식을 맞출 때 사용하는 문서 "작성" 규칙. "옵시디언", "obsidian", "새 문서", "새문서", "vault 문서", "노트 작성", "문서 작성", "목차 추가", "inbox 문서", "기술 문서 작성" 등으로 트리거. 파일명 규칙, 필수 목차(TOC, [[#헤딩]]), Inbox 저장, 코드 요소 색상(span 클래스/CSS 스니펫), 기술 문서 7섹션 구조를 정의한다. 오로지 문서 작성/서식에만 적용되는 스킬.

- Skill: `riverful/obsidian-writer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add riverful/obsidian-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/riverful/obsidian-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: riverful (https://skillmd.com/u/riverful)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/riverful/obsidian-writer

---


# obsidian-writer — Obsidian 문서 작성/서식 규칙

Obsidian vault에서 **새 문서를 만들거나 기존 문서 서식을 정리**할 때 이 규칙을 적용한다. 이 스킬은 **오로지 "쓰기(작성/서식)"** 에만 관한 것이다.

> 저장 폴더(Inbox·프로젝트 폴더 등)의 실제 경로는 프로젝트 `CLAUDE.md`의 "문서 작성 설정"에 정의된 값을 따른다. 정의가 없으면 vault 루트 등 적절한 위치에 작성한다.

## 0. 필수 체크 (문서 생성 시 항상)

- **저장 위치**: 새 파일은 항상 지정된 Inbox 폴더에 먼저 저장 (실제 경로는 `CLAUDE.md`의 "문서 작성 설정" 참조).
- **목차(TOC) 필수**: 문서 상단에 목차를 넣는다. Obsidian 내부 링크 `[[#헤딩]]` 형식 사용.
  - 하위 항목은 들여쓰기(탭)로 표현. 표시 텍스트가 필요하면 `[[#헤딩|표시텍스트]]`.
  - 예:
    ```markdown
    ## 목차
    1. [[#1. 설치]]
    2. [[#2. 사용법|사용법]]
        - [[#2-1. 세부 항목]]
    ```

## 1. 파일명 규칙

| 유형 | 형식 | 예시 |
|---|---|---|
| 일반 문서 | `YYYY-MM-DD 제목.md` | `2026-02-19 회의록.md` |
| 크롤링 문서 | `C-YYYY-MM-DD 제목.md` | `C-2026-02-19 기사제목.md` |
| 유튜브 요약 | `Y-YYYY-MM-DD 제목.md` | `Y-2026-02-19 영상제목.md` |

## 2. 코드 요소 색상 규칙 (span 클래스)

CSS 스니펫 `inline-code-color`(`.obsidian/snippets/`)가 아래 클래스를 정의한다. 문서에서 코드 요소를 강조할 때 이 규칙을 따른다.

- **기본은 인라인 코드(백틱)** — 파일명·함수명·변수명·명령어·경로·설정키는 백틱(`` ` ``)으로 감싼다. 스니펫이 파랑 단색을 자동 적용한다.
- **종류별 색 구분이 필요할 때만 span 클래스** 사용. 남발하지 말 것(핵심 심볼 위주).

| 클래스 | 용도 | 색 | 예시 |
|---|---|---|---|
| `fn` | 함수/메서드 | 노랑 | `<span class="fn">calculateTotal()</span>` |
| `var` | 변수/멤버 | 하늘 | `<span class="var">retryCount</span>` |
| `file` | 파일명 | 청록 | `<span class="file">main.cpp</span>` |
| `type` | 타입/클래스 | 분홍보라 | `<span class="type">HttpClient</span>` |
| `cmd` | 명령어 | 주황 | `<span class="cmd">npm run build</span>` |

- **코드블록은 언어 태그를 붙인다**: ` ```cpp `, ` ```bash `, ` ```python ` 등. PrismJS가 토큰별(함수/타입/문자열/주석)로 자동 색칠한다.
- 색 정의를 바꾸려면 `.obsidian/snippets/inline-code-color.css`의 색코드만 수정(전 문서 반영).

### 2-1. CSS 스니펫 자동 설정 (문서 작업 시작 시 체크)

span 클래스나 코드 색상을 쓰기 전에 **CSS 스니펫이 준비돼 있는지 항상 확인**하고, 없으면 자동으로 생성·활성화한다.

1. `.obsidian/snippets/inline-code-color.css` 존재 확인.
   - **파일이 없거나 비어 있으면** 아래 전체 내용으로 생성한다.
2. `.obsidian/appearance.json`의 `enabledCssSnippets` 배열 확인.
   - **`"inline-code-color"`가 없으면** 배열에 추가한다. (`appearance.json`이 없으면 `{"enabledCssSnippets":["inline-code-color"]}`로 생성)

생성할 CSS 전체 내용:

````css
/* ============================================================
   코드 색상 스니펫
   - 인라인 코드(`...`): 의미 구분 불가 → 단색(파랑)
   - 코드블록(```cpp 등): PrismJS 토큰별 색상 분리
     (함수/타입/변수/문자열/주석/숫자를 각각 다른 색으로)
   ============================================================ */

/* ---------- 1. 인라인 코드 (문장 속 `...`) : 단색 파랑 ---------- */
.markdown-preview-view code:not(pre code),
.markdown-rendered code:not(pre code) {
  color: #61afef;
  background-color: rgba(97, 175, 239, 0.12);
  border: 1px solid rgba(97, 175, 239, 0.25);
  border-radius: 4px;
  padding: 0.1em 0.35em;
  font-size: 0.9em;
}
.cm-s-obsidian .cm-inline-code {
  color: #61afef;
  background-color: rgba(97, 175, 239, 0.12);
  border-radius: 4px;
  padding: 0.1em 0.2em;
}

/* ---------- 2. 코드블록(```cpp 등) PrismJS 토큰별 색상 ---------- */
.token.function            { color: #dcdcaa !important; } /* 함수 — 노랑 */
.token.class-name,
.token.builtin             { color: #4ec9b0 !important; } /* 타입/클래스 — 청록 */
.token.keyword             { color: #c586c0 !important; } /* 키워드 — 분홍보라 */
.token.string,
.token.char                { color: #ce9178 !important; } /* 문자열 — 주황 */
.token.comment             { color: #6a9955 !important; font-style: italic; } /* 주석 — 초록 */
.token.number              { color: #b5cea8 !important; } /* 숫자/라인번호 — 연두 */
.token.macro,
.token.directive           { color: #9b9b9b !important; } /* 전처리기 — 회보라 */
.token.property,
.token.variable            { color: #9cdcfe !important; } /* 변수/식별자 — 하늘 */
.token.operator,
.token.punctuation         { color: #d4d4d4 !important; } /* 연산자·구두점 — 회색 */

/* ---------- 3. 수동 색상 클래스 (문장 속 임의 문자열) ---------- */
.fn, .var, .file, .type, .cmd {
  font-family: var(--font-monospace);
  font-size: 0.92em;
}
.fn   { color: #dcdcaa; }   /* 함수 — 노랑 */
.var  { color: #9cdcfe; }   /* 변수 — 하늘 */
.file { color: #4ec9b0; }   /* 파일 — 청록 */
.type { color: #c586c0; }   /* 타입/클래스 — 분홍보라 */
.cmd  { color: #ce9178; }   /* 명령어 — 주황 */
````

## 3. 기술 문서 작성 규칙 (프로젝트 레퍼런스 문서)

프로젝트 개발 시 **plan 문서**(진행 관리, `{프로젝트명}-plan.md`)와 별도로, 프로젝트 자체를 설명하는 **기술 문서**(`{프로젝트명}.md`)를 작성한다. 처음 보는 사람이 전체를 이해할 수 있는 레퍼런스.

### 구조 (7개 대주제)

| # | 섹션 | 내용 |
|---|------|------|
| 1 | **개요** | 프로젝트 설명, 기본 정보(소스 경로/언어/프레임워크), 배경/동기 |
| 2 | **사용법** | CLI, TUI/GUI 조작(단축키/레이아웃), Bot 커맨드, API 커버리지 |
| 3 | **아키텍처** | 모듈 구조, 데이터 흐름, 인프라(네트워크/포트/파일 위치), 인증 구조, 설계 결정 |
| 4 | **구현 방법** | 핵심 알고리즘, 데이터 수집/처리 로직, 스키마, 계산 공식 등 상세 |
| 5 | **변경 이력** | git log 기반 날짜별 변경 내역 테이블(개발 중 지속 추가) |
| 6 | **트러블슈팅** | 증상 → 원인 → 해결 형식(디버깅에서 발견한 이슈 지속 추가) |
| 7 | **부록** | 의존성, 보안, 제한사항, 설정값, 관련 자료, Git/백업 등 |

### 작성 원칙

- **목차**: 문서 상단에 `[[#섹션명]]` 형식으로 작성.
- **plan 문서와 구분**: plan은 TODO/진행 관리, 기술 문서는 완성된 프로젝트 설명.
- **변경 이력**: 코드 수정 시 변경 이력 테이블에 날짜 + 내용 추가.
- **트러블슈팅**: 버그 수정 시 증상/원인/해결 형식으로 추가.
- **점진적 보강**: 프로젝트 발전 시 해당 섹션 업데이트.
- **파일 위치/이름**: `{프로젝트 폴더}/{프로젝트명}/{프로젝트명}.md` (폴더명과 동일). 프로젝트 폴더 경로는 `CLAUDE.md`의 "문서 작성 설정" 참조.

---

> 이 스킬은 "문서 작성/서식"만 다룬다. 첨부파일 저장 위치, 웹 크롤링 문서 정리 등
> vault 환경에 종속되는 규칙은 각자 환경에 맞게 별도로 정의해서 쓸 것.