ActivityPub 서버에서 YouTube 추적 링크 방지하기

ActivityPub 서버에 공유되는 YouTube 링크는 종종 사용자들 사이에서 개인정보 보호 측면의 우려 사항으로 언급됩니다. 이는 공유된 URL에 포함된 si 파라미터나, YouTube 웹사이트 자체에 내장된 다양한 추적 기술 등 방문자를 추적하는 데 사용될 수 있는 여러 기술적 메커니즘 때문입니다.

현실적으로 볼 때, ActivityPub 프로토콜을 구현하는 프로젝트들이 이 문제에 대해 기본 제공 해결책을 제시할 가능성은 낮습니다. 이는 YouTube라는 특정 서비스에 국한된 문제가 아니라, 보다 광범위한 웹 추적 문제에 해당하기 때문입니다.

그럼에도 불구하고, 서버 관리자는 서버 차원에서 이러한 우려를 완화하기 위한 실질적인 조치를 취할 수 있습니다.

1. 대체 YouTube 프론트엔드 사용

YouTube로 직접 연결하는 대신, 개인정보 보호에 더 우호적인 대체 프론트엔드 사용을 권장할 수 있습니다.

• DNT-YT (권장 — 이 시나리오를 위해 특별히 설계됨)
• Piped
• Invidious

이러한 프론트엔드들은 영상 접근성을 유지하면서도 추적을 줄이거나 제거하는 데 도움을 줍니다.

2. Nginx sub_filter를 사용한 링크 재작성

대체 프론트엔드를 설정한 이후에는, Nginx의 sub_filter 기능을 사용하여 YouTube 링크를 투명하게 재작성할 수 있습니다. 이를 통해 사용자가 원본 YouTube URL에 직접 접근하는 것을 방지하고, 대신 대체 프론트엔드를 통해 영상을 보도록 유도할 수 있습니다.

예시 설정은 다음과 같습니다.

sub_filter 'www.youtube.com/' 'dnt-yt.catswords.net/';
sub_filter 'youtube.com/' 'dnt-yt.catswords.net/';
sub_filter 'www.youtu.be/' 'dnt-yt.catswords.net/';
sub_filter 'youtu.be/' 'dnt-yt.catswords.net/';

결과

youtube.com 또는 youtu.be로 연결되는 링크가 일관되게 대체 프론트엔드 주소로 변경되는 것이 확인되면, 설정은 완료된 것입니다.

이 접근 방식을 실제로 적용한 사례는 아래 링크에서 확인할 수 있습니다.

https://catswords.social/@gnh1201/115801692643125819

Terraform & Kubernetes 도입 후기

최근 인프라 구성과 서비스 운영 전반에서 (늦었지만…) Terraform과 Kubernetes를 본격적으로 사용해 보았고, 생각보다 경험이 꽤 좋아서 기록 겸 공유해 둔다.

TL;DR

이걸 왜 이제 썼지. 진작 써볼 걸. (feat. 관리할 서버가 많아질수록 체감이 큼)

기존에 사용하던 방식

1. 웹 브라우저 → AWS 콘솔에서 마우스 클릭으로 인프라 구성 (EC2 생성, 네트워크 설정 등)
2. 로컬 서버에 Docker / Docker Compose 기반 운영

이번에 사용한 방식

Terraform (IaC)

• VPC, Subnet, NAT, Kubernetes Cluster 까지 인프라를 코드로 선언
• 변경 이력이 Git에 남아 변경 추적과 리뷰가 가능
• 코드로 명확히 남기니 재사용성과 일관성이 크게 좋아짐
• 콘솔 수작업이 줄어들어 휴먼 에러 감소
• '이 인프라가 왜 이렇게 생겼는지'가 코드로 설명됨

내 경우는 NCP(Naver Cloud Platform) 를 사용했는데, 지원하는 리소스 범위가 제한적이라 일부는 여전히 웹 콘솔에서 수작업이 필요했다.

그럼에도 불구하고, Terraform을 도입한 만족도는 꽤 높았다.

Kubernetes

• 배포, 롤링 업데이트(무중단), 오토스케일링이 정책 기반으로 자동 동작
• 모든 설정을 yaml파일로 관리할 수 있는 점이 매우 편리
• 서비스 디스커버리, 헬스 체크, 셀프 힐링 덕분에 운영 부담이 체감될 정도로 감소
• Pod / Node / Resource 단위로 문제를 분리해서 볼 수 있어 장애 원인 추적이 수월
• 서비스 규모가 커질수록 정리된 상태를 유지하기 쉬운 구조
• GitLab CI + Container Registry + ArgoCD 조합의 배포 자동화 경험이 매우 만족스러웠음

그리고, AI의 도움

이번에 느낀 또 하나의 큰 포인트는 AI의 존재감이었다.

• Terraform module 구조 설계, variable 정리
• Kubernetes manifest 작성 및 리팩토링 (Deployment, HPA, Ingress 등)
• 에러 메시지 / 이벤트 로그 해석
• 필요한 CLI 명령어를 바로 바로 알려줌
• “이 구성, 더 나은 패턴이 있는가?” 같은 설계 피드백
• 문서를 처음부터 끝까지 파는 방식보다, AI와 대화하면서 검증하고 다듬는 흐름이 훨씬 효율적이었다.

결과적으로,

• 러닝 커브는 여전히 존재하지만 AI를 보조 도구로 사용하면서 학습 속도와 시행착오 비용이 크게 줄어든 느낌

요약하자면,

• 수많은(?) 장애와 벽에 부딪히는 순간에도 언제든 도움을 받을 수 있다는 점에서 덜 두려웠다.

부록) K8S, 다음에도 바로 쓸 것인가?

• 서비스 초기부터 바로 도입할 것 같지는 않다 (K8S Cluster만 해도 NCP 기준 월 약 7만 원)
• 초기에는 인스턴스 1~2대 + 오토스케일링 정도로 충분할 듯 (아예 오토스케일링이 필요 없는 경우도 많다)
• 사용하는 인스턴스 수가 늘고, 서비스 규모가 커지면 그때 도입을 고민
• 사용 경험은 긍정적이지만 작은 서비스에는 확실히 오버스펙
• 서버에 바로 SSH 접근해서 띄우고 로그보고 재기동 시키고 하는 게 더 편안한 1인이라, 그런 거 못할 때 가끔 불편하게 느껴지기는 했음 (물론 셸 접근은 가능하나, 그러기에는 Pod이 너무 많..)

정리하면

• Terraform: 서비스 초기부터 도입하고 싶다
• Kubernetes: 상황에 따라 선택, 작은 서비스라면 초반 도입은 X

Agent Skill은 Anthropic이 2025년 10월에 발표한 기능이다. 발표 직후부터 폭발적인 반응을 얻어 커뮤니티에서 다양한 종류의 Skill이 만들어졌다. 2025년 12월 18일에 Anthropic은 Agent Skills를 독립적인 오픈 스탠다드로 발표했고 여러 서비스들이 Skill을 지원하고 있다.

이번 글에서는 Agent Skill이 Tool Use 위에서 어떻게 동작하는지 알아본다.

Agent Skill이란?

Agent Skill은 에이전트가 특정 작업을 더 정확하고 효율적으로 수행할 수 있도록 지시문(instructions), 스크립트(scripts), 리소스(resources) 등을 동적으로 불러올 수 있게 구성된 폴더다.

에이전트는 점점 더 많은 것을 할 수 있지만 실제 업무를 안정적으로 수행하려면 절차적 지식과 조직별 맥락이 필요하다. PDF 양식을 채우는 방법, 데이터베이스 마이그레이션을 안전하게 수행하는 순서, 브라우저 자동화의 베스트 프랙티스 같은 것들이다. 이런 지식을 매번 프롬프트에 모두 작성하면 컨텍스트를 낭비하게 되고 일관성도 떨어진다.

Agent Skill은 이러한 문제들을 해결하기 위해 작업에 필요한 지식을 재사용 가능한 단위로 패키징하고 필요할 때만 동적으로 로드한다.

효율적인 컨텍스트 관리 방법

Agent Skill은 점진적 공개(Progressive Disclosure) 패턴으로 컨텍스트를 효율적으로 관리한다. 점진적 공개는 다음과 같은 단계로 구성된다.

첫 번째 단계: 메타데이터 로드

에이전트가 시작할 때 모든 Skill의 name과 description만 로드한다. 이 메타데이터는 Claude가 각 Skill을 언제 사용해야 하는지 판단할 수 있을 만큼의 정보만 제공한다. 예를 들어 PDF Skill은 "PDF 파일에서 텍스트 추출, 폼 채우기, 문서 병합을 수행한다"는 설명만 시스템 프롬프트에 포함된다.

두 번째 단계: SKILL.md 전체 로드

Claude가 현재 작업에 해당 Skill이 관련 있다고 판단하면 전체 SKILL.md를 컨텍스트에 로드한다. 이 단계에서 상세한 지시문이 추가된다. 권장 크기는 5000 토큰 미만이다.

세 번째 단계 이상: 추가 파일 온디맨드 로드

Skill이 복잡해지면 모든 내용을 SKILL.md 하나에 담기 어려워진다. 이런 경우 references/, scripts/, assets/ 폴더에 추가 파일을 번들하고 SKILL.md에서 참조한다. Claude는 필요할 때만 이 파일들을 탐색하고 로드한다.

이 패턴의 장점은 "필요할 때만 필요한 만큼"이다. 모든 Skill의 전체 지시문을 처음부터 로드하면 컨텍스트가 금방 소진된다. 점진적 공개는 이 문제를 해결하면서도 에이전트가 적절한 시점에 적절한 Skill을 활성화할 수 있게 한다.

Agent Skill의 구조

일반적인 Skill의 구조는 다음과 같다.

skill-name/
├── SKILL.md           # 필수: 메타데이터 + 지시문
├── scripts/           # 선택: 실행 가능한 코드
├── references/        # 선택: 추가 문서
└── assets/            # 선택: 템플릿, 리소스

SKILL.md만 필수이고 나머지는 모두 선택이다. 단순한 Skill은 SKILL.md 하나만으로 구성될 수 있고 복잡한 Skill은 여러 개의 스크립트와 참조 문서를 포함할 수 있다.

필수요소인 SKILL.md는 다음과 같은 포맷으로 구성된다.

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
compatibility: Designed for Claude Code
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Read
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

SKILL.md는 YAML frontmatter와 마크다운 본문으로 구성된다. YAML frontmatter에는 name과 description이 필수로 포함되어야 한다. name은 최대 64자의 소문자와 숫자 그리고 하이픈으로만 구성되며 하이픈으로 시작하거나 끝날 수 없다. description은 최대 1024자로 이 Skill이 무엇을 하는지 언제 사용해야 하는지 설명한다.

license, compatibility, metadata, allowed-tools는 선택 필드다. 각 선택 필드의 역할은 다음과 같다.

• license: 라이선스 이름 또는 번들된 라이선스 파일에 대한 참조를 명시한다.
• compatibility: 최대 500자. 환경 요구사항을 명시한다. 의도한 제품, 필요한 시스템 패키지, 네트워크 접근 필요 여부 등을 기술한다. 예를 들어 "Designed for Claude Code" 또는 "Requires git, docker, jq, and access to the internet" 같은 형태로 작성한다. 대부분의 Skill은 이 필드가 필요하지 않다.
• metadata: 임의의 키-값 쌍을 저장하는 맵이다. author, version 같은 추가 속성을 담는다.
• allowed-tools: 공백으로 구분된 사전 승인 도구 목록이다. 실험적 기능으로 에이전트 구현에 따라 지원 여부가 다를 수 있다.

YAML frontmatter 아래의 마크다운 본문이 실제 지시문이 된다. 이 지시문은 Skill이 활성화될 때 컨텍스트에 주입되어 에이전트의 행동을 안내한다.

첫번째 단계에서는 frontmatter의 name과 description만 사용된다. 이 정보로 에이전트는 언제 이 Skill을 활성화해야 하는지 판단한다. 두번째 단계에서 SKILL.md 전체가 로드되고 세번째 단계에서 마크다운 본문의 지시문에 따라 scripts/ 폴더의 코드를 실행하거나 references/ 폴더의 추가 문서를 참조한다.

dev-browser로 살펴보는 실제 Skill 동작

이제 Skill이 어떻게 동작하는지 실제 예시를 통해 살펴보자. 이 예시는 Use Claude Code with Chrome에 있는 사용 예시를 dev-browser Skill을 사용해 테스트하고 분석한 것이다.

사용한 프롬프트는 다음과 같다.

Go to code.claude.com/docs, click on the search box,
type "hooks", and tell me what results appear

이 요청은 tools 배열과 함께 전송되며 Skill도 tools 배열에 포함되어 있다. Claude API 요청 구조에 대해서는 이전 글을 참고한다.

{
  "name": "Skill",
  "description": "Execute a skill within the main conversation\n\n<skills_instructions>...",
  "input_schema": {
    "type": "object",
    "properties": {
      "skill": {
        "type": "string",
        "description": "The skill name. E.g., \"commit\", \"review-pr\", or \"pdf\""
      },
      "args": {
        "type": "string",
        "description": "Optional arguments for the skill"
      }
    },
    "required": ["skill"]
  }
}

Skill 도구의 description에는 <available_skills> 섹션이 포함되어 있어 사용 가능한 모든 Skill의 목록과 설명이 들어있다.

<available_skills>
<skill>
<n>dev-browser:dev-browser</n>
<description>
Browser automation with persistent page state. Use when users ask to 
navigate websites, fill forms, take screenshots, extract web data, 
test web apps, or automate browser workflows. Trigger phrases include 
"go to [url]", "click on", "fill out the form", "take a screenshot"...
</description>
<location>plugin</location>
</skill>
</available_skills>

사용자의 요청 "Go to code.claude.com/docs, click on the search box..."가 dev-browser의 description에 있는 트리거 프레이즈 "go to [url]", "click on"과 매칭된다. 에이전트는 이 매칭을 발견하고 Skill 도구를 호출한다.

{
  "type": "tool_use",
  "id": "toolu_017StpNdwovc4Lm8tGfK9XnA",
  "name": "Skill",
  "input": {
    "skill": "dev-browser:dev-browser",
    "args": "Go to code.claude.com/docs, click on the search box, type \"hooks\", and tell me what results appear"
  }
}

skill 필드에 plugin name을 포함한 qualified name(plugin-name:skill-name)이 사용되고 args에는 사용자의 원본 요청이 그대로 전달되었다.

Skill 도구의 tool_result로 SKILL.md 전체 내용이 반환된다.

Launching skill: dev-browser:dev-browser

Base directory for this skill: /Users/dev-test/.claude/plugins/cache/
dev-browser-marketplace/dev-browser/58c332a7c61a/skills/dev-browser

# Dev Browser Skill

Browser automation that maintains page state across script executions. 
Write small, focused scripts to accomplish tasks incrementally...

## Setup

First, start the dev-browser server using the startup script:

```bash
./skills/dev-browser/server.sh &
```

## Writing Scripts

Execute scripts inline using heredocs:

```bash
cd skills/dev-browser && npx tsx <<'EOF'
import { connect } from "@/client.js";
const client = await connect();
const page = await client.page("homepage");
// Your automation code here
await client.disconnect();
EOF
```

ARGUMENTS: Go to code.claude.com/docs, click on the search box...

tool_result에는 SKILL.md에 있는 모든 지시문이 포함되어 있다. ARGUMENTS에는 원본 사용자 요청이 첨부되어 있어 에이전트가 참조할 수 있다.

이제 에이전트는 SKILL.md의 지시문을 읽고 순서대로 작업을 수행한다. 먼저 Setup 섹션에 따라 서버를 시작한다.

{
  "type": "tool_use",
  "name": "Bash",
  "input": {
    "command": "cd /Users/dev-test/.claude/plugins/cache/dev-browser-marketplace/dev-browser/58c332a7c61a/skills/dev-browser && ./server.sh &",
    "description": "Start dev-browser server"
  }
}

서버가 준비되면 SKILL.md의 인라인 코드 템플릿을 참고하여 브라우저 자동화 스크립트를 작성하고 실행한다.

{
  "type": "tool_use",
  "name": "Bash",
  "input": {
    "command": "cd /Users/dev-test/.claude/plugins/cache/dev-browser-marketplace/dev-browser/58c332a7c61a/skills/dev-browser && npx tsx <<'EOF'\nimport { connect, waitForPageLoad } from \"@/client.js\";\n\nconst client = await connect();\nconst page = await client.page(\"claude-docs\");\nawait page.setViewportSize({ width: 1280, height: 800 });\n\nawait page.goto(\"https://docs.anthropic.com/en/docs/claude-code\");\nawait waitForPageLoad(page);\n\nconsole.log(\"Current URL:\", page.url());\nconst snapshot = await client.getAISnapshot(\"claude-docs\");\nconsole.log(snapshot);\n\nawait client.disconnect();\nEOF",
    "description": "Navigate to Claude Code docs"
  }
}

에이전트는 SKILL.md의 코드 템플릿을 그대로 복사하지 않는다. 템플릿 구조(import, connect, heredoc 패턴)를 따르되 작업에 맞게 즉석에서 코드를 작성한다. page.goto() URL이나 selectSnapshotRef() ref ID 등을 동적으로 결정한다.

SKILL.md가 명시한 Workflow Loop 패턴에 따라 Write a script → Run it → Evaluate → Decide → Repeat 과정이 반복된다. 페이지 탐색 스크립트 실행 → ARIA 스냅샷 확인 → 검색 버튼 클릭 → 검색어 입력 → 결과 확인 순서로 진행된다.

전체 흐름을 정리하면 다음과 같다.

User: "Go to code.claude.com/docs... Use dev-browser"
        │
        ▼
LLM: available_skills에서 매칭 발견
     description에 "go to", "click on" 트리거 포함
        │
        ▼
tool_use: Skill
  skill: "dev-browser:dev-browser"
  args: "Go to code.claude.com/docs..."
        │
        ▼
tool_result: SKILL.md 전체 + Base directory + ARGUMENTS
        │
        ▼
LLM: SKILL.md 지시문 해석
     "First, start the dev-browser server"
        │
        ▼
tool_use: Bash (./server.sh &)  ──► tool_result: "Server ready"
        │
        ▼
LLM: heredoc 템플릿 참고하여 스크립트 작성
     page.goto(), getAISnapshot() 활용
        │
        ▼
tool_use: Bash (npx tsx <<'EOF'...)
        │
        ▼
tool_result: snapshot 출력 (ARIA 트리)
        │
        ▼
(반복: 클릭, 입력, 스크린샷 등)

Skill 도구의 역할은 SKILL.md 파일 경로를 해석하고 전체 내용을 tool_result로 반환하는 것뿐이다. 실제 능력은 에이전트가 SKILL.md를 읽고 지시문에 따라 다른 도구들을 사용하면서 발현된다.

Agent Skill과 Subagent

Subagent와 Agent Skill은 서로 다른 문제를 해결한다.

Subagent는 컨텍스트 분리가 필요할 때 사용한다. 탐색이나 분석 과정이 메인 대화를 오염시키면 안 될 때 적합하다. 예를 들어 코드베이스 전체를 탐색해야 하는데 그 과정의 모든 파일 내용이 메인 컨텍스트에 쌓이면 금방 컨텍스트가 소진된다. Subagent는 독립적인 컨텍스트 윈도우에서 작업하고 결과만 반환한다. 또한 가벼운 모델(Haiku)로 빠르게 처리하거나 무거운 모델(Opus)로 깊이 분석하는 선택이 가능하다.

Agent Skill은 절차적 지식이 필요할 때 사용한다. PDF 폼 채우기나 브라우저 자동화처럼 "어떻게 해야 하는지"에 대한 베스트 프랙티스가 있는 작업에 적합하다. Skill은 현재 컨텍스트를 공유하면서 지시문만 추가로 주입한다. 별도의 메시지 루프를 만들지 않는다.

Agent Skill과 MCP

MCP와 Agent Skill도 역할이 다르다.

MCP는 외부 시스템과의 연동이 필요할 때 사용한다. 브라우저, 데이터베이스, 외부 API처럼 에이전트 내부에서 직접 실행하기 어려운 도구가 필요할 때 적합하다. MCP 서버는 외부 프로세스에서 실행되고 프로토콜을 통해 통신한다. 같은 도구를 여러 에이전트에서 공유할 수도 있다.

Agent Skill은 도구 사용 방법을 가르칠 때 사용한다. MCP가 "어떤 도구가 사용 가능한지"를 알려준다면 Skill은 "그 도구를 어떻게 효과적으로 사용하는지"를 가르친다. 실제로 mcp-builder라는 Skill은 MCP 서버를 더 잘 만들기 위한 지식을 제공한다. Skill이 MCP를 대체하는 것이 아니라 보완하는 관계다.

마무리

지금까지 Agent Skill이 Tool Use 위에서 어떻게 동작하는지 알아보았다.

Skill 도구가 tools 배열에 정의되어 있고 tool_use → tool_result 사이클을 거친다. 이는 Subagent(Task 도구)나 MCP(mcp__xxx 도구)와 동일한 패턴이다.

tools 배열
├── 내장 도구 (Bash, Read, Glob...)
│   └── Host 내부에서 직접 실행
│
├── Task 도구 (Subagent)
│   └── 새 메시지 루프에서 LLM 응답 반환
│
├── mcp__xxx 도구 (MCP)
│   └── 외부 서버의 실행 결과 반환
│
└── Skill 도구 (Skills)
    └── SKILL.md 로드 후 후속 도구 사용 안내

Agent Skill은 다른 도구 사용을 안내하는 메타 도구다. tool_result로 지시문을 컨텍스트에 주입하고 이후 Bash, Read 같은 다른 도구들의 사용을 안내한다. 결국 Skill → Bash → Read... 형태의 도구 체이닝이 발생한다.

Subagent와 MCP가 "무엇을 할 수 있는가"를 확장한다면 Skills는 "어떻게 잘 할 것인가"를 확장한다.