LLM AI Agent

Claude Code - CLAUDE.md와 skills/로 업무 자동화 예제

ybjeon.today 2026. 6. 15. 02:28

목표

  • 같은 프로젝트에서 Markdown끼리 hyperlink가 있을 때, dead link들을 1) 찾고 2) 수정할 수 있는
    • 직접 실행할 수 있는 function 만들기 (skills/)
    • function이 알아서 trigger 되도록 만들기 (CLAUDE.md)
  • CLAUDE.md, SKILL.md 이해하기
  • 참고) command가 skill로 통합됨

배경

  • 본인은 Markdown으로 연구/공부 노트를 관리한다.
  • Markdown 페이지끼리 link를 걸어둘 때가 많은데, 내가 A 페이지에서 만든 링크 destination B 페이지가 있다고 가정하면, destination B 페이지의 주소가 바뀌어도 A 페이지의 destination link가 알아서 업데이트 되지 않아 나중에 못 찾는 불편함이 있다.

Claude Code한테 요청

Skill 생성

1) skills/ 에 스킬 생성 (check-link, fix-link)

 

check-link/SKILL.md

더보기 
---
description: Scan all .md files for internal relative links, classify them as valid or dead, and overwrite links.md with the results.
---

Scan every `.md` file under the project root for internal relative links (links whose target ends in `.md` and does not start with `http`). For each link found:

1. Resolve the target path relative to the source file's directory.
2. Check whether the resolved file actually exists on disk.
3. Classify the link as **valid** or **dead**.

Then overwrite `links.md` at the project root with the following structure:

```
# Link Index

> Generated by `/check-link`. Re-run to refresh.

## Valid Links

| Source | Line | Destination |
|--------|------|-------------|
| [<relative-path>](<relative-path>) | <line> | [<resolved-relative-from-root>](<resolved-relative-from-root>) |
...

## Dead Links

| Source | Line | Destination | Action |
|--------|------|-------------|--------|
| [<relative-path>](<relative-path>) | <line> | `<raw-target>` | <suggested action> |
...
```

Rules:
- **Source** and **Destination** in Valid Links must be clickable markdown links with paths relative to the project root.
- **Source** in Dead Links must be a clickable markdown link; **Destination** must be shown as inline code (not a link, since it does not exist).
- **Line** is the 1-based line number of the link in the source file.
- **Action** for dead links: inspect the project to find the most likely correct target and suggest a concrete fix (e.g., "링크를 `articles/foo.md`로 수정" or "파일 미존재 — 링크 제거 권장"). Write in Korean.
- Skip links whose target is an external URL (starts with `http`).
- Skip links that point to directory paths (no `.md` extension).
- Sort rows within each table by Source path, then by Line number.
- Do not include `links.md` itself as a source.

After writing `links.md`, print a short summary: total links scanned, valid count, dead count.

fix-link/SKILL.md

더보기 
---
description: Apply the fixes suggested in the Dead Links table of links.md, then re-run /check-link to update the index.
---

Read `links.md` and look at the **Dead Links** table. For each row:

1. Read the **Action** column to understand the suggested fix.
2. Open the **Source** file.
3. Apply the fix on the indicated **Line**:
   - If the action says to update the link path, replace the old target with the corrected path.
   - If the action says to remove the link, delete the link (keep the display text as plain text if it makes sense, or remove the whole bullet if it is a bare navigation item).
   - If the action says to create a file, do NOT create it — instead, ask the user whether to create it or remove the link.
4. After all edits, run `/check-link` to regenerate `links.md` and confirm all previously dead links are now valid.

Rules:
- Make the minimal change needed — do not reformat or rewrite surrounding content.
- If two dead links in the same file are on adjacent lines, edit them in one pass.
- If you are uncertain about an action (e.g., ambiguous destination), ask the user before editing.
- After `/check-link` completes, report: how many dead links were fixed, how many remain (if any), and why.

 

 

2) CLAUDE.md에 관련 내용 업데이트 (트리거 추가)

## Link Management
`links.md` at the project root is the authoritative index of all internal `.md` links. Keep it in sync whenever links change.

- **Skip if no links changed**: if a file edit adds or removes no internal `.md` links, skip the Link Management process entirely.
- **Adding a link**: after inserting it, add a corresponding row to the `## Valid Links` table in `links.md`.
- **Removing a link**: remove its row from `links.md`.
- **Renaming or moving a file**: update every row in `links.md` that references the old path (both Source and Destination columns), and fix all source files that link to it.
- **Backwards tracking**: before adding a link to a file, check `links.md` to see if anything already links to that file — keep the graph consistent.
- Run `/check-link` to regenerate `links.md` from scratch and catch any drift.
- Run `/fix-link` to apply the Action suggestions from the Dead Links table and then re-verify.

 

* 내가 파일 수정을 Claude Code에 요청하고 난 다음에 생성된 파일에 link가 추가되지 않으면 굳이 Link Management 프로세스가 필요 없기 때문에 굳이 token을 더 쓰지 않게 아래 문구도 추가하였다.

- **Skip if no links changed**: if a file edit adds or removes no internal `.md` links, skip the Link Management process entirely.

 

시행 착오

 

방법 1: .claude/commands/에 파일 생성 (슬래시 자동완성으로 쓸 수 있게)
.claude/commands/fix-link.md와 .claude/commands/check-link.md를 만들어서 SKILL.md 내용을 그대로 복사

방법 2: 채팅 메시지로 입력

방법 1을 하면 과정은 귀찮지만 자동완성이 되는 장점

방법 2를 하면 과정 없이 그냥 요청하면 되지만 단순 /fix-link를 사용을 못함 (command 상에서 막아 놓음). /fix-link 치고 space bar 몇 번 쳐야한다. (자동 완성을 닫기 위해)

 

처음 프롬프트부터 command에도 등록을 해달라고 하는게 괜찮았을 것 같다. #todo

결과 

1) /check-link 실행 시 > links.md 생성됨

 

 

2) /fix-link 실행 시 > dead link들을 내가 변경한 Action 대로 처리

 

dead link 다 사라짐

 

3) 글 입력하면 자동으로 링크가 업데이트

 

 

조금만 고생하면 계속 편하게 쓸 수 있다.