mirror of https://git.openapi.site/https://github.com/desirecore/market.git synced 2026-10-21 06:24:08 +08:00

Files

Yige 8f7953948f fix: 补齐市场静态事实并保持旧客户端兼容 (#184 )

## 中文

补齐已有 owner 与已锁定上游内容可证明的许可证、技能类型和收录版本。保留 Anthropic Source Available
和其他附加条件，不把所有内容统一标为 MIT，不提升 listing-only 的安装准入。

README 保留最新的双语结构及以 manifest 为准的数量口径，增加静态目录不存访问量、下载量、评分或 Stars 的边界。

发布兼容性：**本 PR 不包含**两支团队新增的本地化字段，也不包含微信支付 `latestVersion:
1.0`；旧客户端会拒绝这些新字段，另以待发布 PR 保留，等匹配客户端发布后再合并。

验证：47 项目录校验测试、19 项 i18n 测试、5 项合集生成测试通过；完整目录/i18n/翻译新鲜度检查通过，6
个固定来源合集的生成检查通过，2 个浮动来源按既有规则明确跳过。发现并修复了生成器在 Windows 使用反斜杠造成的误报：输出改为 POSIX
路径，比较规则不放宽、不重写合集数据。

## English

Fill only license, type and listed-release facts supported by existing
owners or pinned upstream content. Preserve custom license restrictions
and acquisition eligibility. Keep the current bilingual README and
manifest-derived inventory; do not author usage analytics.

This PR deliberately excludes localized team fields and the two-part
WeChat Pay version that older clients reject. Those changes remain
pending a compatible client release.

Validation passes: 47 catalog-validator tests, 19 i18n tests, five
collection-generator tests, complete catalog and translation checks, and
generated inventory checks for six pinned collections. Two mutable
sources remain explicitly skipped. Fix Windows-generated path separators
without weakening comparison or changing declared children.

2026-09-22 01:09:03 +08:00

18 KiB

Raw Blame History

license, name, description, version, type, risk_level, status, disable-model-invocation, tags, metadata, market

license

name

description

version

type

risk_level

status

disable-model-invocation

manage-skills Skill

L0: One-line Summary

Manage the full lifecycle of Skills—import, author, install, update, and delete.

L1: Overview and Use Cases

Capability

manage-skills is a Meta-Skill that gives DesireCore the ability to manage the Skill system. It covers five core operations:

Import a Skill from a URL — supply a remote SKILL.md URL, fetch the content, and create
Bulk import from a Git repository — clone a Git repo, scan all SKILL.md files, and selectively import
Manage existing Skills via API — list, read, update, delete, enable/disable Skills
Author SKILL.md directly via AgentFS — use the Write/Edit tools to create Skills on the filesystem
Bulk operations and cross-Agent copying — bulk enable/disable/delete, plus copy Skills to other Agents

Use Cases

The user wants to import community-shared Skills from platforms like GitHub
The user wants to install a new Skill on an Agent to enhance its capabilities
The user needs to author a custom Skill to teach the Agent a new workflow
The user wants to bulk-manage existing Skills (enable/disable/delete)
The user wants to copy one Agent's Skill to another Agent
The user needs to view or edit the contents of a Skill

Core Value

Self-extension: an Agent can autonomously expand its capability boundary by importing or authoring Skills
Governable: every Skill change goes through the API or filesystem operations and is traceable and auditable
Flexibility: supports both API import and direct filesystem authoring to fit different scenarios

L2: Detailed Specification

1. Import a Single Skill from a URL

For importing a single SKILL.md file (e.g. a GitHub raw link).

Step 1: Fetch the remote content

POST /api/skills/fetch-url
Content-Type: application/json

{
  "url": "https://raw.githubusercontent.com/user/repo/main/my-skill/SKILL.md"
}

Success response (200 OK):

{
  "content": "---\nname: My Skill\ndescription: ...\n---\n\n# Skill content..."
}

Security limits:

HTTPS URLs only
20MB file size limit
30-second request timeout

Step 2: Create the Skill

After a successful fetch, choose the creation endpoint based on scope:

Create a global Skill (visible to all Agents):

POST /api/skills
Content-Type: application/json

{
  "skillId": "my-skill",
  "content": "<content returned in the previous step>"
}

Create an Agent-scoped Skill (visible only to the specified Agent):

POST /api/agents/{agentId}/skills
Content-Type: application/json

{
  "id": "my-skill",
  "fullContent": "<content returned in the previous step>"
}

Success response (201 Created):

{
  "success": true,
  "skill": { "id": "my-skill", "name": "My Skill", "description": "..." }
}

2. Bulk Import from a Git Repository

For importing a Git repository that contains multiple Skills.

Step 1: Scan the repository

POST /api/skills/fetch-git
Content-Type: application/json

{
  "url": "https://github.com/user/skill-collection.git"
}

Success response (200 OK):

{
  "skills": [
    {
      "id": "data-analysis",
      "path": "data-analysis",
      "content": "---\nname: Data Analysis\n...",
      "sidecarFiles": [{ "name": "examples.md", "content": "..." }]
    },
    {
      "id": "report-writing",
      "path": "report-writing",
      "content": "---\nname: Report Writing\n..."
    }
  ]
}

The API automatically:

Uses --depth=1 shallow clone to reduce download size
Recursively scans for SKILL.md files in directories
Derives skillId from the directory name (falls back to a slug from the frontmatter name)
Collects sidecar files in the same directory (e.g. examples.md, references/)
Cleans up the temporary directory once finished

Step 2: Import the chosen Skills one by one

Show the scan results to the user and let them choose which Skills to import, then call the create API for each:

# Global Skill
POST /api/skills
{ "skillId": "data-analysis", "content": "<content>" }

# Or Agent-scoped Skill
POST /api/agents/{agentId}/skills
{ "id": "data-analysis", "fullContent": "<content>" }

Handling sidecarFiles: if the scan result contains sidecarFiles, after creating the Skill write them to the corresponding directory:

# Sidecar file path for a global Skill
${DESIRECORE_ROOT}/skills/{skillId}/{filename}

# Sidecar file path for an Agent-scoped Skill
${DESIRECORE_ROOT}/agents/{agentId}/skills/{skillId}/{filename}

3. Manage Existing Skills via API

List All Skills

GET /api/skills/list
GET /api/skills/list?agentId={agentId}
GET /api/skills/list?includeDisabled=true

Returns a Skill list covering all three scopes: project, agent, and global.

List Skills for a Specific Agent

GET /api/agents/{agentId}/skills

Read Skill Content

# Resolved automatically by scope priority
GET /api/skills/{skillId}/content
GET /api/skills/{skillId}/content?agentId={agentId}

# Read a specific Agent's Skill
GET /api/agents/{agentId}/skills/{skillId}

Update Skill Content

Update a global Skill:

PUT /api/skills/{skillId}/content
Content-Type: application/json

{
  "content": "---\nname: Updated Skill\n...\n---\n\n# New content..."
}

Update an Agent-scoped Skill:

PUT /api/agents/{agentId}/skills/{skillId}
Content-Type: application/json

{
  "content": "---\nname: Updated Skill\n...\n---\n\n# New content...",
  "bumpVersion": "minor"
}

bumpVersion accepts: major | minor | patch; when specified, the version number is auto-incremented. The system automatically updates metadata.updated_at whenever the content changes.

Delete a Skill

# Delete a global Skill
DELETE /api/skills/{skillId}

# Delete an Agent-scoped Skill
DELETE /api/agents/{agentId}/skills/{skillId}

Enable/Disable a Skill

# Global Skill
PATCH /api/skills/{skillId}/status
Content-Type: application/json
{ "enabled": false }

# Agent-scoped Skill
PATCH /api/agents/{agentId}/skills/{skillId}/status
Content-Type: application/json
{ "enabled": true }

Bulk Operations

POST /api/agents/{agentId}/skills/batch
Content-Type: application/json

{
  "action": "enable",
  "ids": ["skill-a", "skill-b", "skill-c"]
}

action accepts: enable | disable | delete

Copy a Skill to Another Agent

POST /api/agents/{targetAgentId}/skills/copy
Content-Type: application/json

{
  "sourceSkillId": "data-analysis",
  "sourceAgentId": "analyst",
  "targetSkillId": "data-analysis-v2"
}

Optional parameters:

sourceAgentId — source Agent ID (required when copying from agent scope)
sourceSource — source scope: project | agent | global
sourceWorkDir — source project workDir (used when copying from project scope)
targetSkillId — target Skill ID (defaults to sourceSkillId if omitted)

4. Author SKILL.md Directly via AgentFS

When you need to create a Skill from scratch or the API approach is not flexible enough, you can author SKILL.md directly on the filesystem.

Directory Structure

Global Skill (visible to all Agents):

${DESIRECORE_ROOT}/skills/
└── my-new-skill/
    ├── SKILL.md          # required: skill definition file
    ├── examples/          # optional: example files
    ├── scripts/           # optional: helper scripts
    └── references/        # optional: reference material

Agent-scoped Skill (visible only to the specified Agent):

${DESIRECORE_ROOT}/agents/{agentId}/
└── skills/
    └── my-new-skill/
        ├── SKILL.md
        └── ...

Full SKILL.md Format

---
# === Required fields ===
description: >-
  Full description of the Skill's purpose. Should include a "Use when" trigger hint
  to help the AI decide when to use this Skill.

# === Recommended fields ===
name: Skill display name
version: 1.0.0
type: procedural
risk_level: low
status: enabled
tags:
  - tag1
  - tag2
metadata:
  author: your-name
  updated_at: '2026-03-03'

# === Optional fields ===
disable-model-invocation: true
requires:
  tools:
    - Bash
    - Read
  optional_tools:
    - Edit
---

# skill-id Skill

## L0: One-line Summary

Describe in one sentence what this Skill does.

## L1: Overview and Use Cases

### Capability

Detailed description of the Skill's core capability.

### Use Cases

- Scenario 1
- Scenario 2

### Core Value

- Value 1
- Value 2

## L2: Detailed Specification

### Concrete Steps

Describe the execution flow, API calls, and input/output formats stage by stage / step by step.

### Error Handling

| Error scenario | Handling |
| -------- | -------- |
| ...      | ...      |

Example: Create a Skill with the Write Tool

The following example shows how to create a global Skill with the Write tool:

Target path: ${DESIRECORE_ROOT}/skills/daily-summary/SKILL.md

Content to write:

---
name: Daily Summary
description: >-
  Aggregates today's conversation records and produces a structured daily work summary.
  Use when the user asks for a summary of today's work, generation of a daily report, or a recap of conversation content.
version: 1.0.0
type: procedural
risk_level: low
status: enabled
tags:
  - summary
  - daily
  - productivity
metadata:
  author: user
  updated_at: '2026-03-03'
---

# daily-summary Skill

## L0: One-line Summary

Aggregates today's conversation records and automatically produces a structured work summary.

## L1: Overview and Use Cases

### Capability

Extracts key information from conversation history, organizes it by project/topic, and produces a daily summary
covering completed items, to-dos, and important decisions.

### Use Cases

- The user asks for a summary at the end of a workday
- The user needs material for a daily or weekly report
- The user wants to recap a particular day's conversation and decisions

## L2: Detailed Specification

### Summary Structure

1. Items completed today
2. Items in progress
3. Important decisions and conclusions
4. Suggested to-dos for tomorrow

5. SKILL.md Format Reference

Frontmatter Field Table

Field	Required	Type	Description
`description`	Required	string	Skill purpose description; including a "Use when" trigger hint is recommended
`name`	Recommended	string	Skill display name
`version`	Recommended	string	Semantic version (e.g. `1.0.0`)
`type`	Recommended	enum	`procedural` / `conversational` / `meta`
`risk_level`	Recommended	enum	`low` / `medium` / `high`
`status`	Recommended	enum	`enabled` / `disabled`
`tags`	Optional	string[]	List of tags, used for search and categorization
`disable-model-invocation`	Optional	boolean	Must be `true` or omitted. Full-content auto-injection is prohibited; skills are loaded only when explicitly invoked via the Skill tool.
`requires`	Optional	object	Dependency declaration: `tools`, `optional_tools`, `connections`
`metadata`	Optional	object	Meta information: `author`, `updated_at`
`market`	Optional	object	Market display metadata (only required for Skills published to the Market)

type Description

Type	Meaning	Examples
`procedural`	Procedural; executed step by step	Data analysis flow, approval flow
`conversational`	Conversational; completed through multi-turn dialogue	Requirements gathering, brainstorming
`meta`	Meta-Skill that manages other resources	Creating Agents, managing Skills

Markdown Body Structure (L0 / L1 / L2)

Tier	Content	Purpose
L0	One-line summary	Quickly understand what the Skill does
L1	Capability + Use Cases + Core Value	Decide whether it applies
L2	Detailed specification: steps, APIs, formats, error handling	Concrete execution guide

6. Scope Notes

Skills exist at three scope levels, listed from highest priority to lowest:

Priority	Scope	Path	Visibility
Highest	Project	`.claude/skills/` (project root)	All Agents in the current project
Medium	Agent	`${DESIRECORE_ROOT}/agents/{agentId}/skills/`	Only that Agent
Lowest	Global	`${DESIRECORE_ROOT}/skills/`	All Agents

Same-name override rule: a Skill in a higher-priority scope overrides a same-named Skill in a lower-priority scope. For example, an Agent-scoped data-analysis Skill will shadow a global Skill of the same name.

7. Error Handling

Error code	Scenario	Handling
400	Missing required fields or invalid format	Prompt the user to check the input and explain which field is problematic
400	SKILL.md frontmatter validation failed	Show validation error details and guide the user to fix
404	Skill does not exist	Note the Skill ID may be misspelled, list available Skills
404	No SKILL.md in the Git repo	Note the repository's format does not match the Skill spec
409	Skill already exists (write conflict)	Suggest using PUT to update instead of POST to create
413	Remote file exceeds 20MB	Note the file is too large; suggest trimming the content
504	URL fetch timeout	Note the network timed out; suggest checking the URL or retrying later
500	Server internal error	Tell the user to retry later

8. Permission Notes

It is recommended to use the Bash tool to call the Agent Service HTTP API via curl
The API base address is already injected into the system prompt's "Local API" section; you can reference it directly
For import and create operations, show the user a preview first and proceed only after confirmation
Deletions require explicit user confirmation
When authoring Skills via AgentFS, simply use the Write tool to create the file

Background Knowledge

AgentFS repository structure, troubleshooting tips, and protected paths are detailed in _agentfs-background.md and _protected-paths.yaml.

Dependencies

Agent Service HTTP API (Skills route group)
The local API address declaration in the system prompt
Write / Edit tools (for the AgentFS direct-authoring scenario)

18 KiB Raw Blame History