diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 00000000..b4fdbe29
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,8 @@
+# Copilot Code Review
+
+When performing a code review, respond in Simplified Chinese (简体中文).
+
+- Write all review comments, summaries, and suggestions in 简体中文.
+- Keep code identifiers, file paths, command names, API routes, and package names in their original form (do not translate them).
+- Prefer concrete, actionable feedback over generic praise.
+- Call out regressions, security issues, and missing tests when relevant.
diff --git a/app/controller/skills.js b/app/controller/skills.js
index b040ef31..065b1ece 100644
--- a/app/controller/skills.js
+++ b/app/controller/skills.js
@@ -33,7 +33,13 @@ class SkillsController extends Controller {
     async downloadSkillArchive() {
         const { ctx } = this;
         const { slug } = ctx.query;
-        const { fileName, content } = await ctx.service.skills.getSkillArchive(slug);
+        const {
+            slug: resolvedSlug,
+            fileName,
+            content,
+        } = await ctx.service.skills.getSkillArchive(slug);
+        // Count only on actual zip download (not install-meta sha256 rebuild).
+        await ctx.service.skills.incrementDownloads(resolvedSlug);
         ctx.set('Content-Type', 'application/zip');
         ctx.set('Content-Disposition', `attachment; filename="${encodeURIComponent(fileName)}"`);
         ctx.body = content;
diff --git a/app/controller/skillsRegistry.js b/app/controller/skillsRegistry.js
index 63454f53..169bb4b7 100644
--- a/app/controller/skillsRegistry.js
+++ b/app/controller/skillsRegistry.js
@@ -87,6 +87,8 @@ class SkillsRegistryController extends Controller {
             ctx.body = { error: '技能不存在' };
             return;
         }
+        // Count only on successful zip download (same seam as web controller).
+        await ctx.service.skills.incrementDownloads(result.slug);
         ctx.set('Content-Type', 'application/zip');
         ctx.set(
             'Content-Disposition',
diff --git a/app/model/skills_item.js b/app/model/skills_item.js
index b9b3827a..a9893c0a 100644
--- a/app/model/skills_item.js
+++ b/app/model/skills_item.js
@@ -51,6 +51,12 @@ module.exports = (app) => {
                 allowNull: false,
                 defaultValue: 0,
             },
+            downloads: {
+                type: INTEGER,
+                allowNull: false,
+                defaultValue: 0,
+                comment: 'zip 成功下发次数（Web 下载 + CLI install）',
+            },
             updated_at_remote: {
                 type: DATE,
                 comment: '源仓库文件更新时间',
@@ -119,6 +125,8 @@ module.exports = (app) => {
                 { fields: ['source_id'] },
                 { fields: ['category'] },
                 { fields: ['stars'] },
+                // downloads index is created in ensureSkillsItemDownloadsColumn
+                // after the column exists (sync cannot add index for a missing column).
                 { fields: ['updated_at_remote'] },
             ],
         }
diff --git a/app/service/skills.js b/app/service/skills.js
index 2b84ded1..5c4913b7 100644
--- a/app/service/skills.js
+++ b/app/service/skills.js
@@ -14,6 +14,12 @@ const {
     extractSkillMdDescription,
     resolveMarketCardDescription,
 } = require('../utils/skill-utils');
+const {
+    coerceCount,
+    sumCounts,
+    aggregateCountsByParent,
+    isDuplicateIndexError,
+} = require('../utils/skill-stats');
 const GitHubStarsClient = require('../utils/github-stars');
 const CommandRunner = require('../utils/command-runner');
 
@@ -122,6 +128,7 @@ class SkillsService extends Service {
             await this.ensureSkillsItemVersionColumn();
             await this.ensureSkillsItemPackageColumns();
             await this.ensureSkillsItemContributorColumn();
+            await this.ensureSkillsItemDownloadsColumn();
             this.storageReady = true;
         })();
 
@@ -177,6 +184,53 @@ class SkillsService extends Service {
         });
     }
 
+    async ensureSkillsItemDownloadsColumn() {
+        const queryInterface = this.app.model.getQueryInterface();
+        const table = await queryInterface.describeTable('skills_items');
+        if (!table.downloads) {
+            await queryInterface.addColumn('skills_items', 'downloads', {
+                type: this.app.Sequelize.INTEGER,
+                allowNull: false,
+                defaultValue: 0,
+                comment: 'zip 成功下发次数（Web 下载 + CLI install）',
+            });
+        }
+
+        // Index is not on the model: sync would ADD INDEX before the column exists
+        // on upgraded DBs. Create once the column is present; ignore duplicate index.
+        try {
+            await queryInterface.addIndex('skills_items', ['downloads'], {
+                name: 'idx_skills_downloads',
+            });
+        } catch (error) {
+            if (!isDuplicateIndexError(error)) throw error;
+        }
+    }
+
+    /**
+     * Count one successful zip delivery for a skill slug.
+     * Failures are logged only — download response must not depend on this.
+     */
+    async incrementDownloads(slug) {
+        const value = String(slug || '').trim();
+        if (!value) return;
+
+        try {
+            await this.ensureStorageReady();
+            const { SkillsItem } = this.app.model;
+            await SkillsItem.increment('downloads', {
+                by: 1,
+                where: { slug: value, is_delete: 0 },
+                // Do not bump updated_at — downloads must not reorder "recent" sort.
+                silent: true,
+            });
+        } catch (error) {
+            this.ctx.logger.warn(
+                `[skills] increment downloads failed for ${value}: ${error.message}`
+            );
+        }
+    }
+
     parseJsonArray(value) {
         if (!value) return [];
         if (Array.isArray(value)) return value;
@@ -201,6 +255,7 @@ class SkillsService extends Service {
             tags: skill.tags,
             allowedTools: skill.allowedTools,
             stars: skill.stars,
+            downloads: skill.downloads,
             updatedAt: skill.updatedAt,
             sourceRepo: skill.sourceRepo,
             sourcePath: skill.sourcePath,
@@ -223,7 +278,8 @@ class SkillsService extends Service {
             version: row.version || '',
             tags: this.parseJsonArray(row.tags),
             allowedTools: this.parseJsonArray(row.allowed_tools),
-            stars: Number(row.stars) || 0,
+            stars: coerceCount(row.stars),
+            downloads: coerceCount(row.downloads),
             updatedAt: (
                 row.updated_at ||
                 row.updated_at_remote ||
@@ -283,22 +339,24 @@ class SkillsService extends Service {
         const safePageSize = Math.max(parseInt(pageSize, 10) || 20, 1);
         const { skills, categories } = this.skillCache;
 
-        // Aggregate child stars by parent slug for package star totals
-        const childStarsByParent = new Map();
-        for (const item of skills) {
-            if (item.parentSlug) {
-                const current = childStarsByParent.get(item.parentSlug) || 0;
-                childStarsByParent.set(item.parentSlug, current + (Number(item.stars) || 0));
-            }
-        }
+        const { stars: childStarsByParent, downloads: childDownloadsByParent } =
+            aggregateCountsByParent(skills, {
+                parentKey: 'parentSlug',
+                fields: ['stars', 'downloads'],
+            });
 
         let list = [...skills]
             .filter((item) => !item.parentSlug)
             .map((item) => {
-                if (item.isPackage === 1 && childStarsByParent.has(item.slug)) {
-                    return { ...item, stars: childStarsByParent.get(item.slug) };
+                if (item.isPackage !== 1) return item;
+                const next = { ...item };
+                if (childStarsByParent.has(item.slug)) {
+                    next.stars = childStarsByParent.get(item.slug);
                 }
-                return item;
+                if (childDownloadsByParent.has(item.slug)) {
+                    next.downloads = childDownloadsByParent.get(item.slug);
+                }
+                return next;
             });
         if (keyword) {
             const value = String(keyword).toLowerCase();
@@ -320,6 +378,10 @@ class SkillsService extends Service {
             if (sortBy === 'recent') {
                 return new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime();
             }
+            if (sortBy === 'downloads') {
+                if (b.downloads !== a.downloads) return b.downloads - a.downloads;
+                return new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime();
+            }
             if (b.stars !== a.stars) return b.stars - a.stars;
             return new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime();
         });
@@ -397,10 +459,8 @@ class SkillsService extends Service {
                 ],
             });
             detail.children = children.map((row) => this.toPublicSkill(this.toSkillDto(row)));
-            detail.stars = detail.children.reduce(
-                (sum, child) => sum + (Number(child.stars) || 0),
-                0
-            );
+            detail.stars = sumCounts(detail.children, (child) => child.stars);
+            detail.downloads = sumCounts(detail.children, (child) => child.downloads);
         }
 
         return detail;
@@ -491,7 +551,10 @@ class SkillsService extends Service {
             });
         }
 
+        // Pure zip build — do not count here. getInstallMeta also builds zip for sha256;
+        // counting belongs only on the real download HTTP handler.
         return {
+            slug: skill.slug,
             fileName: `${rootFolder}.zip`,
             content: zip.toBuffer(),
         };
diff --git a/app/service/skillsRegistry.js b/app/service/skillsRegistry.js
index 98dbf92a..47f68eb6 100644
--- a/app/service/skillsRegistry.js
+++ b/app/service/skillsRegistry.js
@@ -4,6 +4,7 @@ const fs = require('fs');
 const ignore = require('ignore');
 const path = require('path');
 const skillUtils = require('../utils/skill-utils');
+const { coerceCount, sumCounts } = require('../utils/skill-stats');
 const skillFingerprint = require('../../contracts/skill-fingerprint');
 const {
     SKILL_CATEGORY_OPTIONS,
@@ -67,7 +68,7 @@ class SkillsRegistryService extends Service {
             newest: { key: 'newest', field: 'updated_at', type: 'date' },
             createdAt: { key: 'newest', field: 'updated_at', type: 'date' },
             updated: { key: 'newest', field: 'updated_at', type: 'date' },
-            downloads: { key: 'stars', field: 'stars', type: 'number' },
+            downloads: { key: 'downloads', field: 'downloads', type: 'number' },
             stars: { key: 'stars', field: 'stars', type: 'number' },
         };
         const sortConfig = sortMap[sort] || sortMap.newest;
@@ -107,7 +108,10 @@ class SkillsRegistryService extends Service {
         return {
             items: items.map((skill) => {
                 const tags = this.parseJsonArray(skill.tags);
-                const stats = { stars: skill.stars || 0, downloads: 0 };
+                const stats = {
+                    stars: coerceCount(skill.stars),
+                    downloads: coerceCount(skill.downloads),
+                };
                 const item = {
                     slug: skill.slug,
                     displayName: skill.name,
@@ -161,7 +165,10 @@ class SkillsRegistryService extends Service {
 
         const version = skill.version || '';
         const tags = this.parseJsonArray(skill.tags);
-        const stats = { stars: skill.stars || 0, downloads: 0 };
+        const stats = {
+            stars: coerceCount(skill.stars),
+            downloads: coerceCount(skill.downloads),
+        };
         const createdAt = skill.created_at ? new Date(skill.created_at).getTime() : 0;
         const updatedAt = skill.updated_at ? new Date(skill.updated_at).getTime() : 0;
         let fingerprint = null;
@@ -210,12 +217,23 @@ class SkillsRegistryService extends Service {
                 summary: child.description || null,
                 version: child.version || null,
                 tags: this.parseJsonArray(child.tags),
-                stats: { stars: child.stars || 0, downloads: 0 },
+                stats: {
+                    stars: coerceCount(child.stars),
+                    downloads: coerceCount(child.downloads),
+                },
                 createdAt: child.created_at ? new Date(child.created_at).getTime() : 0,
                 updatedAt: child.updated_at ? new Date(child.updated_at).getTime() : 0,
                 isPackage: false,
                 parentSlug: child.parent_slug,
             }));
+            detail.skill.stats.downloads = sumCounts(
+                detail.skill.children,
+                (child) => child.stats.downloads
+            );
+            detail.skill.stats.stars = sumCounts(
+                detail.skill.children,
+                (child) => child.stats.stars
+            );
         }
 
         return detail;
@@ -360,6 +378,7 @@ class SkillsRegistryService extends Service {
 
         const version = skill.version || 'latest';
         return {
+            slug: skill.slug,
             fileName: `${slug}-${version}.zip`,
             content: zip.toBuffer(),
         };
@@ -759,7 +778,7 @@ class SkillsRegistryService extends Service {
     encodeListCursor(skill, sortConfig) {
         const rawValue = skill[sortConfig.field];
         const value =
-            sortConfig.type === 'date' ? new Date(rawValue).getTime() : Number(rawValue) || 0;
+            sortConfig.type === 'date' ? new Date(rawValue).getTime() : coerceCount(rawValue);
         return Buffer.from(
             JSON.stringify({
                 sort: sortConfig.key,
diff --git a/app/utils/skill-stats.js b/app/utils/skill-stats.js
new file mode 100644
index 00000000..37adbb14
--- /dev/null
+++ b/app/utils/skill-stats.js
@@ -0,0 +1,48 @@
+function coerceCount(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) return 0;
+    return Math.floor(n);
+}
+
+function sumCounts(items, getCount) {
+    let sum = 0;
+    for (const item of items || []) {
+        sum += coerceCount(getCount(item));
+    }
+    return sum;
+}
+
+/**
+ * @param {Array<object>} items
+ * @param {{ parentKey: string, fields: string[] }} opts
+ * @returns {Record<string, Map<string, number>>}
+ */
+function aggregateCountsByParent(items, { parentKey, fields }) {
+    const maps = {};
+    for (const field of fields) {
+        maps[field] = new Map();
+    }
+    for (const item of items || []) {
+        const parent = item[parentKey];
+        if (parent == null || parent === '') continue;
+        for (const field of fields) {
+            const current = maps[field].get(parent) || 0;
+            maps[field].set(parent, current + coerceCount(item[field]));
+        }
+    }
+    return maps;
+}
+
+function isDuplicateIndexError(error) {
+    const code = error?.original?.code || error?.parent?.code || error?.code;
+    if (code === 'ER_DUP_KEYNAME') return true;
+    const errno = error?.original?.errno ?? error?.parent?.errno ?? error?.errno;
+    return errno === 1061;
+}
+
+module.exports = {
+    coerceCount,
+    sumCounts,
+    aggregateCountsByParent,
+    isDuplicateIndexError,
+};
diff --git a/app/web/components/skills/SkillCard.tsx b/app/web/components/skills/SkillCard.tsx
index 9614c2fb..ed625f05 100644
--- a/app/web/components/skills/SkillCard.tsx
+++ b/app/web/components/skills/SkillCard.tsx
@@ -1,6 +1,12 @@
 import React from 'react';
-import { FileTextOutlined, FolderOutlined, StarOutlined } from '@ant-design/icons';
+import {
+    DownloadOutlined,
+    FileTextOutlined,
+    FolderOutlined,
+    StarOutlined,
+} from '@ant-design/icons';
 import { Card, Checkbox, Tag } from 'antd';
+import moment from 'moment';
 
 import type { SkillItem } from '@/pages/skills/types';
 import './style.scss';
@@ -64,8 +70,11 @@ export const SkillCard: React.FC<SkillCardProps> = ({
                                     技能包
                                 </Tag>
                             )}
-                            <span className="stars-badge">
-                                <StarOutlined /> {skill.stars || 0}
+                            <span className="stars-badge" title="Stars">
+                                <StarOutlined /> {skill.stars}
+                            </span>
+                            <span className="downloads-badge" title="下载量">
+                                <DownloadOutlined /> {skill.downloads}
                             </span>
                             {onEdit && (
                                 <button
@@ -126,7 +135,7 @@ export const SkillCard: React.FC<SkillCardProps> = ({
                         <span className="meta-label">更新</span>
                         <span className="meta-value">
                             {skill.updatedAt
-                                ? new Date(skill.updatedAt).toLocaleDateString('zh-CN')
+                                ? moment(skill.updatedAt).format('YYYY-MM-DD HH:mm:ss')
                                 : '-'}
                         </span>
                     </span>
diff --git a/app/web/components/skills/style.scss b/app/web/components/skills/style.scss
index 8741ed3f..e1f7142a 100644
--- a/app/web/components/skills/style.scss
+++ b/app/web/components/skills/style.scss
@@ -114,7 +114,8 @@
             height: 20px;
             line-height: 18px;
         }
-        .stars-badge {
+        .stars-badge,
+        .downloads-badge {
             display: inline-flex;
             align-items: center;
             gap: 4px;
diff --git a/app/web/pages/skills/detail/SkillSummaryModalContent.tsx b/app/web/pages/skills/detail/SkillSummaryModalContent.tsx
index 6deb4ae3..1cbde49c 100644
--- a/app/web/pages/skills/detail/SkillSummaryModalContent.tsx
+++ b/app/web/pages/skills/detail/SkillSummaryModalContent.tsx
@@ -1,6 +1,7 @@
 import React, { useEffect, useMemo, useState } from 'react';
 import { CopyOutlined, LinkOutlined, ShareAltOutlined, StarOutlined } from '@ant-design/icons';
 import { Button, Empty, Spin, Tabs, Tag, Typography } from 'antd';
+import moment from 'moment';
 
 import { API } from '@/api';
 import { copyToClipboard } from '@/utils/copyUtils';
@@ -187,7 +188,7 @@ const SkillSummaryModalContent: React.FC<SkillSummaryModalContentProps> = ({ slu
 
     const detailTags = (detail.tags || []).filter((tag) => tag && tag !== detail.category);
     const detailUpdatedAt = detail.updatedAt
-        ? new Date(detail.updatedAt).toLocaleString('zh-CN')
+        ? moment(detail.updatedAt).format('YYYY-MM-DD HH:mm:ss')
         : '-';
     const agentFallbackInstruction = [
         '当前 skill 不支持 doraemon-skills 直接安装。',
@@ -201,6 +202,10 @@ const SkillSummaryModalContent: React.FC<SkillSummaryModalContentProps> = ({ slu
             value: String(detail.stars || 0),
             className: 'is-accent',
         },
+        {
+            label: '下载',
+            value: String(detail.downloads || 0),
+        },
         {
             label: '最近更新',
             value: detailUpdatedAt,
diff --git a/app/web/pages/skills/detail/components/SkillDetailHero.tsx b/app/web/pages/skills/detail/components/SkillDetailHero.tsx
index 4e42e1e4..5a8377c5 100644
--- a/app/web/pages/skills/detail/components/SkillDetailHero.tsx
+++ b/app/web/pages/skills/detail/components/SkillDetailHero.tsx
@@ -35,6 +35,10 @@ export const SkillDetailHero: React.FC<SkillDetailHeroProps> = ({
             label: '分类',
             value: detail.category || '通用',
         },
+        {
+            label: '下载',
+            value: String(detail.downloads || 0),
+        },
         {
             label: '最近更新',
             value: formatCompactDate(detail.updatedAt),
diff --git a/app/web/pages/skills/index.tsx b/app/web/pages/skills/index.tsx
index 7169a59f..098c1540 100644
--- a/app/web/pages/skills/index.tsx
+++ b/app/web/pages/skills/index.tsx
@@ -27,7 +27,9 @@ import {
 import debounce from 'lodash/debounce';
 
 import { API } from '@/api';
+import helpIcon from '@/asset/images/help-icon.png';
 import { SkillCard } from '@/components/skills/SkillCard';
+import config from '../../../../env.json';
 import { SkillItem, SkillListResponse } from './types';
 import './style.scss';
 
@@ -52,7 +54,11 @@ const INITIAL_QUERY = {
     pageSize: 12,
 };
 
-const SkillsMarket: React.FC<any> = ({ history }) => {
+interface SkillsMarketProps {
+    history: { push: (path: string) => void };
+}
+
+const SkillsMarket: React.FC<SkillsMarketProps> = ({ history }) => {
     const [loading, setLoading] = useState(false);
     const [skills, setSkills] = useState<SkillItem[]>([]);
     const [categories, setCategories] = useState<string[]>([]);
@@ -105,6 +111,9 @@ const SkillsMarket: React.FC<any> = ({ history }) => {
     const updateQueryAndFetch = (patch: Partial<typeof query>) => {
         const next = { ...queryRef.current, ...patch };
         setQuery(next);
+        if (Object.prototype.hasOwnProperty.call(patch, 'keyword')) {
+            setKeywordInput(String(patch.keyword ?? ''));
+        }
         setSelectedSlugs(new Set());
         fetchSkills(next);
     };
@@ -302,6 +311,12 @@ const SkillsMarket: React.FC<any> = ({ history }) => {
         });
     };
 
+    const handleHelpIcon = () => {
+        if (config.skillsHelpDocUrl) {
+            window.open(config.skillsHelpDocUrl, '_blank', 'noopener,noreferrer');
+        }
+    };
+
     return (
         <div className="page-skills">
             <div className="skills-header">
@@ -311,6 +326,16 @@ const SkillsMarket: React.FC<any> = ({ history }) => {
                 </div>
             </div>
 
+            {config.skillsHelpDocUrl ? (
+                <img
+                    className="help-icon"
+                    src={helpIcon}
+                    onClick={handleHelpIcon}
+                    alt="帮助文档"
+                    title="Skills Hub 帮助文档"
+                />
+            ) : null}
+
             <div className="search-filter-row">
                 <Search
                     allowClear
@@ -351,6 +376,7 @@ const SkillsMarket: React.FC<any> = ({ history }) => {
                         onChange={(value) => updateQueryAndFetch({ sortBy: value, pageNum: 1 })}
                     >
                         <Option value="stars">按 Stars 排序</Option>
+                        <Option value="downloads">按下载量排序</Option>
                         <Option value="recent">按最近更新</Option>
                     </Select>
                     <Select
diff --git a/app/web/pages/skills/style.scss b/app/web/pages/skills/style.scss
index 4c03e046..bb799178 100644
--- a/app/web/pages/skills/style.scss
+++ b/app/web/pages/skills/style.scss
@@ -73,6 +73,19 @@
     .skills-grid {
         flex-shrink: 0;
     }
+    .help-icon {
+        width: 60px;
+        height: 60px;
+        padding: 12px;
+        border-radius: 50%;
+        background-color: #FFF;
+        box-shadow: 0 4px 8px rgba(0, 0, 0, 0.28);
+        cursor: pointer;
+        position: fixed;
+        bottom: 120px;
+        right: 60px;
+        z-index: 10;
+    }
     .pagination-wrap {
         display: flex;
         justify-content: flex-end;
diff --git a/app/web/pages/skills/types.ts b/app/web/pages/skills/types.ts
index 1c26b1d8..0f947999 100644
--- a/app/web/pages/skills/types.ts
+++ b/app/web/pages/skills/types.ts
@@ -8,6 +8,7 @@ export interface SkillItem {
     tags: string[];
     allowedTools: string[];
     stars: number;
+    downloads: number;
     updatedAt: string;
     sourceRepo: string;
     sourcePath: string;
diff --git a/docs/docsify/_sidebar.md b/docs/docsify/_sidebar.md
index d444366b..4d56c526 100644
--- a/docs/docsify/_sidebar.md
+++ b/docs/docsify/_sidebar.md
@@ -15,5 +15,6 @@
   + [Remote Hosts](zh-cn/guide/RemoteHosts)
   + [文章订阅](zh-cn/guide/文章订阅)
   + [意见反馈](zh-cn/guide/意见反馈)
+  + [Skills Hub](zh-cn/guide/dt-skill)
 + [贡献指南](zh-cn/other/贡献者文档)
 + [ChangeLog](zh-cn/other/CHANGELOG)
diff --git a/docs/docsify/imgs/dt-skill-install.jpg b/docs/docsify/imgs/dt-skill-install.jpg
new file mode 100644
index 00000000..2e088a41
Binary files /dev/null and b/docs/docsify/imgs/dt-skill-install.jpg differ
diff --git a/docs/docsify/imgs/dt-skill-upload.jpg b/docs/docsify/imgs/dt-skill-upload.jpg
new file mode 100644
index 00000000..19c42ff5
Binary files /dev/null and b/docs/docsify/imgs/dt-skill-upload.jpg differ
diff --git a/docs/docsify/zh-cn/_sidebar.md b/docs/docsify/zh-cn/_sidebar.md
index d444366b..4d56c526 100644
--- a/docs/docsify/zh-cn/_sidebar.md
+++ b/docs/docsify/zh-cn/_sidebar.md
@@ -15,5 +15,6 @@
   + [Remote Hosts](zh-cn/guide/RemoteHosts)
   + [文章订阅](zh-cn/guide/文章订阅)
   + [意见反馈](zh-cn/guide/意见反馈)
+  + [Skills Hub](zh-cn/guide/dt-skill)
 + [贡献指南](zh-cn/other/贡献者文档)
 + [ChangeLog](zh-cn/other/CHANGELOG)
diff --git a/docs/docsify/zh-cn/guide/dt-skill.md b/docs/docsify/zh-cn/guide/dt-skill.md
new file mode 100644
index 00000000..cc9a01f3
--- /dev/null
+++ b/docs/docsify/zh-cn/guide/dt-skill.md
@@ -0,0 +1,162 @@
+# Skills Hub（dt-skill）
+
+Skills Hub 是 Doraemon 的 **Agent Skills 市场**能力：Web 端可浏览、下载；命令行 **`dt-skill`** 负责安装、更新、卸载本机 skill，以及把本地 skill **上传（upload）** 到 Registry。
+
+- **Node.js 18 及以上**（与 Doraemon / `dt-skill` package `engines` 对齐，推荐 18.x）
+- 默认 Registry：`http://172.16.100.225:7001`
+- 更多命令与参数：`npx dt-skill -h` / `npx dt-skill <command> -h`
+
+## 快速开始
+
+```bash
+# 无需全局安装
+npx dt-skill --help
+
+# 或全局安装
+npm install -g dt-skill
+```
+
+指定 Registry（本地 Doraemon）：
+
+```bash
+export DT_SKILL_REGISTRY=http://127.0.0.1:7001
+# 或
+npx dt-skill --registry http://127.0.0.1:7001 list
+```
+
+| 场景 | 命令 |
+|------|------|
+| 安装 | `npx dt-skill install <slug>` |
+| 列表 | `npx dt-skill list` |
+| 更新 | `npx dt-skill update` |
+| 本机卸载 | `npx dt-skill uninstall <slug>` |
+| 上传发布 | `npx dt-skill upload <本地目录>` |
+
+---
+
+## 安装 skill（install）
+
+从 Skills 市场安装到本机，并链接到你使用的 Agent。
+
+```bash
+npx dt-skill install zentao-api
+```
+
+安装过程中会引导选择：
+
+* **安装到哪些 Agent**  
+  - Universal（`.agents/skills`）始终包含  
+  - 可搜索、多选更多 Agent（↑↓ 移动，空格选择，回车确认）
+
+* **安装范围**  
+  - Project：当前项目  
+  - Global：本机全局（`~/.agents/skills`）
+
+![dt-skill-install.jpg](../../imgs/dt-skill-install.jpg)
+
+安装完成后，对应 Agent 即可使用该 skill。
+
+---
+
+## 上传 skill（upload）
+
+开发者将本地 skill 目录发布到 Doraemon Registry，其他人即可 `install`。
+
+```bash
+npx dt-skill upload .agents/skills/ask-matt
+# 与 publish 等价
+npx dt-skill publish .agents/skills/ask-matt
+```
+
+常见交互：
+
+* 自动读取 **contributor**（如 git `user.name`）
+* **选择 skill 分类**（通用、前端、后端、数据与 AI、运维与系统、工程效率、安全、其他等）
+
+![dt-skill-upload.jpg](../../imgs/dt-skill-upload.jpg)
+
+同 slug 再次上传时，以**内容指纹**判断是否有实质变更。更多参数见：
+
+```bash
+npx dt-skill upload -h
+```
+
+---
+
+## 更新 skill（update）
+
+从 Doraemon Registry 获取最新内容并更新本机已安装 skill（按内容指纹对比，有变化再更新）。
+
+```bash
+# 交互选择更新范围：Project / Global / Both
+npx dt-skill update
+```
+
+```bash
+# 只更新全局
+npx dt-skill update -g
+
+# 只更新项目
+npx dt-skill update -p
+
+# 更新指定 skill
+npx dt-skill update zentao-api
+```
+
+适合日常同步市场最新版。
+
+---
+
+## 卸载 skill（uninstall）
+
+从本机移除已安装 skill（本地目录、lock 与 Agent 链接）。**不影响**市场上的发布。
+
+```bash
+npx dt-skill uninstall zentao-api
+npx dt-skill uninstall zentao-api --yes
+
+# 若装在全局
+npx dt-skill uninstall zentao-api --global --yes
+```
+
+| 命令 | 作用 |
+|------|------|
+| `uninstall` | 本机删除 |
+| `delete` | 市场软删（可 `undelete` 恢复），详见 `npx dt-skill delete -h` |
+
+---
+
+## 列表（list）
+
+```bash
+npx dt-skill list
+npx dt-skill --global list
+```
+
+---
+
+## 项目 vs 全局
+
+| 范围 | 路径示意 | 说明 |
+|------|----------|------|
+| Project | `<仓库>/.agents/skills` | 跟仓库走 |
+| Global | `~/.agents/skills` | 本机跨项目 |
+
+安装可交互选择或使用 `--global`；更新可用 `-g` / `-p` 或交互三选。
+
+---
+
+## 更多能力
+
+```bash
+npx dt-skill -h
+```
+
+其它常用命令：`search`、`explore`、`inspect`、`pin` / `unpin`、`delete` / `undelete` 等。
+
+## 与 Web 的关系
+
+* **Web**（如 `http://172.16.100.225:7001/page/skills`）：浏览、搜索、详情  
+* **dt-skill CLI**：工程化安装 / 更新 / 发布  
+
+两者共用同一 Doraemon Registry。
diff --git a/dt-skill/package.json b/dt-skill/package.json
index 305a1978..2abb2164 100644
--- a/dt-skill/package.json
+++ b/dt-skill/package.json
@@ -1,6 +1,6 @@
 {
     "name": "dt-skill",
-    "version": "0.18.6",
+    "version": "0.18.7",
     "description": "dt-skill CLI — install, update, search, and publish agent skills.",
     "homepage": "https://github.com/DTStack/doraemon/tree/master/dt-skill",
     "bugs": {
diff --git a/dt-skill/src/cli.ts b/dt-skill/src/cli.ts
index b3419178..2c24f1b3 100644
--- a/dt-skill/src/cli.ts
+++ b/dt-skill/src/cli.ts
@@ -54,7 +54,10 @@ const program = new Command()
         collectAgent,
         []
     )
-    .option('--global', 'Install skills to the global canonical directory (~/.agents/skills)')
+    .option(
+        '--global',
+        'Use global scope (~/.agents/skills + lock). Required for update/uninstall of global installs; install may also prompt Project vs Global without this flag'
+    )
     .option('--copy', 'Copy files into each agent dir instead of symlinking')
     .option('-y, --yes', 'Skip interactive prompts')
     .option('--no-input', 'Disable prompts')
@@ -215,9 +218,25 @@ registerCommand(program, ['update'])
     .option('--all', 'Update all installed skills (same as bare update)')
     .option('--version <version>', 'Update to specific version (single slug only, legacy)')
     .option('--force', 'Overwrite when local files do not match registry content')
+    .option('-g, --global', 'Update global skills only (~/.agents)')
+    .option('-p, --project', 'Update project skills only')
     .action(async (slug, options) => {
         const opts = await resolveGlobalOpts();
-        await cmdUpdate(opts, slug, options, isInputAllowed());
+        const programOpts = program.opts<{ global?: boolean; yes?: boolean }>();
+        await cmdUpdate(
+            opts,
+            slug,
+            {
+                all: options.all,
+                version: options.version,
+                force: options.force,
+                // Prefer update-local -g; fall back to program --global
+                global: Boolean(options.global ?? programOpts.global),
+                project: Boolean(options.project),
+                yes: Boolean(programOpts.yes) || !isInputAllowed(),
+            },
+            isInputAllowed()
+        );
     });
 
 registerCommand(program, ['uninstall'])
diff --git a/dt-skill/src/cli/commands/skills.test.ts b/dt-skill/src/cli/commands/skills.test.ts
index 2bc630f7..efd5dd7f 100644
--- a/dt-skill/src/cli/commands/skills.test.ts
+++ b/dt-skill/src/cli/commands/skills.test.ts
@@ -12,6 +12,8 @@ import {
 import * as lockStore from '../../lockfile.js';
 import { ApiRoutes } from '../../schema/index.js';
 import * as skillStore from '../../skills.js';
+import type { UpdateScopeChoice } from '../ui.js';
+import type { UpdateScopeOptions } from './update.js';
 
 const fsMocks = vi.hoisted(() => ({
     mkdir: vi.fn(),
@@ -46,12 +48,16 @@ const mockIsInteractive = vi.fn(() => false);
 const mockPromptConfirm = vi.fn(async () => false);
 vi.mock('../../http.js', () => httpMocks.moduleFactory());
 vi.mock('../registry.js', () => registryMocks.moduleFactory());
+
+const mockSelectUpdateScope = vi.fn(async (): Promise<UpdateScopeChoice> => 'project');
 vi.mock('../ui.js', () => ({
     createSpinner: vi.fn(() => mockSpinner),
     fail: (message: string) => uiMocks.fail(message),
     formatError: (error: unknown) => (error instanceof Error ? error.message : String(error)),
     isInteractive: mockIsInteractive,
     promptConfirm: mockPromptConfirm,
+    selectScope: vi.fn(async () => false),
+    selectUpdateScope: (...args: unknown[]) => mockSelectUpdateScope(...args),
 }));
 
 const extractZipToDirMock = vi.spyOn(skillStore, 'extractZipToDir');
@@ -79,6 +85,7 @@ const {
     cmdUpdate,
     formatExploreLine,
 } = await import('./skills.js');
+const { resolveUpdateScope, hasProjectSkills } = await import('./update.js');
 const { extractZipToDir, hashSkillFiles, listTextFiles, readSkillOrigin, writeSkillOrigin } =
     skillStore;
 const { readLockfile, writeLockfile } = lockStore;
@@ -103,6 +110,8 @@ beforeEach(() => {
     readSkillOriginMock.mockResolvedValue(null);
     writeLockfileMock.mockResolvedValue(undefined);
     writeSkillOriginMock.mockResolvedValue(undefined);
+    mockIsInteractive.mockReturnValue(false);
+    mockSelectUpdateScope.mockResolvedValue('project');
 });
 
 afterEach(() => {
@@ -275,7 +284,92 @@ describe('cmdSearch', () => {
     });
 });
 
+describe('resolveUpdateScope (vercel-aligned)', () => {
+    it('named skill without flags resolves to both', async () => {
+        const scope = await resolveUpdateScope(
+            {},
+            { inputAllowed: true, projectWorkdir: '/work/.agents', hasSkillNames: true }
+        );
+        expect(scope).toBe('both');
+        expect(mockSelectUpdateScope).not.toHaveBeenCalled();
+    });
+
+    it('-g only resolves to global', async () => {
+        const scope = await resolveUpdateScope(
+            { global: true },
+            { inputAllowed: true, projectWorkdir: '/work/.agents', hasSkillNames: false }
+        );
+        expect(scope).toBe('global');
+    });
+
+    it('-p only resolves to project', async () => {
+        const scope = await resolveUpdateScope(
+            { project: true },
+            { inputAllowed: true, projectWorkdir: '/work/.agents', hasSkillNames: false }
+        );
+        expect(scope).toBe('project');
+    });
+
+    it('-g and -p resolve to both', async () => {
+        const scope = await resolveUpdateScope(
+            { global: true, project: true },
+            { inputAllowed: false, projectWorkdir: '/work/.agents', hasSkillNames: false }
+        );
+        expect(scope).toBe('both');
+    });
+
+    it('non-interactive uses hasProjectSkills (no lock → global)', async () => {
+        vi.mocked(stat).mockRejectedValue(new Error('missing'));
+        const scope = await resolveUpdateScope(
+            { yes: true },
+            { inputAllowed: true, projectWorkdir: '/work/.agents', hasSkillNames: false }
+        );
+        expect(scope).toBe('global');
+    });
+
+    it('non-interactive with lock file → project', async () => {
+        vi.mocked(stat).mockImplementation(async (path: string) => {
+            if (String(path).includes('lock.json')) {
+                return {} as Awaited<ReturnType<typeof stat>>;
+            }
+            throw new Error('missing');
+        });
+        const scope = await resolveUpdateScope(
+            { yes: true },
+            { inputAllowed: true, projectWorkdir: '/work/.agents', hasSkillNames: false }
+        );
+        expect(scope).toBe('project');
+    });
+
+    it('interactive bare update calls selectUpdateScope', async () => {
+        mockIsInteractive.mockReturnValue(true);
+        mockSelectUpdateScope.mockResolvedValueOnce('both');
+        const scope = await resolveUpdateScope(
+            {},
+            { inputAllowed: true, projectWorkdir: '/work/.agents', hasSkillNames: false }
+        );
+        expect(scope).toBe('both');
+        expect(mockSelectUpdateScope).toHaveBeenCalled();
+        mockIsInteractive.mockReturnValue(false);
+    });
+});
+
+describe('hasProjectSkills', () => {
+    it('is true when lock.json exists', async () => {
+        vi.mocked(stat).mockImplementation(async (path: string) => {
+            if (String(path).endsWith('lock.json')) {
+                return {} as Awaited<ReturnType<typeof stat>>;
+            }
+            throw new Error('missing');
+        });
+        await expect(hasProjectSkills('/work/.agents')).resolves.toBe(true);
+    });
+});
+
 describe('cmdUpdate', () => {
+    /** Force project scope so tests use makeOpts().workdir without interactive prompt. */
+    const projectYes: UpdateScopeOptions = { project: true, yes: true };
+
     it('fails when directly updating a pinned skill', async () => {
         vi.mocked(readLockfile).mockResolvedValue({
             version: 1,
@@ -284,9 +378,9 @@ describe('cmdUpdate', () => {
             },
         });
 
-        await expect(cmdUpdate(makeOpts(), 'demo', { force: true }, false)).rejects.toThrow(
-            /is pinned/i
-        );
+        await expect(
+            cmdUpdate(makeOpts(), 'demo', { force: true, ...projectYes }, false)
+        ).rejects.toThrow(/is pinned/i);
 
         expect(mockApiRequest).not.toHaveBeenCalled();
         expect(mockDownloadZip).not.toHaveBeenCalled();
@@ -303,9 +397,9 @@ describe('cmdUpdate', () => {
         vi.mocked(listTextFiles).mockResolvedValue([]);
         vi.mocked(stat).mockResolvedValue({} as Awaited<ReturnType<typeof stat>>);
 
-        await expect(cmdUpdate(makeOpts(), 'demo', { force: true }, false)).rejects.toThrow(
-            /Failed to update 1 skill|download failed/
-        );
+        await expect(
+            cmdUpdate(makeOpts(), 'demo', { force: true, ...projectYes }, false)
+        ).rejects.toThrow(/Failed to update 1 skill|download failed/);
 
         expect(rm).not.toHaveBeenCalledWith('/work/.agents/skills/demo', {
             recursive: true,
@@ -326,9 +420,9 @@ describe('cmdUpdate', () => {
         vi.mocked(stat).mockResolvedValue({} as Awaited<ReturnType<typeof stat>>);
         vi.mocked(extractZipToDir).mockRejectedValue(new Error('extract failed'));
 
-        await expect(cmdUpdate(makeOpts(), 'demo', { force: true }, false)).rejects.toThrow(
-            /Failed to update 1 skill|extract failed/
-        );
+        await expect(
+            cmdUpdate(makeOpts(), 'demo', { force: true, ...projectYes }, false)
+        ).rejects.toThrow(/Failed to update 1 skill|extract failed/);
 
         expect(renameMock).not.toHaveBeenCalled();
         expect(rm).not.toHaveBeenCalledWith('/work/.agents/skills/demo', {
@@ -359,7 +453,7 @@ describe('cmdUpdate', () => {
         vi.mocked(stat).mockRejectedValue(new Error('missing'));
         vi.mocked(rm).mockResolvedValue();
 
-        await cmdUpdate(makeOpts(), undefined, { all: true }, false);
+        await cmdUpdate(makeOpts(), undefined, { all: true, ...projectYes }, false);
 
         expect(mockApiRequest).toHaveBeenCalledTimes(1);
         const [, args] = mockApiRequest.mock.calls[0] ?? [];
@@ -402,7 +496,7 @@ describe('cmdUpdate', () => {
         vi.mocked(rm).mockResolvedValue();
 
         // bare update (no slug, no --all)
-        await cmdUpdate(makeOpts(), undefined, {}, false);
+        await cmdUpdate(makeOpts(), undefined, { ...projectYes }, false);
 
         expect(mockApiRequest).toHaveBeenCalledTimes(1);
         const [, args] = mockApiRequest.mock.calls[0] ?? [];
@@ -440,7 +534,7 @@ describe('cmdUpdate', () => {
         vi.mocked(hashSkillFiles).mockReturnValue({ fingerprint: sharedFp, files: [] });
         vi.mocked(stat).mockResolvedValue({} as unknown as Awaited<ReturnType<typeof stat>>);
 
-        await cmdUpdate(makeOpts(), 'demo', {}, false);
+        await cmdUpdate(makeOpts(), 'demo', { ...projectYes }, false);
 
         expect(mockDownloadZip).not.toHaveBeenCalled();
         expect(writeLockfile).not.toHaveBeenCalled();
@@ -481,9 +575,9 @@ describe('cmdUpdate', () => {
         vi.mocked(stat).mockRejectedValue(new Error('missing'));
         vi.mocked(rm).mockResolvedValue();
 
-        await expect(cmdUpdate(makeOpts(), undefined, { all: true }, false)).rejects.toThrow(
-            /Failed to update 1 skill/
-        );
+        await expect(
+            cmdUpdate(makeOpts(), undefined, { all: true, ...projectYes }, false)
+        ).rejects.toThrow(/Failed to update 1 skill/);
 
         expect(mockDownloadZip).toHaveBeenCalledTimes(2);
         expect(mockLog).toHaveBeenCalledWith(
@@ -509,7 +603,7 @@ describe('cmdUpdate', () => {
         vi.mocked(stat).mockRejectedValue(new Error('missing'));
         vi.mocked(rm).mockResolvedValue();
 
-        await cmdUpdate(makeOpts(), 'demo', {}, false);
+        await cmdUpdate(makeOpts(), 'demo', { ...projectYes }, false);
 
         const [, args] = mockApiRequest.mock.calls[0] ?? [];
         expect(args?.path).toBe(`${ApiRoutes.skills}/${encodeURIComponent('demo')}`);
@@ -547,7 +641,7 @@ describe('cmdUpdate', () => {
         vi.mocked(stat).mockResolvedValue({} as unknown as Awaited<ReturnType<typeof stat>>);
         vi.mocked(rm).mockResolvedValue();
 
-        await cmdUpdate(makeOpts(), 'demo', {}, false);
+        await cmdUpdate(makeOpts(), 'demo', { ...projectYes }, false);
 
         expect(mockApiRequest).toHaveBeenCalledTimes(1);
         expect(mockDownloadZip).toHaveBeenCalledWith(
diff --git a/dt-skill/src/cli/commands/update.ts b/dt-skill/src/cli/commands/update.ts
index 2f9ea1c5..c461c766 100644
--- a/dt-skill/src/cli/commands/update.ts
+++ b/dt-skill/src/cli/commands/update.ts
@@ -1,5 +1,6 @@
-import { rm } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readdir, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
 import semver from 'semver';
 
 import { apiRequest, downloadZip } from '../../http.js';
@@ -18,7 +19,15 @@ import { hashSkillFiles, listTextFiles, readSkillOrigin, writeSkillOrigin } from
 import { getRegistry } from '../registry.js';
 import { decideSkillSync, remoteCurrentFromDetail } from '../skillSync.js';
 import type { GlobalOpts } from '../types.js';
-import { createSpinner, fail, formatError, isInteractive, promptConfirm } from '../ui.js';
+import {
+    createSpinner,
+    fail,
+    formatError,
+    isInteractive,
+    promptConfirm,
+    selectUpdateScope,
+    type UpdateScopeChoice,
+} from '../ui.js';
 import {
     fileExists,
     isSafeSkillSlug,
@@ -27,14 +36,112 @@ import {
     replaceSkillDirectory,
 } from './skillHelpers.js';
 
+export type UpdateScopeOptions = {
+    all?: boolean;
+    version?: string;
+    force?: boolean;
+    /** -g / --global */
+    global?: boolean;
+    /** -p / --project */
+    project?: boolean;
+    /** -y or non-interactive: skip scope prompt */
+    yes?: boolean;
+};
+
+type AgentsRoot = { workdir: string; dir: string };
+
+type ScopeRoots = {
+    project: AgentsRoot;
+    global: AgentsRoot;
+};
+
+/**
+ * Whether the project domain looks occupied (vercel hasProjectSkills spirit).
+ * true if project lock file exists OR any skills dir has a SKILL.md child.
+ */
+export async function hasProjectSkills(projectWorkdir: string): Promise<boolean> {
+    const lockPath = join(projectWorkdir, '.dt-skill', 'lock.json');
+    if (await fileExists(lockPath)) return true;
+
+    const skillsDir = join(projectWorkdir, 'skills');
+    try {
+        const entries = await readdir(skillsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            if (await fileExists(join(skillsDir, entry.name, 'SKILL.md'))) {
+                return true;
+            }
+        }
+    } catch {
+        // missing skills dir
+    }
+    return false;
+}
+
+/** Project + global agents roots for update. */
+export function getUpdateScopeRoots(opts: GlobalOpts): ScopeRoots {
+    const globalWorkdir = join(homedir(), '.agents');
+    const globalDir = join(globalWorkdir, 'skills');
+
+    if (opts.globalScope) {
+        // opts.workdir is ~/.agents; project agents root from cwd
+        const projectWorkdir = join(resolve(process.cwd()), '.agents');
+        return {
+            project: { workdir: projectWorkdir, dir: join(projectWorkdir, 'skills') },
+            global: { workdir: opts.workdir, dir: opts.dir },
+        };
+    }
+
+    return {
+        project: { workdir: opts.workdir, dir: opts.dir },
+        global: { workdir: globalWorkdir, dir: globalDir },
+    };
+}
+
 /**
- * Update installed skills by content hash (main path).
- * No resolve API — remote identity is skill.fingerprint from detail.
+ * Resolve update scope (vercel-labs/skills resolveUpdateScope).
+ * hasSkillNames = positional slug present.
+ * Returns null if the user cancels the interactive prompt.
+ */
+export async function resolveUpdateScope(
+    options: UpdateScopeOptions,
+    ctx: { inputAllowed: boolean; projectWorkdir: string; hasSkillNames: boolean }
+): Promise<UpdateScopeChoice | null> {
+    const g = Boolean(options.global);
+    const p = Boolean(options.project);
+
+    if (ctx.hasSkillNames) {
+        if (g && !p) return 'global';
+        if (p && !g) return 'project';
+        if (g && p) return 'both';
+        return 'both';
+    }
+
+    if (g && p) return 'both';
+    if (g) return 'global';
+    if (p) return 'project';
+
+    const skipPrompt = Boolean(options.yes) || !isInteractive() || !ctx.inputAllowed;
+    if (skipPrompt) {
+        return (await hasProjectSkills(ctx.projectWorkdir)) ? 'project' : 'global';
+    }
+
+    const picked = await selectUpdateScope();
+    if (picked === null) {
+        console.log('Update cancelled');
+        return null;
+    }
+    return picked;
+}
+
+/**
+ * Update installed skills by content hash.
+ * Scope selection matches vercel; remote identity is skill.fingerprint.
  */
 export async function cmdUpdate(
     opts: GlobalOpts,
     slugArg: string | undefined,
-    options: { all?: boolean; version?: string; force?: boolean },
+    options: UpdateScopeOptions,
     inputAllowed: boolean
 ) {
     const slug = slugArg ? normalizeSkillSlugOrFail(slugArg) : undefined;
@@ -42,16 +149,128 @@ export async function cmdUpdate(
     if (options.version && !slug) fail('--version requires a single <slug>');
     if (options.version && !semver.valid(options.version)) fail('--version must be valid semver');
 
-    const installWorkdir = opts.workdir;
-    const installDir = opts.dir;
+    const roots = getUpdateScopeRoots(opts);
+    const scope = await resolveUpdateScope(options, {
+        inputAllowed,
+        projectWorkdir: roots.project.workdir,
+        hasSkillNames: Boolean(slug),
+    });
+    if (scope === null) return;
+
+    const scopesToRun: Array<'project' | 'global'> =
+        scope === 'both' ? ['project', 'global'] : [scope];
+
+    const updated: string[] = [];
+    const alreadyCurrent: string[] = [];
+    const skippedPinned: string[] = [];
+    const failed: Array<{ slug: string; error: string; scope: string }> = [];
+
+    const registry = await getRegistry(opts, { cache: true });
+    const allowPrompt = isInteractive() && inputAllowed && !options.yes;
+
+    for (const scopeLabel of scopesToRun) {
+        const { workdir, dir } = roots[scopeLabel];
+        const result = await updateSkillsInOneScope({
+            installWorkdir: workdir,
+            installDir: dir,
+            scopeLabel,
+            multiScope: scopesToRun.length > 1,
+            slug,
+            options,
+            registry,
+            allowPrompt,
+        });
+        const tag = (s: string) => (scopesToRun.length > 1 ? `${s} (${scopeLabel})` : s);
+        updated.push(...result.updated.map(tag));
+        alreadyCurrent.push(...result.alreadyCurrent.map(tag));
+        skippedPinned.push(...result.skippedPinned.map(tag));
+        for (const f of result.failed) {
+            failed.push({ ...f, scope: scopeLabel });
+        }
+    }
+
+    if (
+        slug &&
+        updated.length === 0 &&
+        alreadyCurrent.length === 0 &&
+        skippedPinned.length === 0 &&
+        failed.length === 0
+    ) {
+        failed.push({ slug, error: 'not found', scope: scope === 'both' ? 'both' : scope });
+    }
+
+    if (
+        !slug &&
+        updated.length === 0 &&
+        alreadyCurrent.length === 0 &&
+        skippedPinned.length === 0 &&
+        failed.length === 0
+    ) {
+        console.log('No installed skills.');
+        return;
+    }
+
+    if (skippedPinned.length > 0 && updated.length === 0 && alreadyCurrent.length === 0 && !slug) {
+        console.log(`Skipped ${skippedPinned.length} pinned skill(s): ${skippedPinned.join(', ')}`);
+    }
+
+    console.log('');
+    console.log(
+        `Update summary: ${updated.length} updated, ${alreadyCurrent.length} up to date, ${skippedPinned.length} pinned skipped, ${failed.length} failed`
+    );
+    if (updated.length > 0) console.log(`  updated: ${updated.join(', ')}`);
+    if (alreadyCurrent.length > 0) console.log(`  up to date: ${alreadyCurrent.join(', ')}`);
+    if (skippedPinned.length > 0) {
+        console.log(`  pinned skipped: ${skippedPinned.join(', ')}`);
+    }
+    if (failed.length > 0) {
+        for (const item of failed) {
+            const scopeTag = scopesToRun.length > 1 ? ` [${item.scope}]` : '';
+            console.log(`  failed ${item.slug}${scopeTag}: ${item.error}`);
+        }
+        fail(`Failed to update ${failed.length} skill(s)`);
+    }
+}
+
+async function updateSkillsInOneScope(args: {
+    installWorkdir: string;
+    installDir: string;
+    scopeLabel: string;
+    multiScope: boolean;
+    slug: string | undefined;
+    options: UpdateScopeOptions;
+    registry: string;
+    allowPrompt: boolean;
+}): Promise<{
+    updated: string[];
+    alreadyCurrent: string[];
+    skippedPinned: string[];
+    failed: Array<{ slug: string; error: string }>;
+}> {
+    const {
+        installWorkdir,
+        installDir,
+        slug,
+        options,
+        registry,
+        allowPrompt,
+        scopeLabel,
+        multiScope,
+    } = args;
 
     const lock = await readLockfile(installWorkdir);
+
     if (slug && isPinnedSkillEntry(lock.skills[slug])) {
         fail(`skill "${slug}" is pinned; run \`dt-skill unpin ${slug}\` first`);
     }
-    const allowPrompt = isInteractive() && inputAllowed;
 
-    const registry = await getRegistry(opts, { cache: true });
+    if (slug) {
+        const onDisk = await fileExists(join(installDir, slug));
+        if (!lock.skills[slug] && !onDisk) {
+            return { updated: [], alreadyCurrent: [], skippedPinned: [], failed: [] };
+        }
+    }
+
     const requestedSlugs = slug ? [slug] : Object.keys(lock.skills).filter(isSafeSkillSlug);
     const skippedPinned = slug
         ? []
@@ -61,24 +280,17 @@ export async function cmdUpdate(
         : requestedSlugs.filter((entry) => !isPinnedSkillEntry(lock.skills[entry]));
 
     if (slugs.length === 0) {
-        if (skippedPinned.length > 0) {
-            const suffix = skippedPinned.length === 1 ? '' : 's';
-            console.log(
-                `Skipped ${skippedPinned.length} pinned skill${suffix}: ${skippedPinned.join(', ')}`
-            );
-            return;
-        }
-        console.log('No installed skills.');
-        return;
+        return { updated: [], alreadyCurrent: [], skippedPinned, failed: [] };
     }
 
     const updated: string[] = [];
     const alreadyCurrent: string[] = [];
     const failed: Array<{ slug: string; error: string }> = [];
     let lockDirty = false;
+    const checkLabel = multiScope ? `Checking ${scopeLabel}` : 'Checking';
 
     for (const entry of slugs) {
-        const spinner = createSpinner(`Checking ${entry}`);
+        const spinner = createSpinner(`${checkLabel} ${entry}`);
         try {
             const target = join(installDir, entry);
             const exists = await fileExists(target);
@@ -109,7 +321,7 @@ export async function cmdUpdate(
                         console.log(`${entry}: skipped`);
                         continue;
                     }
-                    spinner.start(`Checking ${entry}`);
+                    spinner.start(`${checkLabel} ${entry}`);
                 } else {
                     console.log(`${entry}: skipped (use --force to update suspicious skills)`);
                     continue;
@@ -152,7 +364,6 @@ export async function cmdUpdate(
                         prev,
                         decision.fingerprint
                     );
-                    // Persist once after the loop (lockDirty).
                     lockDirty = true;
                 }
                 spinner.succeed(
@@ -166,7 +377,6 @@ export async function cmdUpdate(
                 continue;
             }
 
-            // decision.action === 'update'
             const targetVersion = decision.version;
             if (spinner.isSpinning) {
                 spinner.text = `Updating ${entry}`;
@@ -206,7 +416,6 @@ export async function cmdUpdate(
                 throw error;
             }
 
-            // Persist once after the loop (lockDirty).
             lockDirty = true;
             spinner.succeed(
                 `${entry}: updated${
@@ -226,19 +435,5 @@ export async function cmdUpdate(
         await writeLockfile(installWorkdir, lock);
     }
 
-    console.log('');
-    console.log(
-        `Update summary: ${updated.length} updated, ${alreadyCurrent.length} up to date, ${skippedPinned.length} pinned skipped, ${failed.length} failed`
-    );
-    if (updated.length > 0) console.log(`  updated: ${updated.join(', ')}`);
-    if (alreadyCurrent.length > 0) console.log(`  up to date: ${alreadyCurrent.join(', ')}`);
-    if (skippedPinned.length > 0) {
-        console.log(`  pinned skipped: ${skippedPinned.join(', ')}`);
-    }
-    if (failed.length > 0) {
-        for (const item of failed) {
-            console.log(`  failed ${item.slug}: ${item.error}`);
-        }
-        fail(`Failed to update ${failed.length} skill(s)`);
-    }
+    return { updated, alreadyCurrent, skippedPinned, failed };
 }
diff --git a/dt-skill/src/cli/ui.ts b/dt-skill/src/cli/ui.ts
index 9d95be5e..c361f192 100644
--- a/dt-skill/src/cli/ui.ts
+++ b/dt-skill/src/cli/ui.ts
@@ -177,25 +177,60 @@ function byLabel(a: AgentType, b: AgentType): number {
 }
 
 /** Project vs Global scope selection. Returns true=global, false=project, null=cancelled. */
-export async function selectScope(): Promise<boolean | null> {
+export async function selectScope(message = 'Installation scope'): Promise<boolean | null> {
+    if (!isInteractive()) return null;
+    const options: Array<{ value: boolean; label: string; hint: string }> = [
+        {
+            value: false,
+            label: 'Project',
+            hint: 'Install in current directory (committed with your project)',
+        },
+        {
+            value: true,
+            label: 'Global',
+            hint: 'Install in home directory (available across all projects)',
+        },
+    ];
+    const scope = await select({ message, options });
+    if (isCancel(scope)) return null;
+    if (scope === true || scope === false) return scope;
+    return null;
+}
+
+/** Update scope (vercel-aligned). Returns null if cancelled. */
+export type UpdateScopeChoice = 'project' | 'global' | 'both';
+
+const UPDATE_SCOPE_OPTIONS: Array<{
+    value: UpdateScopeChoice;
+    label: string;
+    hint: string;
+}> = [
+    {
+        value: 'project',
+        label: 'Project',
+        hint: 'Update skills in current directory',
+    },
+    {
+        value: 'global',
+        label: 'Global',
+        hint: 'Update skills in home directory',
+    },
+    {
+        value: 'both',
+        label: 'Both',
+        hint: 'Update all skills',
+    },
+];
+
+export async function selectUpdateScope(): Promise<UpdateScopeChoice | null> {
     if (!isInteractive()) return null;
     const scope = await select({
-        message: 'Installation scope',
-        options: [
-            {
-                value: false,
-                label: 'Project',
-                hint: 'Install in current directory (committed with your project)',
-            },
-            {
-                value: true,
-                label: 'Global',
-                hint: 'Install in home directory (available across all projects)',
-            },
-        ],
+        message: 'Update scope',
+        options: UPDATE_SCOPE_OPTIONS,
     });
     if (isCancel(scope)) return null;
-    return scope as boolean;
+    if (scope === 'project' || scope === 'global' || scope === 'both') return scope;
+    return null;
 }
 
 /** Skill market category selection (first publish). Returns null=cancelled. */
diff --git a/env.json b/env.json
index 144c6916..a0a5e2b2 100644
--- a/env.json
+++ b/env.json
@@ -5,6 +5,7 @@
     "helpDocUrl": "https://dtstack.github.io/doraemon/docsify/#/",
     "articleHelpDocUrl": "https://dtstack.github.io/doraemon/docsify/#/zh-cn/guide/%E6%96%87%E7%AB%A0%E8%AE%A2%E9%98%85",
     "proxyHelpDocUrl": "https://dtstack.github.io/doraemon/docsify/#/zh-cn/guide/%E4%BB%A3%E7%90%86%E6%9C%8D%E5%8A%A1",
+    "skillsHelpDocUrl": "https://dtstack.github.io/doraemon/docsify/#/zh-cn/guide/dt-skill",
     "mysql": {
         "prod": {}
     },
diff --git a/sql/doraemon.sql b/sql/doraemon.sql
index 18f60a8e..30b4f373 100644
--- a/sql/doraemon.sql
+++ b/sql/doraemon.sql
@@ -337,6 +337,7 @@ CREATE TABLE `skills_items` (
   `allowed_tools` longtext COMMENT 'JSON字符串数组',
   `contributor` varchar(50) DEFAULT NULL COMMENT '贡献者',
   `stars` int NOT NULL DEFAULT '0',
+  `downloads` int NOT NULL DEFAULT '0' COMMENT 'zip 成功下发次数（Web 下载 + CLI install）',
   `updated_at_remote` datetime DEFAULT NULL COMMENT '源仓库文件更新时间',
   `source_repo` varchar(1000) DEFAULT NULL COMMENT '仓库地址',
   `source_path` varchar(1000) DEFAULT NULL COMMENT '仓库内 skill 相对路径',
@@ -351,6 +352,7 @@ CREATE TABLE `skills_items` (
   KEY `idx_skills_source_id` (`source_id`),
   KEY `idx_skills_category` (`category`),
   KEY `idx_skills_stars` (`stars`),
+  KEY `idx_skills_downloads` (`downloads`),
   KEY `idx_skills_updated_at_remote` (`updated_at_remote`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='技能条目表';
 
diff --git a/test/skills-registry-contract.test.js b/test/skills-registry-contract.test.js
index 627844ea..d3be2208 100644
--- a/test/skills-registry-contract.test.js
+++ b/test/skills-registry-contract.test.js
@@ -132,6 +132,7 @@ test('listSkills returns items with cursor pagination', async () => {
                     version: '1.0.0',
                     tags: '["test"]',
                     stars: 3,
+                    downloads: 7,
                     created_at: new Date('2026-05-21T10:00:00Z'),
                     updated_at: new Date('2026-05-21T10:00:00Z'),
                 },
@@ -143,6 +144,7 @@ test('listSkills returns items with cursor pagination', async () => {
                     version: '2.0.0',
                     tags: '[]',
                     stars: 10,
+                    downloads: 2,
                     created_at: new Date('2026-05-21T09:00:00Z'),
                     updated_at: new Date('2026-05-21T09:00:00Z'),
                 },
@@ -161,7 +163,7 @@ test('listSkills returns items with cursor pagination', async () => {
     assert.equal(first.displayName, 'Skill B');
     assert.equal(first.summary, 'Desc B');
     assert.deepEqual(first.tags, ['test']);
-    assert.deepEqual(first.stats, { stars: 3, downloads: 0 });
+    assert.deepEqual(first.stats, { stars: 3, downloads: 7 });
     assert.equal(first.createdAt, new Date('2026-05-21T10:00:00Z').getTime());
     assert.equal(first.updatedAt, new Date('2026-05-21T10:00:00Z').getTime());
     assert.deepEqual(first.latestVersion, {
@@ -172,6 +174,38 @@ test('listSkills returns items with cursor pagination', async () => {
     });
 });
 
+test('listSkills sort=downloads orders by downloads field (not stars)', async () => {
+    const calls = [];
+    const service = Object.create(SkillsRegistryService.prototype);
+    service.app = createMockApp({
+        SkillsItem: {
+            findAll: async (options) => {
+                calls.push(options);
+                return [
+                    {
+                        id: 2,
+                        slug: 'hot-skill',
+                        name: 'Hot',
+                        tags: '[]',
+                        stars: 1,
+                        downloads: 99,
+                        created_at: new Date('2026-05-21T10:00:00Z'),
+                        updated_at: new Date('2026-05-21T10:00:00Z'),
+                    },
+                ];
+            },
+        },
+    });
+    service.ctx = createMockCtx();
+
+    const data = await service.listSkills(null, 'downloads', 10);
+    assert.deepEqual(calls[0].order, [
+        ['downloads', 'DESC'],
+        ['id', 'DESC'],
+    ]);
+    assert.deepEqual(data.items[0].stats, { stars: 1, downloads: 99 });
+});
+
 test('listSkills uses a composite cursor that matches newest sorting', async () => {
     const calls = [];
     const rows = [
@@ -281,6 +315,7 @@ test('getSkillDetail returns full skill object', async () => {
                 version: '1.2.3',
                 tags: '["test"]',
                 stars: 42,
+                downloads: 11,
                 created_at: new Date('2026-05-21T10:00:00Z'),
                 updated_at: new Date('2026-05-21T10:00:00Z'),
             }),
@@ -296,7 +331,7 @@ test('getSkillDetail returns full skill object', async () => {
     assert.equal(data.skill.summary, 'A test skill');
     assert.equal(data.skill.version, '1.2.3');
     assert.deepEqual(data.skill.tags, ['test']);
-    assert.deepEqual(data.skill.stats, { stars: 42, downloads: 0 });
+    assert.deepEqual(data.skill.stats, { stars: 42, downloads: 11 });
     assert.equal(data.skill.createdAt, new Date('2026-05-21T10:00:00Z').getTime());
     assert.equal(data.skill.updatedAt, new Date('2026-05-21T10:00:00Z').getTime());
     assert.equal(data.skill.fingerprint, null);
@@ -493,6 +528,7 @@ test('buildSkillZip returns zip buffer', async () => {
 
     const result = await service.buildSkillZip('my-skill');
     assert.ok(result);
+    assert.equal(result.slug, 'my-skill');
     assert.ok(result.fileName.includes('my-skill'));
     assert.ok(Buffer.isBuffer(result.content));
     assert.ok(result.content.length > 0);
@@ -534,6 +570,7 @@ test('buildSkillZip packages skill package nested structure when is_package is 1
 
     const result = await service.buildSkillZip('my-skills-pack');
     assert.ok(result);
+    assert.equal(result.slug, 'my-skills-pack');
     assert.ok(result.fileName.includes('my-skills-pack'));
     assert.ok(Buffer.isBuffer(result.content));
 
diff --git a/test/skills-registry-integration.test.js b/test/skills-registry-integration.test.js
index 06410753..492a2efc 100644
--- a/test/skills-registry-integration.test.js
+++ b/test/skills-registry-integration.test.js
@@ -43,6 +43,9 @@ function buildController(serviceMethods) {
     controller.ctx.service = {
         skillsRegistry: serviceMethods,
         skillLike: skillLikeService,
+        skills: {
+            incrementDownloads: async () => {},
+        },
     };
     return controller;
 }
@@ -88,12 +91,20 @@ test('detail endpoint returns 404 for missing skill', async () => {
 });
 
 test('download endpoint sets correct headers', async () => {
+    let countedSlug = null;
     const controller = buildController({
         buildSkillZip: async (slug) => {
             assert.equal(slug, 'my-skill');
-            return { fileName: 'my-skill-1.0.0.zip', content: Buffer.from('PK') };
+            return {
+                slug: 'my-skill',
+                fileName: 'my-skill-1.0.0.zip',
+                content: Buffer.from('PK'),
+            };
         },
     });
+    controller.ctx.service.skills.incrementDownloads = async (slug) => {
+        countedSlug = slug;
+    };
     controller.ctx.query = { slug: 'my-skill', version: '1.0.0' };
     const headers = {};
     controller.ctx.set = (k, v) => {
@@ -104,6 +115,7 @@ test('download endpoint sets correct headers', async () => {
     assert.equal(headers['Content-Type'], 'application/zip');
     assert.ok(headers['Content-Disposition'].includes('my-skill-1.0.0.zip'));
     assert.ok(Buffer.isBuffer(controller.ctx.body));
+    assert.equal(countedSlug, 'my-skill');
 });
 
 test('publish endpoint parses multipart payload JSON string', async () => {