feat(agents): resolve built-in skill descriptions from agent SKILL.md

- getAgentDetail: for uncatalogued entrypoint, built-in (private) and
  uncatalogued dependency skills, fall back to the in-package SKILL.md
  (agent_files) to resolve real name/description
- skill-utils: add extractSkillMdName to read frontmatter name
- Agent detail: hide built-in Skills card when empty

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: liuxy0551

app/service/agents.js

@@ -6,7 +6,11 @@ const path = require('path');
 const yaml = require('js-yaml');
 const mime = require('mime-types');
 
-const { normalizeRelativePath } = require('../utils/skill-utils');
+const {
+    normalizeRelativePath,
+    extractSkillMdDescription,
+    extractSkillMdName,
+} = require('../utils/skill-utils');
 const {
     isValidSkillCategory,
     SKILL_CATEGORY_OPTIONS,
@@ -69,6 +73,19 @@ class AgentsService extends Service {
         return normalized;
     }
 
+    // agent.yaml 里的 ref 指向目录（skills/bugfix-workflow）或 SKILL.md 本身，
+    // 统一归一化为包内 SKILL.md 相对路径，供 agent_files 精确匹配。
+    resolveSkillMdPath(refOrPath) {
+        const normalized = String(refOrPath || '').trim();
+        if (!normalized) return '';
+        return normalized.toLowerCase().endsWith('.md') ? normalized : `${normalized}/SKILL.md`;
+    }
+
+    lookupSkillMd(skillMdMap, refOrPath) {
+        if (!skillMdMap) return '';
+        return skillMdMap.get(this.resolveSkillMdPath(refOrPath)) || '';
+    }
+
     parseJsonArray(value) {
         if (!value) return [];
         if (Array.isArray(value)) return value;
@@ -929,7 +946,8 @@ class AgentsService extends Service {
 
     async getAgentDetail(name) {
         await this.ensureStorageReady();
-        const { Agent, AgentSkill, SkillsItem } = this.app.model;
+        const { Agent, AgentSkill, SkillsItem, AgentFile } = this.app.model;
+        const { Op } = this.app.Sequelize;
         const row = await Agent.findOne({
             where: {
                 name,
@@ -964,6 +982,8 @@ class AgentsService extends Service {
         const skillMap = new Map(skillRows.map((item) => [item.slug, item]));
 
         const entrypoint = relations.find((item) => item.relation_type === 'entrypoint') || null;
+        const entrypointSkill = entrypoint ? skillMap.get(entrypoint.skill_slug) : null;
+
         const dependencies = relations
             .filter((item) => item.relation_type === 'dependency')
             .map((item) => {
@@ -987,6 +1007,61 @@ class AgentsService extends Service {
                 path: '',
             }));
 
+        // 未收录的入口 Skill 和内置 Skills 不在 SkillsItem 表，其真实 name/description
+        // 从 agent 包内自带的 SKILL.md 解析（agent_files 已在导入时保存文件内容）。
+        const skillMdPaths = [
+            ...(entrypoint && !entrypointSkill ? [this.resolveSkillMdPath(row.entrypoint_ref)] : []),
+            ...privateSkills.map((item) => `skills/${item.slug}/SKILL.md`),
+            ...dependencies
+                .filter((item) => !item.collected)
+                .map((item) => `skills/${item.slug}/SKILL.md`),
+        ].filter(Boolean);
+        const skillMdRows =
+            skillMdPaths.length > 0 && AgentFile
+                ? await AgentFile.findAll({
+                      where: {
+                          agent_id: row.id,
+                          file_path: { [Op.in]: skillMdPaths },
+                          is_delete: 0,
+                      },
+                  })
+                : [];
+        const skillMdMap = new Map(skillMdRows.map((item) => [item.file_path, item.content || '']));
+
+        // 入口 Skill：已收录用 SkillsItem 描述；未收录回填包内 SKILL.md 的 name/description
+        const entrypointItem = entrypoint
+            ? (() => {
+                  const skill = entrypointSkill;
+                  const skillMd = skill ? '' : this.lookupSkillMd(skillMdMap, row.entrypoint_ref);
+                  return {
+                      slug: entrypoint.skill_slug,
+                      name: skill ? skill.name : extractSkillMdName(skillMd) || entrypoint.skill_slug,
+                      description: skill ? skill.description || '' : extractSkillMdDescription(skillMd),
+                      collected: Boolean(skill),
+                      path: `/page/skills/${entrypoint.skill_slug}`,
+                  };
+              })()
+            : null;
+
+        // 内置 Skills：总是从包内 SKILL.md 回填
+        privateSkills.forEach((item) => {
+            const skillMd = skillMdMap.get(`skills/${item.slug}/SKILL.md`) || '';
+            const name = extractSkillMdName(skillMd);
+            if (name) item.name = name;
+            const description = extractSkillMdDescription(skillMd);
+            if (description) item.description = description;
+        });
+
+        // 未收录的依赖 Skills：包内有 SKILL.md 时同样回填
+        dependencies.forEach((item) => {
+            if (item.collected) return;
+            const skillMd = skillMdMap.get(`skills/${item.slug}/SKILL.md`) || '';
+            const name = extractSkillMdName(skillMd);
+            if (name) item.name = name;
+            const description = extractSkillMdDescription(skillMd);
+            if (description) item.description = description;
+        });
+
         const detail = row.toJSON();
         const demoImages = this.parseJsonArray(detail.demo_images).map((item) => ({
             ...item,
@@ -1008,19 +1083,7 @@ class AgentsService extends Service {
             logoUrl: this.buildAssetUrl(detail.name, detail.logo_path),
             logoPath: detail.logo_path,
             demoImages,
-            entrypoint: entrypoint
-                ? {
-                      slug: entrypoint.skill_slug,
-                      name: skillMap.get(entrypoint.skill_slug)
-                          ? skillMap.get(entrypoint.skill_slug).name
-                          : entrypoint.skill_slug,
-                      description: skillMap.get(entrypoint.skill_slug)
-                          ? skillMap.get(entrypoint.skill_slug).description || ''
-                          : '',
-                      collected: Boolean(skillMap.get(entrypoint.skill_slug)),
-                      path: `/page/skills/${entrypoint.skill_slug}`,
-                  }
-                : null,
+            entrypoint: entrypointItem,
             dependencies,
             privateSkills,
             updatedAt: detail.updated_at ? detail.updated_at.toISOString() : '',

app/utils/skill-utils.js

@@ -91,6 +91,31 @@ function extractSkillMdDescription(skillMdContent) {
     return extractBodySummary(body) || extractBodySummary(normalized);
 }
 
+/** Frontmatter `name:` from SKILL.md, quoted-scalar aware. Empty when absent. */
+function extractSkillMdName(content) {
+    const text = String(content || '');
+    const normalized = text.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n')) return '';
+    const endMarkerIndex = normalized.indexOf('\n---\n', 4);
+    if (endMarkerIndex === -1) return '';
+    const frontmatterText = normalized.slice(4, endMarkerIndex);
+    const lines = frontmatterText.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const keyMatch = lines[i].match(/^name:\s*(.*)$/i);
+        if (!keyMatch) continue;
+        const rest = keyMatch[1].trim();
+        if (!rest) continue;
+        if (
+            (rest.startsWith('"') && rest.endsWith('"')) ||
+            (rest.startsWith("'") && rest.endsWith("'"))
+        ) {
+            return rest.slice(1, -1).trim();
+        }
+        return rest;
+    }
+    return '';
+}
+
 /**
  * Market card description (CLI registry + Web zip/import/update).
  * Explicit override wins; else keep non-empty card; else SKILL.md default.
@@ -110,6 +135,7 @@ function resolveMarketCardDescription(opts = {}) {
 module.exports = {
     normalizeRelativePath,
     extractSkillMdDescription,
+    extractSkillMdName,
     extractBodySummary,
     resolveMarketCardDescription,
 };

app/web/pages/agents/detail/AgentDetailContent.tsx

@@ -435,9 +435,9 @@ const AgentDetailContent: React.FC<AgentDetailContentProps> = ({ name, history }
                                     )}
                                 </Card>
 
-                                <Card className="agent-section-card">
-                                    <Title level={4}>内置 Skills</Title>
-                                    {detail.privateSkills.length > 0 ? (
+                                {detail.privateSkills.length > 0 ? (
+                                    <Card className="agent-section-card">
+                                        <Title level={4}>内置 Skills</Title>
                                         <div className="agent-skill-grid">
                                             {detail.privateSkills.map((item) => (
                                                 <SkillRelationCard
@@ -447,10 +447,8 @@ const AgentDetailContent: React.FC<AgentDetailContentProps> = ({ name, history }
                                                 />
                                             ))}
                                         </div>
-                                    ) : (
-                                        <Empty description="暂无内置 Skills" />
-                                    )}
-                                </Card>
+                                    </Card>
+                                ) : null}
 
                                 {detail.dependencies.length > 0 ? (
                                     <Card className="agent-section-card">

test/agent-market-service.test.js

@@ -462,3 +462,123 @@ test('getAgentArchiveStream 返回当前 hash 对应的原始 ZIP', async () =>
         fs.rmSync(storageDir, { recursive: true, force: true });
     }
 });
+
+function createDetailService() {
+    const service = createService();
+    service.storageReady = true;
+    service.app.Sequelize = { Op: require('sequelize').Op };
+
+    const row = {
+        id: 1,
+        name: 'bugfix-agent',
+        display_name: 'Bugfix Agent',
+        description: 'Agent 简短描述',
+        profile: '简介',
+        author_name: 'DTStack',
+        category: '工程效率',
+        tags: '[]',
+        prompts: '[]',
+        capabilities: '[]',
+        version: '1.0.0',
+        logo_path: '',
+        demo_images: '[]',
+        updated_at: new Date('2026-01-01T00:00:00Z'),
+        entrypoint_ref: 'skills/bugfix-workflow',
+        toJSON() {
+            return { ...this };
+        },
+    };
+
+    const skillMdContents = {
+        'skills/bugfix-workflow/SKILL.md':
+            '---\nname: Bugfix Workflow\n---\n# Bugfix Workflow\n修复 Bug 的完整流程',
+        'skills/builtin-review/SKILL.md':
+            '---\nname: 内置审查 Skill\n---\n# 内置审查\n用于代码审查',
+        'skills/systematic-debugging/SKILL.md':
+            '---\nname: Systematic Debugging\n---\n# Systematic Debugging\n系统化调试方法论',
+    };
+
+    service.app.model = {
+        Agent: {
+            async findOne() {
+                return row;
+            },
+        },
+        AgentSkill: {
+            async findAll() {
+                return [
+                    { skill_slug: 'bugfix-workflow', relation_type: 'entrypoint', sort_order: 0 },
+                    { skill_slug: 'builtin-review', relation_type: 'private', sort_order: 0 },
+                    {
+                        skill_slug: 'systematic-debugging',
+                        relation_type: 'dependency',
+                        sort_order: 0,
+                    },
+                ];
+            },
+        },
+        SkillsItem: {
+            async findAll() {
+                return [];
+            },
+        },
+        AgentFile: {
+            async findAll({ where }) {
+                const { Op } = service.app.Sequelize;
+                const paths = where.file_path[Op.in] || [];
+                return paths
+                    .filter((filePath) => skillMdContents[filePath] !== undefined)
+                    .map((filePath) => ({
+                        file_path: filePath,
+                        content: skillMdContents[filePath],
+                    }));
+            },
+        },
+    };
+
+    return service;
+}
+
+test('getAgentDetail 未收录入口/内置/依赖 Skill 从包内 SKILL.md 回填描述', async () => {
+    const detail = await createDetailService().getAgentDetail('bugfix-agent');
+
+    // 核心工作流：未收录时回填 SKILL.md 的 name/description
+    assert.equal(detail.entrypoint.name, 'Bugfix Workflow');
+    assert.match(detail.entrypoint.description, /修复 Bug/);
+    assert.equal(detail.entrypoint.collected, false);
+
+    // 内置 Skills：总是回填，name 取 frontmatter，标记 builtin
+    assert.equal(detail.privateSkills.length, 1);
+    assert.equal(detail.privateSkills[0].name, '内置审查 Skill');
+    assert.match(detail.privateSkills[0].description, /代码审查/);
+    assert.equal(detail.privateSkills[0].builtin, true);
+    assert.equal(detail.privateSkills[0].path, '');
+
+    // 未收录的依赖 Skills：包内有 SKILL.md 时同样回填
+    assert.equal(detail.dependencies.length, 1);
+    assert.equal(detail.dependencies[0].name, 'Systematic Debugging');
+    assert.match(detail.dependencies[0].description, /系统化调试/);
+});
+
+test('getAgentDetail 已收录入口 Skill 用 SkillsItem 描述，且不查包内 SKILL.md', async () => {
+    const service = createDetailService();
+    service.app.model.SkillsItem.findAll = async () => [
+        { slug: 'bugfix-workflow', name: 'Bugfix Workflow(已收录)', description: '来自 Skills Hub 的描述' },
+    ];
+    // 包内不提供 SKILL.md，验证已收录场景不读取它
+    service.app.model.AgentFile.findAll = async ({ where }) => {
+        const { Op } = service.app.Sequelize;
+        const paths = where.file_path[Op.in] || [];
+        assert.equal(paths.length, 2); // 仅内置 + 未收录依赖，不再包含入口
+        return [];
+    };
+
+    const detail = await service.getAgentDetail('bugfix-agent');
+
+    assert.equal(detail.entrypoint.name, 'Bugfix Workflow(已收录)');
+    assert.equal(detail.entrypoint.description, '来自 Skills Hub 的描述');
+    assert.equal(detail.entrypoint.collected, true);
+    // 内置 Skill 无 SKILL.md：name 回退 slug，description 为空（前端显示"暂无描述"）
+    assert.equal(detail.privateSkills[0].name, 'builtin-review');
+    assert.equal(detail.privateSkills[0].description, '');
+});