---
id: ai-skills-patterns
title: AI Skills — 재사용 가능 Instruction + Tools
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [ai, skills, anthropic, vibe-coding]
tech_stack: { language: "Markdown / TS", applicable_to: ["Backend"] }
applied_in: []
aliases: [Skills, Anthropic Skills, Claude Skills, instruction packs, agent capabilities]
---

# AI Skills

> 재사용 instruction + scripts 묶음. **Filesystem-based**, 한 번 정의 → 여러 사용. Anthropic Skills, Claude Skills, custom agent capabilities.

## 📖 핵심 개념
- SKILL.md: 사용 instruction.
- Scripts: supporting code (`scripts/`).
- References: 추가 context files.
- Auto-trigger: 관련 시 자동 inject.

## 💻 코드 패턴

### Skill folder
```
.claude/skills/
└── code-review/
    ├── SKILL.md
    ├── scripts/
    │   ├── analyze.ts
    │   └── format-report.ts
    └── references/
        ├── style-guide.md
        └── checklist.md
```

### SKILL.md 형식
```markdown
---
name: code-review
description: Review TypeScript / React PRs against team style guide
---

# Code Review

You're a senior engineer reviewing a PR.

## Process
1. Read changed files
2. Run `scripts/analyze.ts` for static issues
3. Check against `references/style-guide.md`
4. Output review in `references/checklist.md` format

## Rules
- Severity: must-fix / suggestion / nit
- Quote line numbers
- Suggest specific fix

## Tools
- Bash, Read, Grep
- `bun run scripts/analyze.ts <file>` for AST analysis
```

### Skill discovery (auto-trigger)
```
Description matched → auto-inject into agent context.

User: "Review this PR"
→ Agent matches "code-review" skill
→ Loads SKILL.md + relevant references
```

### 자체 skill system
```ts
import fs from 'node:fs';
import path from 'node:path';
import matter from 'gray-matter';

interface Skill {
  name: string;
  description: string;
  content: string;
  scriptsDir: string;
}

class SkillLoader {
  private skills: Skill[] = [];
  
  constructor(dir: string) {
    for (const name of fs.readdirSync(dir)) {
      const skillDir = path.join(dir, name);
      const skillFile = path.join(skillDir, 'SKILL.md');
      if (fs.existsSync(skillFile)) {
        const { data, content } = matter(fs.readFileSync(skillFile, 'utf8'));
        this.skills.push({
          name: data.name ?? name,
          description: data.description ?? '',
          content,
          scriptsDir: path.join(skillDir, 'scripts'),
        });
      }
    }
  }
  
  async findRelevant(userQuery: string, llm: LLM): Promise<Skill[]> {
    // LLM 가 description 기반 선택
    const r = await llm.complete({
      system: `Given a user query, return JSON of skill names that are relevant.
Skills:
${this.skills.map(s => `- ${s.name}: ${s.description}`).join('\n')}

Output: { "relevant": ["name1", "name2"] }`,
      user: userQuery,
      response_format: { type: 'json_object' },
    });
    
    const { relevant } = JSON.parse(r);
    return this.skills.filter(s => relevant.includes(s.name));
  }
}
```

### Inject into agent
```ts
async function chat(userMsg: string) {
  const relevantSkills = await skillLoader.findRelevant(userMsg, llm);
  
  const skillSection = relevantSkills.length > 0 ? `
## Available Skills

${relevantSkills.map(s => `### ${s.name}\n${s.content}`).join('\n\n')}
` : '';
  
  const system = `You are a helpful assistant.${skillSection}`;
  
  return await agent.run({ system, userMsg });
}
```

### Skills + tools (script execution)
```markdown
# SKILL.md
## Tools
- `bash scripts/run-tests.sh` — runs project tests
- `node scripts/analyze.js <file>` — AST analysis
```

```ts
// Agent 가 Bash tool 으로 script 실행
const result = await agent.callTool('bash', {
  command: `node ${skill.scriptsDir}/analyze.js ${file}`,
});
```

### Skill versioning
```
.claude/skills/code-review/v2/
.claude/skills/code-review/v1/

// SKILL.md 안 version 명시
```

### Skill testing
```ts
test('code-review skill produces severity labels', async () => {
  const result = await runSkill('code-review', { input: samplePR });
  expect(result).toMatch(/must-fix|suggestion|nit/);
});
```

### Skill marketplace (개념)
```
공유 skill repo (npm 처럼).
재사용 + community + version.

claude-skills.com 같은 곳 — OSS.
```

### 좋은 skill 패턴
```
1. Single responsibility — 한 task.
2. Self-contained — 외부 의존 최소.
3. Self-describing — description 풍부.
4. Verifiable — 결과 검증 가능.
5. Tool-aware — 어떤 tool 필요 명시.
```

### 안 좋은 skill 패턴
```
1. 너무 generic ("be helpful" — 의미 없음).
2. Description 빈약 — 매칭 안 됨.
3. Scripts 외부 API 의존 — 실패 가능.
4. Multi-purpose god skill — 분리.
5. Implicit tool — 사용자 모름.
```

### Skill vs Tool vs Prompt
```
Tool:    한 함수 — read_file, execute_sql.
Skill:   여러 step + instruction — 사용자가 task 보고 사용.
Prompt:  단순 template — placeholder.

Skill = Tool + instruction + ranking.
```

### Personality / persona via skill
```markdown
# SKILL.md
---
name: socratic-tutor
description: Teach by asking guiding questions, never give direct answers
---

You are a Socratic tutor. Ask questions to guide the student to understanding.
Never give the answer directly.
Encourage exploration and reasoning.
```

→ Agent 가 user query 가 학습 관련 시 자동 적용.

### Composability
```
Multiple skills 동시:
- code-review + security-audit + perf-check

각 skill 의 instruction 가 합쳐짐.
Conflict 시 higher-priority 선언.
```

### Use case
```
- Code review
- Document analysis
- Customer support (tone, knowledge)
- Data analysis (SQL)
- Translation (language pair, style)
- Email composition (tone, brevity)
- Technical writing
- Test generation
```

### Implementation 종류
```
Anthropic Claude:    .claude/skills/ (CLI / Desktop).
Cursor:              .cursorrules / .cursor/.
GitHub Copilot:      custom instructions in IDE.
자체 agent:          위 SkillLoader pattern.
```

### Description 매칭 정확도
```
Bad:  description: "useful tool"
Good: description: "Review TypeScript PRs against team style guide. Trigger on phrases like 'review this PR' or 'check this code change'."
```

→ LLM 가 description 으로 선택. 명확.

### Limit (token cost)
```
모든 skill 의 SKILL.md 매번 inject = 큰 cost.
→ Lazy load — 필요 시만.
→ 또는 skill 가 작게 (200-500 token).
```

## 🤔 의사결정 기준
| 상황 | 추천 |
|---|---|
| 자주 쓰는 task | Skill |
| 1회성 | Prompt |
| Tool + flow | Skill (with scripts) |
| 단순 helper | Tool 만 |
| Persona | Skill |
| Domain knowledge | RAG + skill |

## ❌ 안티패턴
- **모든 거 skill 화**: overload.
- **Description 빈약**: 매칭 X.
- **Scripts 안 test**: 깨짐.
- **External API in skill**: failure.
- **Token 무관 — 전부 inject**: 비용.
- **Versioning 없음**: skill 변경 시 깨짐.

## 🤖 LLM 활용 힌트
- SKILL.md + scripts + references 표준.
- LLM 가 description 으로 매칭.
- 작게 + composable.
- Anthropic Claude + 자체 agent 둘 다 사용.

## 🔗 관련 문서
- [[AI_LangGraph_Agent_Frameworks]]
- [[AI_MCP_Server_Building]]
- [[AI_Agentic_Patterns]]