15.5 · Chia sẻ skill với team & tổ chức

Mở đầu: Từ "skill của tôi" sang "skill của team"

• Mọi PR review output cùng format (reviewer mới không phải "học style")
• Feedback tone nhất quán (không có review harsh chỗ này, soft chỗ khác)
• Compliance check (security, a11y) không bị miss
• New hire onboard nhanh: clone repo về, skill đã nằm trong .claude/skills/, Claude của họ review đúng style từ ngày đầu

Otto (Anthropic) tổng kết:

Skills become much more valuable when they're shared. A PR review skill that only you use is helpful, but that same skill shared across your entire team standardizes code review and creates a consistent experience across your organization.

Bài này cover 3 phương pháp share, từ đơn giản nhất (Git commit) tới mạnh nhất (enterprise deploy). Plus: cách wire skill vào subagent — điểm gây surprise nhất.

3 phương pháp share — Tổng quan

┌────────────────────────────────────────────┐
│  🏢 1. Enterprise  (managed settings)      │ ← cao nhất, mandatory
├────────────────────────────────────────────┤
│  👤 2. Personal    (~/.claude/skills)      │
├────────────────────────────────────────────┤
│  📦 3. Project     (.claude/skills, Git)   │ ← team standards
├────────────────────────────────────────────┤
│  🔌 4. Plugins     (marketplace install)   │ ← cross-team reusable
└────────────────────────────────────────────┘

Phương pháp 1: Commit skill vào repository

Đây là cách đơn giản nhất, phổ biến nhất, và đủ cho 80% trường hợp team.

Cấu trúc thư mục

my-app/                                 ← root của repo
├── .claude/
│   ├── skills/                         ← skill của team
│   │   ├── pr-review/
│   │   │   └── SKILL.md
│   │   ├── commit-format/
│   │   │   └── SKILL.md
│   │   └── brand-guidelines/
│   │       ├── SKILL.md
│   │       └── references/
│   │           └── full-brand-book.md
│   ├── agents/                         ← custom subagent (optional)
│   ├── hooks/                          ← hook settings (optional)
│   └── settings.json                   ← Claude Code config (optional)
├── src/
├── package.json
└── README.md

Workflow chia sẻ

Step 1: Tạo skill như đã học ở Bài 15.2/15.4, nhưng đặt ở .claude/skills/ (project) thay vì ~/.claude/skills/ (personal):

cd /path/to/my-app
mkdir -p .claude/skills/pr-review

Step 2: Commit và push:

git add .claude/skills/pr-review
git commit -m "chore: add pr-review skill for team standardization"
git push

Step 3: Team member pull về:

git pull

Step 4: Restart Claude Code. Skill đã available cho toàn team.

Đó là tất cả. Không cài đặt thêm. Git workflow bình thường.

Ưu điểm

• Zero friction: dev đã biết Git, không cần học tool mới
• Version control: git log .claude/skills/ cho lịch sử thay đổi skill
• PR review cho skill: skill mới được team review như code khác
• Rollback được: git revert nếu skill mới phá vỡ workflow
• Branch per skill: thử nghiệm skill mới trên feature branch

Nhược điểm

• Phụ thuộc repo: chỉ dùng được khi clone repo này → không dùng cho skill cross-project
• Scope limit: team nhỏ OK. Tổ chức 500 người dùng nhiều repo → không scale

Prompt tip cho việc setup lần đầu

Litton (AI University) gợi ý: Trong VS Code Claude Code, bạn có thể bảo Claude tự tạo structure:

initialize this project with a simple .claude/skills structure

Claude Code sẽ tạo .claude/skills/ với sample skill mẫu. Sau đó bạn replace content.

Gotcha: Enable skill trong settings

Trước khi skill hoạt động, bạn (và mỗi team member) phải enable skill feature:

Settings → Search skill → Check "use agent skills".

Nếu quên bước này, skill không trigger dù đã đúng tất cả. Otto: "Then only you will be able to do anything here."

Case study: Team engineering 12 người

Trước khi share skill:

• 12 dev, 12 style review PR hơi khác nhau
• New hire mất 2 tuần hiểu "style review của team này"
• Tech lead paste lại review instruction ~40 lần/tuần trong các session Claude

Sau khi share skill .claude/skills/pr-review:

• 12 dev cùng format review output
• New hire: ngày 1 clone repo, Claude review theo đúng style team
• Tech lead gõ "review PR #142" → skill trigger, 0 dòng instruction prefix

Tiết kiệm thực tế: ~30 phút/dev/tuần = 6 giờ/team/tuần = 300 giờ/năm.

Phương pháp 2: Plugin marketplace

Khi nào cần

Phương pháp 1 OK cho skill gắn với 1 repo. Nhưng nếu bạn có skill reusable qua nhiều project, nhiều team, nhiều tổ chức? Plugin là cách tiếp theo.

Ví dụ skill phù hợp plugin:

• seo-blog-writer — áp dụng cho mọi project content marketing
• jest-test-generator — hữu ích cho bất kỳ JS project nào
• owasp-security-audit — check chung cho web app
• conventional-commits — standard cross-industry

Điểm chung: không gắn với codebase/convention riêng của 1 team nào.

Plugin structure

my-plugin/
├── plugin.json                  ← metadata plugin
├── skills/                      ← cùng convention như .claude/skills/
│   ├── seo-blog-writer/
│   │   └── SKILL.md
│   └── conventional-commits/
│       └── SKILL.md
└── README.md

Distribution

1. Push plugin lên GitHub repo hoặc npm package
2. Publish lên marketplace (khi Claude Code hỗ trợ)
3. User install: claude plugin install <plugin-name>
4. Skills trong plugin available ở tầng priority 4 (plugin — thấp nhất)

Skill Anthropic ship sẵn (ví dụ marketplace)

Tính đến thời điểm viết, Anthropic đã ship một số skill built-in như plugin demonstrate:

• skill-creator — wizard tạo skill mới (tự tạo skill!)
• canvas-design — design canvas layout
• theme-factory — tạo color theme
• slack-gif-creator — generate GIF cho Slack
• powerpoint-generator — tạo PowerPoint deck

Litton mô tả: "miniature automation bots." Bạn có thể xem/dùng các skill này, học structure, rồi build skill tương tự cho domain của mình.

Ưu điểm

• Cross-team, cross-org reuse
• Community contribute được (open source plugin)
• Phân phối rộng (hàng ngàn người dùng)

Nhược điểm

• Priority thấp nhất (tầng 4) → enterprise/personal/project đè được
• Quality phụ thuộc plugin author
• Phải tin plugin author (không execute code lạ từ plugin)

Security concern

Plugin có thể chứa script trong scripts/. Khi skill trigger, Claude có thể chạy script đó. Luôn audit plugin trước khi cài — xem SKILL.md và scripts của plugin, chắc chắn không có gì suspicious.

Phương pháp 3: Enterprise managed settings

Khi nào cần

Khi bạn muốn mandatory standards — không ai trong tổ chức được bypass:

• Security audit phải chạy trên mọi code review
• Compliance check phải có cho healthcare/finance
• Code style phải nhất quán toàn công ty

Otto nhấn mạnh từ: "The keyword here is 'must'."

Enterprise skill override personal skill, project skill, plugin skill cùng tên.

Cấu trúc managed settings

Admin deploy file managed-settings.json ở location platform-specific. Trong đó khai báo skill location + policy:

{
  "skills": {
    "skillDirectories": [
      "/opt/acme-corp/skills"
    ],
    "strictKnownMarketplaces": [
      {
        "source": "github",
        "repo": "acme-corp/approved-plugins"
      },
      {
        "source": "npm",
        "package": "@acme-corp/compliance-plugins"
      }
    ]
  }
}

Giải thích:

• skillDirectories — folder trên máy dev chứa enterprise skill (deploy qua MDM hoặc image)
• strictKnownMarketplaces — whitelist marketplace. Dev chỉ được cài plugin từ nguồn này

Case study: Ngân hàng với compliance requirements

Pain: Ngân hàng có 300 dev, yêu cầu mỗi PR review phải check:

• Không log PII (personally identifiable information) ra console
• Không hard-code secret
• Audit log tất cả query access DB production

Trước: policy tồn tại ở wiki, dev nhớ thì check, quên thì không.

Với enterprise skill:

---
name: code-review
description: Code review with mandatory compliance checks. Use when reviewing PR or code change.
allowed-tools: Read, Grep, Glob
---

Every code review MUST include:

1. PII scan: grep for names/emails/SSN patterns in logs
2. Secret scan: check for API keys, passwords hardcoded
3. Audit log requirement: all DB production access must have audit call
4. Sign-off: review is not complete without all 3 checks passed

Result:

• Dev gõ "review this PR" → trigger skill code-review
• Enterprise version override nếu dev có personal code-review
• 3 check compliance luôn chạy, không miss

Dev không happy → complain. Admin reply: "bạn có thể tạo personal-code-review riêng cho style cá nhân. Enterprise code-review là mandatory, không bypass."

Ưu điểm

• Priority cao nhất — không ai bypass được
• Centralized management — admin deploy 1 lần, toàn org có
• Security + compliance enforced automatically

Nhược điểm

• Cần admin access platform/deployment tool (MDM, corp laptop image)
• Setup phức tạp (MDM profile, managed settings JSON)
• Friction với dev cá nhân (họ mất customization rights cho cùng skill name)

Workaround cho dev: đặt tên khác

Dev không thích style enterprise? Tạo skill với tên khác, trigger cùng thứ:

Enterprise: code-review  (mandatory, formal)
Personal:   my-code-review  (informal, cá nhân)

User gõ "review this PR" → semantic match có thể match cả 2. Claude hỏi "dùng code-review hay my-code-review?" — dev chọn.

Skill với subagent — Gotcha quan trọng

Đây là phần hay bỏ qua nhưng critical nếu team bạn dùng subagent.

Gotcha chính: Subagent KHÔNG inherit skill tự động

Tưởng tượng setup của bạn:

.claude/
├── skills/
│   ├── a11y-standard/
│   └── pr-review/
└── agents/
    └── frontend-reviewer.md

Bạn kỳ vọng: delegate task cho frontend-reviewer → subagent tự có 2 skill trên.

Thực tế: KHÔNG. Otto:

Subagents don't automatically see your skills. When you delegate a task to a subagent, it starts with a fresh, clean context.

Subagent fresh context. Skill không auto available.

Thêm nữa: Built-in agent không access skill được

Có 2 loại subagent:

1. Built-in (Explorer, Plan, Verify) — không access skill được, ever
2. Custom (bạn tạo) — access được skill, nhưng phải explicit list

Cách đúng: Khai báo skills field trong agent.md

---
name: frontend-reviewer
description: Reviews frontend code for accessibility, performance, design system compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch, Skill
model: sonnet
color: blue
skills: a11y-standard, pr-review, design-system-check
---

You are a frontend code reviewer. For each code change, check:

1. Accessibility (use a11y-standard skill)
2. Code quality (use pr-review skill)
3. Design system compliance (use design-system-check skill)

Output: structured review with severity labels (critical/major/minor).

Field skills: list skill name (không có path). Claude load các skill này khi subagent start.

Khi subagent load skill?

• Khi subagent start (không on-demand như main conversation)
• Tất cả skill trong skills: load hết vào subagent context
• Dữ liệu tổng của các skill ăn context của subagent

Implication: Chỉ list skill luôn relevant cho purpose của subagent. Đừng add skill "for safety" — nó ăn context ngay cả khi task không cần.

Pattern: Specialized subagent + shared skill

Otto pattern:

Your front-end developer subagent can use a component pattern skill. Your UI reviewer subagent can use a design system skill, but both can load and use the same accessibility standard skill.

agents/
├── frontend-developer.md    skills: [component-patterns, a11y-standard]
├── ui-reviewer.md            skills: [design-system, a11y-standard]
└── backend-reviewer.md       skills: [api-conventions, sql-perf-check]

skills/
├── component-patterns/       ← dùng bởi frontend-developer
├── design-system/            ← dùng bởi ui-reviewer
├── a11y-standard/            ← SHARED giữa frontend-developer & ui-reviewer
├── api-conventions/          ← dùng bởi backend-reviewer
└── sql-perf-check/           ← dùng bởi backend-reviewer

Mỗi subagent đặc biệt hóa theo role. Skill reusable qua nhiều subagent. Skill a11y-standard viết 1 lần, dùng 2 chỗ.

Pattern này phù hợp khi:

• Bạn muốn isolated task delegation với specific expertise
• Subagent khác nhau cần skill khác nhau (frontend vs backend)
• Enforce standards trong delegated work không dựa vào prompt

Workflow tạo subagent với skill

Cách 1: Dùng command /agents trong Claude Code

/agents

Claude Code wizard interactive hỏi:

• Tên subagent
• Description
• Tools allowed
• Skills to load ← chọn từ danh sách skill đã có

Claude Code generate file .claude/agents/<name>.md với đúng frontmatter.

Cách 2: Tạo file manual

cat > .claude/agents/security-auditor.md << 'EOF'
---
name: security-auditor
description: Audits code for security vulnerabilities per OWASP top 10.
tools: Read, Grep, Glob, Bash
model: opus
color: red
skills: owasp-check, secret-scan, dependency-audit
---

[instructions...]
EOF

Restart Claude Code → subagent available.

Đảm bảo skill exist trước

Trước khi thêm skill vào subagent, check skill thực sự tồn tại trong .claude/skills/ hoặc ~/.claude/skills/. Nếu không, subagent sẽ fail khi start.

ls .claude/skills/owasp-check

So sánh 3 phương pháp share — Decision matrix

┌────────────────────────────────────────────────────────────┐
│  Câu hỏi: Bạn muốn ai dùng skill?                          │
└────────────────────────────────────────────────────────────┘
                            ↓
        ┌───────────────────┼───────────────────┐
        ↓                   ↓                   ↓
    Team cùng          Bất kỳ ai có      Toàn tổ chức,
    repo               Claude Code        mandatory
        ↓                   ↓                   ↓
   ┌─────────┐         ┌─────────┐        ┌─────────┐
   │   Git   │         │ Plugin  │        │Enterprise│
   │  repo   │         │marketplace│      │ managed │
   │         │         │         │        │settings │
   └─────────┘         └─────────┘        └─────────┘
   Priority 3          Priority 4         Priority 1
   Dễ: ⭐⭐⭐⭐⭐        Dễ: ⭐⭐⭐           Dễ: ⭐⭐

Checklist chọn phương pháp

Case studies theo role

Sales team sharing CRM prep skill

Setup: .claude/skills/prep-call/ trong repo sales-playbook-internal.

Skills content:

• Pull CRM account data (qua MCP salesforce-mcp)
• Pull email history (qua MCP gmail-mcp)
• Output: 1-page briefing với talking points

Impact: 20 AE × 45 phút prep/call → 5 phút. Tổng: ~13 giờ/ngày tiết kiệm team-wide.

Marketing team sharing brand voice skill

Setup: .claude/skills/blog-post-writer/ trong repo content-marketing-hub.

Skills content:

• references/brand-voice.md — trích từ brand book 40 trang
• references/seo-checklist.md — 27 điểm
• references/past-winners.md — 10 blog post top performance
• SKILL.md orchestrate workflow

Impact: Content writer mới onboard ngày 1 đã produce content on-brand. Tone consistent 100%.

Finance team — Enterprise compliance skill

Setup: Enterprise /opt/acme-finance/skills/sox-compliance-check/.

Skills content:

• Mandatory check cho SOX compliance mọi financial report
• Audit log mọi access vào financial data
• Escalation path nếu detect violation

Enterprise deploy: Admin push qua MDM lên mọi finance laptop. Dev không bypass được.

Legal — Plugin cho OSS community

Setup: contract-review-open plugin publish lên npm.

Skills content:

• Review NDA, MSA, SOW theo templates public
• Red flag common patterns
• Không include proprietary data (open source)

Impact: Community legal pro dùng, tạo community around plugin, feedback loop improve skill.

Healthcare — Multi-tier setup

Setup:

• Enterprise: mandatory-phi-check (PHI = Protected Health Info)
• Project: clinical-research-workflow (trong repo study-specific)
• Personal: my-research-style (của mỗi researcher)

Priority resolution:

• User gõ "review this study data" → semantic match phi-check first (enterprise override)
• Rồi Claude còn match clinical-research-workflow (project)
• Nếu personal my-research-style cùng tên → bị enterprise đè

Anti-patterns — Sai lầm khi share skill

Push skill chứa secret vào repo

Sai lầm:

---
name: deploy-to-prod
description: ...
---

API_KEY=sk_live_abc123...  ← HARDCODED!

Tại sao tệ

Secret trong Git = secret compromised. Dù xóa sau cũng vẫn ở lịch sử.

Cách đúng

Dùng env variable. SKILL.md: "run with DEPLOY_API_KEY env set." Secret ở .env file trong .gitignore.

Enterprise deploy skill không test cẩn thận

Sai lầm

Admin push enterprise code-review ảnh hưởng 500 dev. Sau 1 ngày mới phát hiện skill có bug, break review của ai cũng.

Tại sao tệ

Enterprise priority cao nhất → không ai escape được bug.

Cách đúng:

1. Trial ở team nhỏ (10-20 dev) trước
2. Staging environment trước production deploy
3. Rollback plan sẵn (version trước trong managed settings)

Plugin chứa code malicious

Sai lầm

Install plugin lạ mà không audit. Plugin có script scripts/steal-credentials.sh.

Tại sao tệ

Khi skill trigger, Claude chạy script → credential leak.

Cách đúng:

• Admin whitelist marketplace qua strictKnownMarketplaces
• Audit plugin source code trước install
• Enterprise: block plugin install ngoài whitelist

Skill trong repo nhưng không document

Sai lầm

.claude/skills/ có 15 skill, README.md repo không mention.

Tại sao tệ

New hire clone repo không biết skill nào có. Dùng một vài cái ngẫu nhiên, miss những cái hữu ích.

Cách đúng

README.md repo có section "Available Skills":

Claude Code Skills

This project ships with the following team skills:

• pr-review — team code review standard. Trigger: "review this PR"
• commit-format — conventional commits. Trigger: "write commit message"
• incident-response — postmortem template. Trigger: "postmortem for incident"

### ❌ Subagent skill list không match thực tế

**Sai lầm:**

skills: a11y-standard, nonexistent-skill, old-deleted-skill

**Tại sao tệ:** Subagent fail khi start vì skill không tìm thấy.

**Cách đúng:** Audit subagent khi xóa/rename skill. Check `.claude/agents/*.md` sau mỗi skill change.

---

Áp dụng ngay

Bài tập 1: Share skill đầu tiên cho team (~15 phút)

Bước 1

Lấy 1 skill bạn đã làm ở Bài 15.2 hoặc 15.4, đang ở personal ~/.claude/skills/.

Bước 2

Quyết định: skill này có phù hợp project này không? Nếu có, di chuyển sang project:

cd /path/to/project
mkdir -p .claude/skills
mv ~/.claude/skills/<tên-skill> .claude/skills/

Bước 3

Update README.md của project với section skill list.

Bước 4

Commit:

git add .claude/skills/<tên-skill> README.md
git commit -m "chore: add <tên-skill> skill for team"
git push

Bước 5: Báo team trong channel: "Mình vừa add skill X, mọi người pull về và gõ [trigger phrase] để dùng."

Bài tập 2: Tạo subagent dùng skill (~10 phút)

Bước 1

Pick 2-3 skill bạn muốn combine.

Bước 2

Trong Claude Code session, gõ /agents để wizard mở.

Bước 3

Điền:

• Name: <role>-reviewer (ví dụ frontend-reviewer)
• Description: role của subagent
• Skills: list 2-3 skill ở Bước 1

Bước 4

Wizard generate file .claude/agents/<name>.md. Review frontmatter có skills: field chưa.

Bước 5

Test: trong Claude Code, delegate task cho subagent — kiểm tra có dùng skill không.

Tóm tắt bài học

Tài liệu tham khảo

• Anthropic Academy — "Sharing skills"
• Video — "Distributing skills"
• Claude Code — /agents command docs
• Enterprise managed settings — official Claude Code docs