Back to Details

claude-collaboration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Code Collaboration Best Practices

Claude Code 团队协作最佳实践

This skill provides guidance on effectively using Claude Code in team environments, managing shared knowledge through skills, and maximizing value from AI-assisted development.
本Skill提供在团队环境中高效使用Claude Code、通过Skill管理共享知识、最大化AI辅助开发价值的指南。

Core Principles

核心原则

  1. Skills are living documentation - They evolve as you learn
  2. Capture knowledge explicitly - Claude doesn't auto-update skills
  3. All skills live in $CLAUDE_METADATA - No local skills or commands in projects
  4. Share knowledge across the team - Centralized repo ensures consistency
  5. Version control your skills - Track changes and improvements
  6. Be intentional about updates - Not everything learned needs to be captured
  1. Skill是活的文档 - 它们会随着你的学习不断迭代
  2. 明确沉淀知识 - Claude不会自动更新Skill
  3. 所有Skill都存放在$CLAUDE_METADATA中 - 项目中不要存放本地Skill或命令
  4. 跨团队共享知识 - 集中式仓库确保一致性
  5. 对Skill进行版本控制 - 跟踪变更和优化内容
  6. 有针对性地更新 - 不是所有学到的内容都需要沉淀

Critical: No Local Skills or Commands

关键要求：禁止使用本地Skill或命令

ALL skills and commands MUST be in the $CLAUDE_METADATA repository, never in individual project directories.
Never do this:
bash
undefined
所有Skill和命令必须存放在$CLAUDE_METADATA仓库中，绝对不要放在单独的项目目录下。
禁止这样操作：
bash
undefined

Creating local skill in project

在项目中创建本地Skill

echo "---" > .claude/skills/my-local-skill/SKILL.md

**Always do this:**
```bash
echo "---" > .claude/skills/my-local-skill/SKILL.md

**请始终这样操作：**
```bash

Create skill in central repo

在中央仓库中创建Skill

mkdir -p $CLAUDE_METADATA/skills/project-name echo "---" > $CLAUDE_METADATA/skills/project-name/SKILL.md
mkdir -p $CLAUDE_METADATA/skills/project-name echo "---" > $CLAUDE_METADATA/skills/project-name/SKILL.md

Then symlink to project

然后软链接到项目

ln -s $CLAUDE_METADATA/skills/project-name .claude/skills/project-name

**Why centralization is mandatory:**
- **Version control**: All skills tracked in one git repo
- **Team sharing**: Everyone uses the same knowledge
- **Consistency**: No divergence between projects
- **Maintenance**: Update once, applies everywhere
- **Discovery**: Team can see all available skills

**Even project-specific skills go in the central repo** under `$CLAUDE_METADATA/skills/project-name/`.

---
ln -s $CLAUDE_METADATA/skills/project-name .claude/skills/project-name

**为什么必须采用集中式存储：**
- **版本控制**：所有Skill都在同一个git仓库中跟踪
- **团队共享**：所有人使用相同的知识
- **一致性**：项目之间不会出现内容分歧
- **易维护**：只需更新一次，所有地方都生效
- **易发现**：团队可以看到所有可用的Skill

**即使是项目专属的Skill也要存放在中央仓库的`$CLAUDE_METADATA/skills/project-name/`目录下。**

---

Understanding How Skills Work

了解Skill的工作原理

What Happens During a Session

会话过程中会发生什么

At session start:
  • Claude reads all 
    .claude/skills/
    files in your directory
  • Skills provide context and guidelines for the session
  • Knowledge from skills is "loaded" into Claude's working context
During the session:
  • Claude learns from your conversation (temporary, in-context learning)
  • Solutions discovered apply only to this conversation
  • Skills remain unchanged unless you explicitly update them
At session end:
  • All temporary learning is lost
  • Skills remain exactly as they were at the start
  • Next session starts fresh, reading skills again
会话启动时：
  • Claude会读取你目录下所有
    .claude/skills/
    中的文件
  • Skill为当前会话提供上下文和指导规则
  • Skill中的知识会被“加载”到Claude的工作上下文中
会话进行中：
  • Claude从你的对话中学习（临时的上下文内学习）
  • 发现的解决方案仅适用于当前对话
  • 除非你明确更新，否则Skill内容不会改变
会话结束时：
  • 所有临时学习的内容都会丢失
  • Skill内容和启动时完全一致
  • 下次会话会重新读取Skill，从头开始

What This Means

这意味着什么

  • Skills persist across sessions - They're files on disk
  • Session learnings don't persist - They exist only in conversation context
  • You must explicitly update skills - Claude won't do it automatically
  • Skill会跨会话持久化 - 它们是存储在磁盘上的文件
  • 会话学习内容不会持久化 - 仅存在于对话上下文中
  • 你必须明确更新Skill - Claude不会自动完成这个操作

When to Update Skills

什么时候需要更新Skill

Always Update Skills For:

以下场景请务必更新Skill：

  1. Repeated problems with known solutions
    • "We keep hitting this error, here's how to fix it"
    • Add to troubleshooting section
  2. New best practices discovered
    • "Using --quiet saves 85% tokens, use it by default"
    • Add to optimization guidelines
  3. Common workflows that need standardization
    • "Our team always does X before Y"
    • Add to standard procedures
  4. Configuration patterns that work
    • "This cron job setup works best for our HPC"
    • Add as recommended configuration
  5. Important architectural decisions
    • "We decided to use symlinks for global skills because..."
    • Document rationale for future reference
  1. 有已知解决方案的重复问题
    • “我们经常遇到这个错误，修复方法如下”
    • 添加到故障排查部分
  2. 新发现的最佳实践
    • “使用--quiet参数可以节省85%的token，默认请使用这个参数”
    • 添加到优化指南中
  3. 需要标准化的通用工作流
    • “我们团队始终在Y操作前先执行X”
    • 添加到标准流程中
  4. 经过验证的配置模式
    • “这个定时任务配置最适合我们的HPC环境”
    • 作为推荐配置添加
  5. 重要的架构决策
    • “我们决定对全局Skill使用软链接，原因是…”
    • 记录决策逻辑供后续参考

Don't Update Skills For:

以下场景不要更新Skill：

  1. One-time issues - Specific to a particular run or environment
  2. Experimental approaches - Wait until proven effective
  3. User-specific preferences - Unless they should be team defaults
  4. Obvious information - Already well-documented elsewhere
  5. Temporary workarounds - Not worth making permanent
  1. 一次性问题 - 仅特定运行或环境下才会出现的问题
  2. 实验性方案 - 等到验证有效后再添加
  3. 用户个性化偏好 - 除非需要设为团队默认规则
  4. 常识性内容 - 其他地方已经有完善文档的内容
  5. 临时解决方案 - 不值得永久固化的内容

Example: When to Update

示例：何时需要更新

Scenario 1: New error pattern discovered
Session: "WF8 fails when Hi-C files are missing R2 reads"
Action: ADD to troubleshooting - this will happen again
Rationale: Common issue with known solution
Scenario 2: One-off configuration issue
Session: "My personal laptop has Python 3.7, need 3.8"
Action: DON'T ADD to skill - personal environment issue
Rationale: Not relevant to others, not a recurring pattern
Scenario 3: Token optimization discovered
Session: "Using --quiet mode saves 15K to 2K tokens!"
Action: ADD to token efficiency skill
Rationale: Valuable for entire team, significant impact
场景1：发现新的错误模式
会话：“Hi-C文件缺失R2读段时WF8会运行失败”
操作：添加到故障排查部分 - 这个问题会再次出现
理由：是有已知解决方案的通用问题
场景2：一次性配置问题
会话：“我的个人笔记本装的是Python 3.7，需要升级到3.8”
操作：不要添加到Skill - 属于个人环境问题
理由：和其他人无关，不是重复出现的问题
场景3：发现token优化方法
会话：“使用--quiet模式可以把token消耗从15K降到2K！”
操作：添加到token效率Skill中
理由：对整个团队都有价值，影响显著

How to Update Skills

如何更新Skill

Method 1: Explicit Request (Recommended)

方法1：明确指令（推荐）

User: "We just solved the issue with workflow timeouts in HPC environments.
       Add this to the VGP skill under troubleshooting."

Claude: [Reads current skill, adds new troubleshooting entry, saves file]
用户：“我们刚刚解决了HPC环境下工作流超时的问题。把这个内容添加到VGP Skill的故障排查部分。”

Claude：[读取当前Skill，添加新的故障排查条目，保存文件]

Method 2: Ask Claude to Suggest Updates

方法2：让Claude建议更新内容

User: "Based on our work today, what should we add to the VGP skill?"
Claude: [Reviews conversation, suggests additions]
User: "Yes, add those three things."
Claude: [Updates skill file]
用户：“基于我们今天的工作，我们应该给VGP Skill添加哪些内容？”
Claude：[回顾对话，建议添加的内容]
用户：“好的，把这三点加上。”
Claude：[更新Skill文件]

Method 3: End-of-Session Summary

方法3：会话结束总结

User: "Summarize today's learnings and update the relevant skills."
Claude: [Creates summary, updates multiple skills if needed]
用户：“总结今天学到的内容，更新相关的Skill。”
Claude：[生成总结，必要时更新多个Skill]

Method 4: Periodic Review

方法4：定期回顾

User: "We've been working on VGP for a month.
       Review our conversation history and suggest skill improvements."
Claude: [Analyzes patterns, suggests updates]
用户：“我们已经开发VGP一个月了，回顾我们的对话历史，给出Skill优化建议。”
Claude：[分析模式，建议更新内容]

Skill Organization Patterns

Skill组织模式

Pattern 1: Project-Specific Skills (In Central Repo)

模式1：项目专属Skill（存放在中央仓库）

Use for: Project-specific knowledge (VGP workflows, Galaxy APIs)
Location: 
$CLAUDE_METADATA/skills/project-name/
(NOT in project directory)
$CLAUDE_METADATA/
└── skills/
    ├── my-project/              # Project-specific skill
    │   └── SKILL.md
    └── another-project/
        └── SKILL.md

my-project/
└── .claude/
    └── skills/
        └── my-project -> $CLAUDE_METADATA/skills/my-project  # Symlink only!
适用场景： 项目专属知识（VGP工作流、Galaxy API）
存放路径： 
$CLAUDE_METADATA/skills/project-name/
（不要放在项目目录下）
$CLAUDE_METADATA/
└── skills/
    ├── my-project/              # 项目专属Skill
    │   └── SKILL.md
    └── another-project/
        └── SKILL.md

my-project/
└── .claude/
    └── skills/
        └── my-project -> $CLAUDE_METADATA/skills/my-project  # 仅保留软链接！

Pattern 2: General Skills (Cross-Project)

模式2：通用Skill（跨项目）

Use for: General development practices, tool-agnostic optimizations, team-wide standards
Location: 
$CLAUDE_METADATA/skills/
适用场景： 通用开发实践、不绑定工具的优化方法、团队通用标准
存放路径： 
$CLAUDE_METADATA/skills/

Pattern 3: Symlinking Skills to Projects

模式3：将Skill软链接到项目

This is THE standard pattern - all projects use symlinks, no exceptions.
bash
undefined
这是标准模式 - 所有项目都使用软链接，没有例外。
bash
undefined

In each project

进入每个项目目录

cd /path/to/project mkdir -p .claude/skills .claude/commands
cd /path/to/project mkdir -p .claude/skills .claude/commands

Symlink skills from central repo

从中央仓库软链接Skill

ln -s $CLAUDE_METADATA/skills/token-efficiency .claude/skills/token-efficiency ln -s $CLAUDE_METADATA/skills/my-project .claude/skills/my-project
ln -s $CLAUDE_METADATA/skills/token-efficiency .claude/skills/token-efficiency ln -s $CLAUDE_METADATA/skills/my-project .claude/skills/my-project

Symlink commands from central repo

从中央仓库软链接命令

ln -s $CLAUDE_METADATA/commands/global/*.md .claude/commands/

**Critical rule:** Projects contain ONLY symlinks, never actual skill/command files.
ln -s $CLAUDE_METADATA/commands/global/*.md .claude/commands/

**关键规则：** 项目中仅保留软链接，绝对不要存放实际的Skill/命令文件。

Pattern 4: Skills with Supporting Documentation

模式4：带辅助文档的Skill

skills/skill-name/
├── SKILL.md              # Core concepts and quick reference
├── reference.md          # Detailed technical documentation
├── troubleshooting.md    # Common issues and solutions
├── examples/             # Code examples
└── templates/            # Template files
When to use:
  • SKILL.md is getting too long (>500 lines)
  • Detailed reference material available
  • Multiple categories of information (guides, troubleshooting, examples)
Best practice:
  • Keep SKILL.md under 500 lines
  • Move detailed guides to supporting files
  • Reference supporting files at end of SKILL.md
  • Use descriptive filenames (troubleshooting.md, not tips.md)
skills/skill-name/
├── SKILL.md              # 核心概念和速查参考
├── reference.md          # 详细技术文档
├── troubleshooting.md    # 常见问题和解决方案
├── examples/             # 代码示例
└── templates/            # 模板文件
适用场景：
  • SKILL.md内容过长（超过500行）
  • 有详细的参考材料
  • 包含多类信息（指南、故障排查、示例）
最佳实践：
  • 保持SKILL.md内容不超过500行
  • 把详细指南移动到辅助文件中
  • 在SKILL.md末尾引用辅助文件
  • 使用描述性文件名（比如troubleshooting.md，不要用tips.md）

Quick Reference

快速参考

Daily Workflow

日常工作流

1. Start session -> Claude reads skills
2. Work on task -> Learn new patterns
3. End session -> "What should we add to skills?"
4. Claude suggests -> You approve/modify
5. Git commit -> Share with team
1. 启动会话 -> Claude读取Skill
2. 处理任务 -> 学习新模式
3. 会话结束 -> 询问“我们应该给Skill添加哪些内容？”
4. Claude给出建议 -> 你确认/修改
5. Git提交 -> 共享给团队

Weekly Maintenance

每周维护

1. Review week's commits
2. Identify patterns across sessions
3. Consolidate related updates
4. Remove outdated info
5. Share changelog with team
1. 回顾本周提交
2. 识别跨会话的共性模式
3. 合并相关更新
4. 删除过时信息
5. 给团队同步变更日志

Monthly Review

月度回顾

1. Audit all skills for conflicts
2. Measure token savings
3. Collect team feedback
4. Major refactoring if needed
5. Update skill documentation
1. 检查所有Skill是否存在冲突
2. 统计token节省量
3. 收集团队反馈
4. 必要时进行大规模重构
5. 更新Skill文档

Summary

总结

Key Principles:
  1. Skills are permanent, sessions are temporary
  2. Update skills explicitly - Claude won't auto-update
  3. ALL skills in $CLAUDE_METADATA - No local skills or commands ever
  4. Version control your skills with git in central repo
  5. Share skills across team - Centralization ensures consistency
  6. Regular reviews keep skills valuable
Critical Architectural Rule:
  • NEVER create skills or commands directly in project directories
  • ALWAYS create in $CLAUDE_METADATA and symlink to projects
Even project-specific skills must live in the central repository. This ensures:
  • Single source of truth - No duplicates, no divergence
  • Version control - All skills tracked in one git repo
  • Team sharing - Everyone can discover and use all skills
  • Easy maintenance - Update once, applies everywhere
Remember: Claude is a powerful assistant, but skills are how you make that power consistent, shareable, and permanent. The centralized architecture ensures your team's knowledge remains organized, discoverable, and maintainable. Invest in your skills, and they'll pay dividends for your entire team.
核心原则：
  1. Skill是永久的，会话是临时的
  2. 明确更新Skill - Claude不会自动更新
  3. 所有Skill都存放在$CLAUDE_METADATA中 - 绝对不要使用本地Skill或命令
  4. 对Skill进行版本控制 - 用git在中央仓库中跟踪
  5. 跨团队共享Skill - 集中式存储确保一致性
  6. 定期回顾 - 保持Skill的价值
关键架构规则：
  • 绝对不要直接在项目目录中创建Skill或命令
  • 始终在$CLAUDE_METADATA中创建，再软链接到项目
即使是项目专属的Skill也必须存放在中央仓库中，这可以确保：
  • 唯一可信源 - 没有重复内容，没有版本分歧
  • 版本控制 - 所有Skill都在同一个git仓库中跟踪
  • 团队共享 - 所有人都可以发现和使用所有Skill
  • 易维护 - 只需更新一次，所有地方都生效
提醒： Claude是强大的助手，而Skill是让这种能力保持一致、可共享、可永久留存的方式。集中式架构可以确保团队的知识始终有序、易发现、易维护。在Skill上投入时间，会给整个团队带来丰厚的回报。

Supporting Documentation

辅助文档

This skill includes detailed reference documentation in the same directory:
  • centralized-repository.md - Centralized skill repository setup, migration patterns, team workflow, and directory structure examples
  • version-control-and-sharing.md - Git setup for skills, team collaboration workflows, and four methods for sharing skills (git repo, network drive, copy-based, zip archive)
  • maintenance-and-effectiveness.md - Best practices for skill maintenance, measuring effectiveness, metrics to track, and common pitfalls with solutions
  • advanced-patterns.md - Tiered/conditional/role-based skill patterns and documentation for session interruptions (resume documentation templates)
These files provide deep technical details that complement the core concepts above.
本Skill在同一目录下包含详细的参考文档：
  • centralized-repository.md - 集中式Skill仓库搭建、迁移模式、团队工作流和目录结构示例
  • version-control-and-sharing.md - Skill的Git配置、团队协作工作流，以及四种Skill共享方法（git仓库、网络驱动器、复制式、zip压缩包）
  • maintenance-and-effectiveness.md - Skill维护最佳实践、效果衡量、需要跟踪的指标，以及常见问题和解决方案
  • advanced-patterns.md - 分层/条件/基于角色的Skill模式，以及会话中断相关文档（恢复文档模板）
这些文件提供了补充上述核心概念的深度技术细节。