fdt:update-remote-plugins

中文环境要求

本技能运行在中文环境下，请遵循以下约定：

• 面向用户的回复、注释、提示信息必须使用中文
• AI 内部处理过程可以使用英文
• 所有生成的文件必须使用 UTF-8 编码

---

Update Remote Plugins

Audit and generate per-skill README.md files, sync marketplace.json with plugins directory, update both English and Chinese README files, then commit and push to remote. Finally, sync to local Claude Code plugins directory.

When to Use

• After modifying any skill in plugins/ directory
• To release a new version of the plugin
• To sync English and Chinese documentation
• After adding new skills or updating existing ones
• To regenerate per-skill README.md files from SKILL.md content

Trigger

/fdt:update-remote-plugins

---

Workflow

1. Pull Latest Changes

ALWAYS start by pulling latest changes to avoid conflicts:

git fetch origin
git pull --rebase

If pull fails due to uncommitted changes:

git stash
git pull --rebase
# After resolving any conflicts, restore stash if needed

2. Scan Skills Directory

List all skills in the plugin:

ls -1 plugins/flutter-dev-tools/skills/

For each skill, read its SKILL.md to get name and description.

3. Detect Changes

Check if any file changed since last commit:

git diff HEAD --name-only -- plugins/

If changes detected, determine version bump:

• Bug fix / minor update → patch (+0.0.1): 1.0.0 → 1.0.1
• New skill / feature → minor (+0.1.0): 1.0.0 → 1.1.0
• Breaking change → major (+1.0.0): 1.0.0 → 2.0.0

4. Audit and Generate Skill READMEs

在更新配置文件之前，确保每个 skill 目录都有最新的 README.md。

4a. 识别需要审计的 skill

结合 Step 3 的变更检测结果，确定哪些 skill 需要处理：

# 获取变更的 skill 目录列表
# 路径格式: plugins/flutter-dev-tools/skills/{skill-name}/SKILL.md，skill-name 在第4段
CHANGED_SKILLS=$(git diff HEAD --name-only -- plugins/flutter-dev-tools/skills/ \
  | cut -d'/' -f4 \
  | sort -u)

需要审计的 skill：

• 有变更的 skill — SKILL.md 被修改，README.md 需要重新生成
• 缺少 README.md 的 skill — 无论是否变更，都需创建

4b. 检查每个 skill 目录

扫描所有 skill 目录，检查 README.md 是否存在：

for skill_dir in plugins/flutter-dev-tools/skills/*/; do
  skill_name=$(basename "$skill_dir")
  if [ ! -f "${skill_dir}README.md" ]; then
    echo "MISSING: ${skill_name}/README.md"
  fi
done

4c. 生成或更新 README.md

对每个需要处理的 skill，读取其 SKILL.md 内容，提取以下信息并生成 README.md：

提取规则：

README 字段	SKILL.md 来源
标题	frontmatter 中的 name 字段
一句话描述	H1 标题后的第一段文字（翻译为中文）
功能列表	## When to Use、## 功能概述 或其他功能描述段落（翻译为中文）
用法	## Trigger、## Example Prompts、## 使用方法、## Command Parameters 等段落

README.md 模板：

# {skill-name}

{一句话中文描述}

---

## 功能

{功能列表，每项一行，以 - 开头}

## 用法

{用法示例，保留原始代码块格式}

---

> 本文档由 SKILL.md 自动生成，请勿手动编辑。如需更新，修改 SKILL.md 后运行 `/fdt:update-remote-plugins`。

关键规则：

• SKILL.md 是唯一真相来源，README.md 完全从 SKILL.md 派生
• 所有内容必须使用中文（英文段落需翻译）
• 保持所有 skill 的 README 格式一致
• README.md 末尾必须包含自动生成声明
• 如果 SKILL.md 没有变更且 README.md 已存在，跳过该 skill
• 如果 SKILL.md 有变更但 README.md 内容仍然准确，仍然重新生成以确保一致性

4d. 验证生成结果

确认每个 skill 目录现在都有 README.md：

for skill_dir in plugins/flutter-dev-tools/skills/*/; do
  skill_name=$(basename "$skill_dir")
  if [ ! -f "${skill_dir}README.md" ]; then
    echo "ERROR: ${skill_name}/README.md 仍然缺失！"
  else
    echo "OK: ${skill_name}/README.md"
  fi
done

如有缺失，重新生成。

5. Update Configuration Files

plugin.json - Update version and description in plugins/flutter-dev-tools/.claude-plugin/plugin.json

CRITICAL: plugin.json MUST include skills field:

{
  "name": "flutter-dev-tools",
  "description": "...",
  "version": "1.1.0",
  "author": {...},
  "skills": ["./skills/"]
}

Without skills field, Claude Code will NOT load any skills from the plugin.

marketplace.json - Update version in .claude-plugin/marketplace.json

6. Sync README Files

README.md (Chinese) - Update skills table:

## 包含的 Skills

| Skill | 描述 |
|-------|------|
| `skill-name` | Description from SKILL.md |
...

README_EN.md (English) - Sync with Chinese version:

• Translate any new content to English
• Keep structure identical
• Update skills table
• Update repository structure section

7. Commit and Push (Robust)

Stage and commit changes:

git add .claude-plugin/marketplace.json README.md README_EN.md plugins/flutter-dev-tools/
git commit -m "feat: 更新插件至 v{version} - {变更摘要}"

注意： Commit message 必须使用中文。

Push with retry logic:

# Try push, if fails due to remote changes, pull and retry
git push || {
  git pull --rebase
  # Resolve conflicts if any
  git rebase --continue  # or --abort if needed
  git push
}

8. Sync Local Plugins (CRITICAL)

ALWAYS sync to BOTH cache AND marketplace directories - Claude Code reads from both locations.

# Determine target paths
VERSION=$(cat plugins/flutter-dev-tools/.claude-plugin/plugin.json | grep '"version"' | head -1 | cut -d'"' -f4)

# Cache path (primary)
CACHE_PATH="$HOME/.claude/plugins/cache/flutter-dev-tools/flutter-dev-tools/$VERSION"

# Marketplace path (git clone, NOT manual copy!)
MARKETPLACE_PATH="$HOME/.claude/plugins/marketplaces/flutter-dev-tools"

# === Sync to CACHE directory ===
mkdir -p "$CACHE_PATH/skills" "$CACHE_PATH/.claude-plugin"
cp -r plugins/flutter-dev-tools/skills/* "$CACHE_PATH/skills/"
cp plugins/flutter-dev-tools/.claude-plugin/plugin.json "$CACHE_PATH/.claude-plugin/"
cp README.md README_EN.md "$CACHE_PATH/"
echo "Synced to cache: $CACHE_PATH"

# === Sync to MARKETPLACE directory (git pull, NOT cp!) ===
# CRITICAL: Claude Code requires marketplace to be a git clone.
# If the directory doesn't exist or has no .git, clone it first.
if [ ! -d "$MARKETPLACE_PATH/.git" ]; then
  echo "Marketplace not a git repo, cloning..."
  rm -rf "$MARKETPLACE_PATH"
  git clone [email protected]:adzcsx2/flutter-claude-skill.git "$MARKETPLACE_PATH"
else
  echo "Marketplace is git repo, pulling latest..."
  git -C "$MARKETPLACE_PATH" pull
fi

# Verify
echo "=== Cache skills ==="
ls -1 "$CACHE_PATH/skills/"
echo "=== Marketplace skills ==="
ls -1 "$MARKETPLACE_PATH/plugins/flutter-dev-tools/skills/"

9. Register Plugin (First Install Only)

CRITICAL: Without these registrations, Claude Code will NOT load the plugin.

9a. Add to known_marketplaces.json

Ensure ~/.claude/plugins/known_marketplaces.json has an entry:

{
  "flutter-dev-tools": {
    "source": {
      "source": "git",
      "url": "[email protected]:adzcsx2/flutter-claude-skill.git"
    },
    "installLocation": "/Users/hoyn/.claude/plugins/marketplaces/flutter-dev-tools",
    "lastUpdated": "2026-04-14T00:00:00.000Z"
  }
}

9b. Add to enabledPlugins in settings.json

Ensure ~/.claude/settings.json has the plugin enabled:

{
  "enabledPlugins": {
    "flutter-dev-tools@flutter-dev-tools": true
  }
}

9c. Update installed_plugins.json

Verify ~/.claude/plugins/installed_plugins.json points to correct version:

cat ~/.claude/plugins/installed_plugins.json | grep -A5 "flutter-dev-tools"

If version mismatch, update the file to point to the new version.

---

README Sync Rules

When syncing README.md and README_EN.md:

1. Structure must match - Same sections in same order
2. Skills table - Update both Chinese and English versions
3. New skills - Add to both files with translated description
4. Removed skills - Remove from both files
5. Version number - Update in both files
6. Repository structure - Update to show all skill directories
7. Skill-level README.md - Each skill directory must have a README.md generated from its SKILL.md content, following the standard template

---

Troubleshooting

Issue 1: Push Rejected (Remote Has New Commits)

Symptoms:

! [rejected] main -> main (fetch first)
error: failed to push some refs

Solution:

git stash  # Save any uncommitted changes
git pull --rebase
# Resolve conflicts if any
git rebase --continue
git push
git stash pop  # Restore saved changes

Issue 2: Merge Conflicts During Rebase

Symptoms:

CONFLICT (content): Merge conflict in <file>

Solution:

1. Read the conflicted file
2. Keep both changes (combine HEAD and incoming)
3. Remove conflict markers (<<<<<<<, =======, >>>>>>>)
4. Stage resolved files: git add <file>
5. Continue: git rebase --continue

Issue 3: SSH Connection Failed

Symptoms:

Connection closed by <ip> port 22
fatal: Could not read from remote repository

Solution: Simply retry the push:

git push

Issue 4: New Window Missing Updated Plugin

Cause: Local plugins directory not synced after push

Solution: Run Step 8 (Sync Local Plugins) manually - sync BOTH cache AND marketplace directories.

Issue 5: Stash Conflicts After Rebase

Symptoms:

CONFLICT (content): Merge conflict in <file>
Auto-merging <file>

Solution: If stash conflicts are not critical, drop the stash:

git checkout --theirs <conflicted-file>
git stash drop

Issue 6: Skills Not Loading - Missing skills Field

Symptoms:

• Plugin loads but skills are not available
• /plugin-name:skill-name command not recognized

Root Cause: plugin.json missing "skills": ["./skills/"] field

Solution: Add skills field to plugin.json:

{
  "name": "flutter-dev-tools",
  "version": "1.1.0",
  "skills": ["./skills/"]
}

Then re-sync to local directories (Step 8).

Issue 7: Skills Not Loading - Marketplace Not a Git Repo

Symptoms:

• Plugin files exist in marketplace directory but skills are not available
• New Claude Code window doesn't load the plugin

Root Cause: Claude Code requires the marketplace directory to be a valid git clone (with .git/). Manual cp copies won't work.

Solution: Replace manual copy with git clone:

rm -rf ~/.claude/plugins/marketplaces/flutter-dev-tools
git clone [email protected]:adzcsx2/flutter-claude-skill.git ~/.claude/plugins/marketplaces/flutter-dev-tools

For subsequent updates, use git pull:

git -C ~/.claude/plugins/marketplaces/flutter-dev-tools pull

Issue 8: installed_plugins.json Version Mismatch

Symptoms:

• New Claude Code window loads old version
• installed_plugins.json points to different version than expected

Solution: Update ~/.claude/plugins/installed_plugins.json:

{
  "plugins": {
    "flutter-dev-tools@flutter-dev-tools": [
      {
        "installPath": "/Users/xxx/.claude/plugins/cache/flutter-dev-tools/flutter-dev-tools/1.1.0",
        "version": "1.1.0"
      }
    ]
  }
}

Issue 9: Plugin Marked as Orphaned

Symptoms:

• .orphaned_at file exists in plugin directory
• Plugin not loading despite correct configuration

Solution: Remove the orphaned marker:

rm -f ~/.claude/plugins/cache/flutter-dev-tools/flutter-dev-tools/1.1.0/.orphaned_at

Issue 10: Plugin Not Loading - Missing Registration

Symptoms:

• Plugin files exist in cache and marketplace directories
• plugin.json has skills field
• But plugin still not available in new Claude Code windows

Root Cause: Claude Code requires plugin registration in 3 config files. If any is missing, the plugin won't load.

Solution: Verify and fix all 3 registration points:

# 1. Check enabledPlugins in settings.json
grep "flutter-dev-tools" ~/.claude/settings.json

# 2. Check known_marketplaces.json
grep "flutter-dev-tools" ~/.claude/plugins/known_marketplaces.json

# 3. Check installed_plugins.json
grep "flutter-dev-tools" ~/.claude/plugins/installed_plugins.json

If any is missing, add it. See Step 9 for detailed format.

---

Notes

1. ALWAYS pull first - Avoid conflicts by syncing with remote before starting
2. ALWAYS sync to local - New Claude Code windows need the updated plugin
3. Sync cache via cp, marketplace via git pull - Claude Code reads from both directories，marketplace 必须是 git 仓库
4. plugin.json MUST have skills field - Without it, no skills will load
5. Commit message 使用中文 - 提交到远程的注释必须使用中文
6. Run from the marketplace root directory
7. Ensure git is configured with push access
8. Keep README.md and README_EN.md synchronized
9. Version format: semver (major.minor.patch)
10. Local paths:
    • Cache: ~/.claude/plugins/cache/flutter-dev-tools/flutter-dev-tools/{version}/
    • Marketplace: ~/.claude/plugins/marketplaces/flutter-dev-tools/ (必须是 git clone，不能用 cp 复制)
    • Installed: ~/.claude/plugins/installed_plugins.json
11. If push fails, pull and retry before giving up
12. Clean up old versions to avoid version confusion
13. Each skill directory must have a README.md generated from its SKILL.md content
14. README.md files are auto-generated -- edit SKILL.md instead and re-run this skill
15. 首次安装需要注册 3 个文件 - settings.json (enabledPlugins)、known_marketplaces.json、installed_plugins.json