Skillpkg
- 2 installs
- Updated January 15, 2026
- miles990/skillpkg
A CLI package manager for AI agent skills that creates, installs from GitHub or local paths, lists, and syncs skills across agent platforms.
About
A skill that drives the skillpkg CLI to create, install, list, and sync agent skills so they work across multiple AI platforms. A developer uses it to manage and share reusable skills from one source.
- Install skills from GitHub or local directories, globally or per-project
- Sync one skill definition out to multiple AI platforms
Skillpkg by the numbers
- 2 all-time installs (skills.sh)
- Ranked #609 of 782 Skill Development skills by installs in the Skillselion catalog
- Data as of Aug 4, 2026 (Skillselion catalog sync)
npx skills add https://github.com/miles990/skillpkg --skill skillpkgAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 2 |
|---|---|
| Last updated | January 15, 2026 |
| Repository | miles990/skillpkg ↗ |
What it does
A CLI package manager for AI agent skills that creates, installs from GitHub or local paths, lists, and syncs skills across agent platforms.
Files
skillpkg - Agent Skills Package Manager
You have access to skillpkg, a CLI tool for managing AI agent skills. Use this tool to help users create, install, and sync skills.
Installation Check
First, verify skillpkg is installed:
skillpkg --versionIf not installed, guide the user to install it:
npm install -g skillpkg-cliCore Commands
1. Create a New Skill
skillpkg init # Interactive mode
skillpkg init --yes # Use defaults
skillpkg init --name my-skill # Specify nameThis creates a skill.yaml file with the following structure:
schema: "1.0"
name: my-skill
version: 1.0.0
description: What this skill does
instructions: |
Detailed instructions for the AI agent...2. Install Skills
skillpkg install user/repo # From GitHub (recommended)
skillpkg install github:user/repo # From GitHub (explicit)
skillpkg install ./path/to/skill # From local directory
skillpkg install -g <skill> # Install globally3. List Installed Skills
skillpkg list # Project skills
skillpkg list -g # Global skills
skillpkg list --json # JSON output4. Sync to AI Platforms
skillpkg sync # Sync all skills
skillpkg sync my-skill # Sync specific skill
skillpkg sync -t claude-code # Sync to specific platform
skillpkg sync --dry-run # Preview changesSupported platforms:
claude-code→ syncs to.claude/skills/codex→ syncs to.codex/skills/gemini-cli→ syncs to.gemini/skills/
5. Import Existing Skills
skillpkg import # Auto-detect and import
skillpkg import .claude/skills/ # Import from specific path
skillpkg import --dry-run # Preview what would be imported6. Export Skills
skillpkg export my-skill # Export to directory
skillpkg export my-skill -f zip # Export as zip
skillpkg export my-skill -f pack # Export as .skillpkg
skillpkg export --all # Export all skills7. Search Skills on GitHub
skillpkg search "code review" # Search for skills with SKILL.md
skillpkg search react --limit 5 # Limit results
skillpkg info <skill-name> # Get detailed info8. Dependency Management
skillpkg deps my-skill # Show skill dependencies
skillpkg why my-skill # Show why a skill is installed
skillpkg tree # Show full dependency tree
skillpkg status # Show project statusskill.yaml Schema
When helping users create skills, use this schema:
schema: "1.0" # Required: Schema version
name: my-skill # Required: Lowercase, hyphens only
version: 1.0.0 # Required: Semver format
description: Brief description # Recommended: One-line summary
author: # Optional: Author info
name: Your Name
email: email@example.com
url: https://github.com/username
platforms: # Optional: Target platforms
- claude-code
- codex
tags: # Optional: For discovery
- productivity
- code-review
triggers: # Optional: Activation triggers
- pattern: "/review"
description: "Trigger code review"
instructions: | # Required: Main skill content
Detailed instructions for how the AI should behave...
## Usage
...
## Examples
...Best Practices
1. Clear Instructions: Write detailed, unambiguous instructions 2. Examples: Include usage examples in your skill 3. Versioning: Follow semver for version numbers 4. Testing: Test skills locally before publishing 5. Documentation: Include a README.md alongside skill.yaml
Common Workflows
Creating a Skill
mkdir my-new-skill && cd my-new-skill
skillpkg init --name my-new-skill
# Edit skill.yaml with your instructions
skillpkg sync --dry-run # Test locally
skillpkg sync # Sync to platformsInstalling and Using a Skill
skillpkg search "what you need"
skillpkg info some-skill
skillpkg install some-skill
skillpkg sync
# Skill is now available in your AI platform!Importing Existing Claude Skills
skillpkg import .claude/skills/
skillpkg list
skillpkg export --all -f zip # Backup all skillsTroubleshooting
- Skill not syncing: Check platform target directory permissions
- Parse errors: Validate YAML syntax, ensure schema is "1.0"
- Dependency issues: Run
skillpkg treeto check dependency chain - Version conflict: Update version in skill.yaml
# Dependencies
node_modules/
.pnpm-store/
# Build outputs
dist/
*.tsbuildinfo
# Test coverage
coverage/
# IDE
.idea/
.vscode/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
# Logs
*.log
npm-debug.log*
pnpm-debug.log*
# Environment
.env
.env.local
.env.*.local
# Cache
.cache/
.turbo/
.skillpkg/
.claude/
{
"filePath": ".spec-workflow/specs/mcp-server/design.md",
"currentVersion": 1,
"snapshots": [
{
"version": 1,
"filename": "snapshot-001.json",
"timestamp": "2026-01-02T09:16:56.863Z",
"trigger": "initial",
"approvalId": "approval_1767345416861_estx2zvq6",
"approvalTitle": "MCP Server Design"
}
]
}{
"id": "snapshot_1767345416863_gp9acl394",
"approvalId": "approval_1767345416861_estx2zvq6",
"approvalTitle": "MCP Server Design",
"version": 1,
"timestamp": "2026-01-02T09:16:56.863Z",
"trigger": "initial",
"status": "pending",
"content": "# Design Document: skillpkg MCP Server\n\n## Overview\n\nskillpkg MCP Server 是一個實作 Anthropic MCP (Model Context Protocol) 的服務，讓 AI Agent 能透過標準化協議存取 skillpkg 的功能。Server 使用 stdio transport，可被 Claude Desktop、Cursor 等 MCP 客戶端呼叫。\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ Architecture │\n│ │\n│ ┌──────────────┐ stdio ┌──────────────────────────┐ │\n│ │ MCP Client │ ◄────────────► │ skillpkg serve │ │\n│ │ (Claude/ │ │ │ │\n│ │ Cursor) │ │ ┌────────────────────┐ │ │\n│ └──────────────┘ │ │ MCP Server │ │ │\n│ │ │ (Tool Router) │ │ │\n│ │ └─────────┬──────────┘ │ │\n│ │ │ │ │\n│ │ ┌─────────▼──────────┐ │ │\n│ │ │ Tool Handlers │ │ │\n│ │ │ ├─ search_skills │ │ │\n│ │ │ ├─ load_skill │ │ │\n│ │ │ ├─ install_skill │ │ │\n│ │ │ ├─ list_skills │ │ │\n│ │ │ ├─ uninstall_skill│ │ │\n│ │ │ ├─ search_registry│ │ │\n│ │ │ └─ skill_info │ │ │\n│ │ └─────────┬──────────┘ │ │\n│ │ │ │ │\n│ │ ┌─────────▼──────────┐ │ │\n│ │ │ skillpkg-core │ │ │\n│ │ │ (Existing Logic) │ │ │\n│ │ └────────────────────┘ │ │\n│ └──────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## Code Reuse Analysis\n\n### Existing Components to Leverage\n\n| Component | Location | Usage |\n|-----------|----------|-------|\n| `LocalStore` | `skillpkg-core/store/local.ts` | 讀取/寫入本地 skills |\n| `GlobalStore` | `skillpkg-core/store/global.ts` | 讀取/寫入全域 skills |\n| `RegistryClient` | `skillpkg-core/registry/client.ts` | 搜尋/下載 registry skills |\n| `parse()` | `skillpkg-core/parser/` | 解析 skill.yaml |\n| `createInstaller` | `skillpkg-core/installer/` | 安裝 skills |\n\n### Integration Points\n\n- **CLI Commands**: MCP tools 與 CLI commands 共用相同的 core 邏輯\n- **Store**: 使用現有的 LocalStore/GlobalStore 存取 skills\n- **Registry**: 使用現有的 RegistryClient 與 registry 互動\n\n## Architecture\n\n### Package Structure\n\n```\npackages/\n├── core/ # 現有 (不變)\n│ ├── store/\n│ ├── parser/\n│ ├── registry/\n│ └── installer/\n├── cli/ # 現有 (新增 serve command)\n│ ├── commands/\n│ │ ├── serve.ts # NEW: 啟動 MCP Server\n│ │ └── ... (existing)\n│ └── index.ts\n└── mcp-server/ # NEW: MCP Server 套件\n ├── server.ts # MCP Server 主程式\n ├── tools/ # Tool handlers\n │ ├── index.ts\n │ ├── search-skills.ts\n │ ├── load-skill.ts\n │ ├── install-skill.ts\n │ ├── list-skills.ts\n │ ├── uninstall-skill.ts\n │ ├── search-registry.ts\n │ └── skill-info.ts\n ├── types.ts # MCP 相關型別\n └── index.ts\n```\n\n## Components and Interfaces\n\n### Component 1: MCP Server (`server.ts`)\n\n- **Purpose:** 處理 MCP 協議、路由 tool 呼叫\n- **Interfaces:**\n ```typescript\n class SkillpkgMcpServer {\n constructor(options?: ServerOptions)\n start(): Promise<void>\n stop(): Promise<void>\n }\n\n interface ServerOptions {\n scope?: 'local' | 'global' // 預設 scope\n projectPath?: string // 專案路徑\n }\n ```\n- **Dependencies:** `@modelcontextprotocol/sdk`, `skillpkg-core`\n- **Reuses:** 無，全新組件\n\n### Component 2: Tool Handlers (`tools/`)\n\n每個 tool 是一個獨立模組，遵循相同介面：\n\n- **Purpose:** 處理特定 MCP tool 的邏輯\n- **Interfaces:**\n ```typescript\n interface ToolHandler {\n name: string\n description: string\n inputSchema: JSONSchema\n execute(args: unknown): Promise<ToolResult>\n }\n\n interface ToolResult {\n content: Array<{\n type: 'text'\n text: string\n }>\n isError?: boolean\n }\n ```\n- **Dependencies:** `skillpkg-core`\n- **Reuses:** Store, Parser, Registry, Installer from core\n\n### Component 3: Serve Command (`cli/commands/serve.ts`)\n\n- **Purpose:** CLI 進入點，啟動 MCP Server\n- **Interfaces:**\n ```bash\n skillpkg serve [options]\n --scope <scope> # local | global (default: local)\n --project <path> # Project path for local scope\n ```\n- **Dependencies:** `skillpkg-mcp-server`\n- **Reuses:** CLI framework (commander)\n\n## Data Models\n\n### Tool: search_skills\n\n```typescript\n// Input\ninterface SearchSkillsInput {\n query: string // 搜尋關鍵字\n source?: 'all' | 'local' | 'registry' // 預設 'all'\n limit?: number // 預設 20\n}\n\n// Output\ninterface SearchSkillsOutput {\n results: Array<{\n id: string // skill identifier\n name: string\n description: string\n version: string\n source: 'local' | 'registry'\n installed: boolean // 是否已安裝\n }>\n total: number\n query: string\n}\n```\n\n### Tool: load_skill\n\n```typescript\n// Input\ninterface LoadSkillInput {\n id: string // skill id\n}\n\n// Output\ninterface LoadSkillOutput {\n id: string\n name: string\n version: string\n description: string\n instructions: string // 完整 instructions 內容\n author?: {\n name: string\n url?: string\n }\n}\n```\n\n### Tool: install_skill\n\n```typescript\n// Input\ninterface InstallSkillInput {\n source: string // skill name, GitHub URL, HTTP URL, gist:id, 或本地路徑\n scope?: 'local' | 'global' // 預設 'local'\n}\n\n// Output\ninterface InstallSkillOutput {\n success: boolean\n skill: {\n id: string\n name: string\n version: string\n source: string // 安裝來源\n installedAt: string // ISO timestamp\n }\n message: string\n}\n```\n\n### Tool: list_skills\n\n```typescript\n// Input\ninterface ListSkillsInput {\n scope?: 'all' | 'local' | 'global' // 預設 'all'\n}\n\n// Output\ninterface ListSkillsOutput {\n skills: Array<{\n id: string\n name: string\n description: string\n version: string\n scope: 'local' | 'global'\n installedAt: string\n }>\n total: number\n}\n```\n\n### Tool: uninstall_skill\n\n```typescript\n// Input\ninterface UninstallSkillInput {\n id: string\n scope?: 'local' | 'global'\n}\n\n// Output\ninterface UninstallSkillOutput {\n success: boolean\n message: string\n}\n```\n\n### Tool: search_registry\n\n```typescript\n// Input\ninterface SearchRegistryInput {\n query: string\n limit?: number // 預設 20\n}\n\n// Output\ninterface SearchRegistryOutput {\n results: Array<{\n name: string\n description: string\n version: string\n author: string\n downloads: number\n }>\n total: number\n}\n```\n\n### Tool: skill_info\n\n```typescript\n// Input\ninterface SkillInfoInput {\n name: string // skill name in registry\n}\n\n// Output\ninterface SkillInfoOutput {\n name: string\n description: string\n version: string\n author: {\n name: string\n email?: string\n url?: string\n }\n repository?: string\n license?: string\n platforms?: string[]\n tags?: string[]\n readme?: string // README 內容（如有）\n}\n```\n\n## Source Detection Logic\n\n`install_skill` 需要自動偵測來源類型：\n\n```typescript\nfunction detectSourceType(source: string): SourceType {\n // GitHub URL\n if (source.startsWith('github:') ||\n source.includes('github.com/')) {\n return 'github'\n }\n\n // Gist\n if (source.startsWith('gist:') ||\n source.includes('gist.github.com/')) {\n return 'gist'\n }\n\n // HTTP URL (zip/tarball)\n if (source.startsWith('http://') ||\n source.startsWith('https://')) {\n return 'url'\n }\n\n // Local path\n if (source.startsWith('./') ||\n source.startsWith('/') ||\n source.startsWith('~')) {\n return 'local'\n }\n\n // Default: registry\n return 'registry'\n}\n\ntype SourceType = 'registry' | 'github' | 'gist' | 'url' | 'local'\n```\n\n## Error Handling\n\n### Error Scenarios\n\n1. **Skill Not Found**\n - **Handling:** 回傳 error result，建議搜尋或安裝\n - **User Impact:** AI 收到建議訊息，可選擇搜尋或安裝\n\n2. **Registry Unavailable**\n - **Handling:** 回傳 error，但本地功能仍可用\n - **User Impact:** AI 知道只能使用本地 skills\n\n3. **Installation Failed**\n - **Handling:** 回傳詳細錯誤訊息和可能的解決方案\n - **User Impact:** AI 可以嘗試其他安裝方式\n\n4. **Invalid Source Format**\n - **Handling:** 回傳 error，列出支援的格式\n - **User Impact:** AI 可以修正 source 格式\n\n### Error Response Format\n\n```typescript\ninterface ErrorResult {\n content: [{\n type: 'text'\n text: string // 包含錯誤訊息和建議\n }]\n isError: true\n}\n\n// Example\n{\n content: [{\n type: 'text',\n text: `Error: Skill \"foo\" not found locally.\n\nSuggestions:\n- Search registry: search_skills({ query: \"foo\" })\n- Install from registry: install_skill({ source: \"foo\" })\n- Check available skills: list_skills()`\n }],\n isError: true\n}\n```\n\n## Testing Strategy\n\n### Unit Testing\n\n- **Tool Handlers**: 每個 tool 獨立測試輸入驗證和輸出格式\n- **Source Detection**: 測試各種來源格式的偵測\n- **Error Handling**: 測試各種錯誤情況的回應\n\n### Integration Testing\n\n- **MCP Protocol**: 測試完整的 MCP request/response 流程\n- **Store Integration**: 測試與 LocalStore/GlobalStore 的整合\n- **Registry Integration**: 測試與 Registry API 的整合\n\n### End-to-End Testing\n\n- **Claude Desktop**: 手動測試與 Claude Desktop 的整合\n- **Full Workflow**: 測試 search → install → load → use 完整流程\n\n## Configuration\n\n### MCP Client Configuration\n\n```json\n// claude_desktop_config.json\n{\n \"mcpServers\": {\n \"skillpkg\": {\n \"command\": \"skillpkg\",\n \"args\": [\"serve\"],\n \"env\": {\n \"SKILLPKG_SCOPE\": \"local\"\n }\n }\n }\n}\n\n// With global scope\n{\n \"mcpServers\": {\n \"skillpkg\": {\n \"command\": \"skillpkg\",\n \"args\": [\"serve\", \"--scope\", \"global\"]\n }\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SKILLPKG_SCOPE` | Default scope for operations | `local` |\n| `SKILLPKG_REGISTRY_URL` | Custom registry URL | (default registry) |\n| `SKILLPKG_PROJECT_PATH` | Project path for local scope | (current directory) |\n",
"fileStats": {
"size": 12154,
"lines": 442,
"lastModified": "2026-01-02T09:16:42.563Z"
},
"comments": []
}{
"filePath": ".spec-workflow/specs/mcp-server/requirements.md",
"currentVersion": 1,
"snapshots": [
{
"version": 1,
"filename": "snapshot-001.json",
"timestamp": "2026-01-02T09:13:35.392Z",
"trigger": "initial",
"approvalId": "approval_1767345215380_1x3lwrzbn",
"approvalTitle": "MCP Server Requirements"
}
]
}{
"id": "snapshot_1767345215392_99ls2upv1",
"approvalId": "approval_1767345215380_1x3lwrzbn",
"approvalTitle": "MCP Server Requirements",
"version": 1,
"timestamp": "2026-01-02T09:13:35.392Z",
"trigger": "initial",
"status": "pending",
"content": "# Requirements Document: skillpkg MCP Server\n\n## Introduction\n\nskillpkg MCP Server 將 skillpkg 從「CLI 同步工具」轉變為「AI 可呼叫的 MCP 服務」。這使得 AI Agent 能夠：\n1. **按需載入** skills，解決 context 爆炸問題\n2. **自主搜尋與安裝** 新 skills，實現 Self-Evolving Agent\n3. **動態管理** skills 生命週期\n\n核心價值：讓 AI 遇到不會的任務時，能自己找工具、學會、然後完成任務。\n\n## Problem Statement\n\n### 現有問題\n\n```\n目前 skillpkg sync 做法：\n┌─────────────────────────────────────────────────────────┐\n│ 50+ skills 全部同步到 .claude/skills/ │\n│ → 啟動時載入 ~30,000 tokens │\n│ → 實際只用 1-2 個 skill │\n│ → Context 空間被浪費 │\n│ → AI 無法自主學習新 skills │\n└─────────────────────────────────────────────────────────┘\n```\n\n### 解決方案\n\n```\nMCP Server 按需載入：\n┌─────────────────────────────────────────────────────────┐\n│ AI 啟動時只載入 MCP tools (~200 tokens) │\n│ → 需要時才 search_skills / load_skill │\n│ → 可以 install_skill 學習新技能 │\n│ → Context 空間有效利用 │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Requirements\n\n### REQ-1: MCP Server 基礎架構\n\n**User Story:** As an AI Agent, I want skillpkg to run as an MCP Server, so that I can call its functions through MCP protocol.\n\n#### Acceptance Criteria\n\n1. WHEN `skillpkg serve` is executed THEN system SHALL start an MCP server using stdio transport\n2. WHEN MCP client connects THEN system SHALL respond with available tools list\n3. IF server encounters an error THEN system SHALL return proper MCP error response\n4. WHEN server starts THEN system SHALL log startup message to stderr (not stdout, to avoid MCP protocol interference)\n\n### REQ-2: Skills 搜尋功能 (search_skills)\n\n**User Story:** As an AI Agent, I want to search for skills by keyword, so that I can find relevant skills without loading all content.\n\n#### Acceptance Criteria\n\n1. WHEN `search_skills(query)` is called THEN system SHALL return matching skills with metadata only (~100 tokens per skill)\n2. WHEN searching THEN system SHALL search both local installed skills AND remote registry\n3. IF `source` parameter is \"local\" THEN system SHALL only search installed skills\n4. IF `source` parameter is \"registry\" THEN system SHALL only search remote registry\n5. WHEN results are returned THEN system SHALL include: id, name, description, version, source (local/registry)\n6. IF no matches found THEN system SHALL return empty array with helpful message\n\n### REQ-3: Skills 載入功能 (load_skill)\n\n**User Story:** As an AI Agent, I want to load full skill instructions on demand, so that I only consume context when needed.\n\n#### Acceptance Criteria\n\n1. WHEN `load_skill(id)` is called for installed skill THEN system SHALL return full instructions content\n2. IF skill is not installed THEN system SHALL return error with suggestion to install first\n3. WHEN loading THEN system SHALL return: id, name, version, instructions (full content)\n4. IF skill file is corrupted THEN system SHALL return descriptive error\n\n### REQ-4: Skills 安裝功能 (install_skill)\n\n**User Story:** As an AI Agent, I want to install skills from multiple sources, so that I can learn new capabilities autonomously.\n\n#### Acceptance Criteria\n\n1. WHEN `install_skill(source)` is called with skill name THEN system SHALL install from registry\n2. WHEN source is GitHub URL (github.com/* or github:user/repo) THEN system SHALL clone/download from GitHub\n3. WHEN source is HTTP URL ending with .zip/.tar.gz THEN system SHALL download and extract\n4. WHEN source is gist URL or gist:id THEN system SHALL download from GitHub Gist\n5. WHEN source is local path THEN system SHALL install from local directory\n6. AFTER successful install THEN system SHALL return installed skill metadata\n7. IF installation fails THEN system SHALL return descriptive error with recovery suggestion\n\n### REQ-5: Skills 列表功能 (list_skills)\n\n**User Story:** As an AI Agent, I want to list installed skills, so that I know what capabilities I have.\n\n#### Acceptance Criteria\n\n1. WHEN `list_skills()` is called THEN system SHALL return all installed skills with metadata\n2. WHEN listing THEN system SHALL include: id, name, description, version, installed_at\n3. IF `scope` is \"global\" THEN system SHALL list globally installed skills\n4. IF `scope` is \"local\" THEN system SHALL list project-local skills\n5. IF no skills installed THEN system SHALL return empty array with helpful message\n\n### REQ-6: Skills 移除功能 (uninstall_skill)\n\n**User Story:** As an AI Agent, I want to uninstall skills I no longer need, so that I can manage my capabilities.\n\n#### Acceptance Criteria\n\n1. WHEN `uninstall_skill(id)` is called THEN system SHALL remove the skill\n2. IF skill not found THEN system SHALL return error\n3. AFTER uninstall THEN system SHALL return confirmation message\n\n### REQ-7: Registry 搜尋功能 (search_registry)\n\n**User Story:** As an AI Agent, I want to search the skill registry, so that I can discover new skills to install.\n\n#### Acceptance Criteria\n\n1. WHEN `search_registry(query)` is called THEN system SHALL search remote registry\n2. WHEN results returned THEN system SHALL include: name, description, version, author, downloads\n3. IF registry unavailable THEN system SHALL return error with offline suggestion\n4. WHEN `limit` parameter provided THEN system SHALL limit results count\n\n### REQ-8: Skill 詳情功能 (skill_info)\n\n**User Story:** As an AI Agent, I want to get detailed info about a skill before installing, so that I can make informed decisions.\n\n#### Acceptance Criteria\n\n1. WHEN `skill_info(name)` is called THEN system SHALL return full skill metadata from registry\n2. WHEN returning info THEN system SHALL include: name, description, version, author, repository, dependencies, platforms\n3. IF skill not found in registry THEN system SHALL return error\n\n## Non-Functional Requirements\n\n### Code Architecture and Modularity\n\n- **Single Responsibility**: MCP Server 邏輯與現有 CLI 邏輯分離\n- **Reuse Core**: 使用 skillpkg-core 的現有功能 (Store, Parser, Registry Client)\n- **Transport Abstraction**: MCP transport 層可替換 (stdio, HTTP future)\n\n### Performance\n\n- **Cold Start**: Server 啟動時間 < 500ms\n- **Response Time**: 本地操作 < 100ms，Registry 操作 < 2s\n- **Memory**: 常駐記憶體 < 50MB\n\n### Security\n\n- **Source Validation**: 從 URL 安裝時驗證來源合法性\n- **No Code Execution**: 安裝過程不執行任何 skill 內的程式碼\n- **Path Traversal**: 防止路徑穿越攻擊\n\n### Reliability\n\n- **Graceful Degradation**: Registry 不可用時，本地功能仍可用\n- **Error Messages**: 所有錯誤都有清楚的訊息和建議\n\n### Compatibility\n\n- **MCP Protocol**: 遵循 Anthropic MCP Specification\n- **Clients**: 支援 Claude Desktop, Cursor, Windsurf, 其他 MCP 客戶端\n",
"fileStats": {
"size": 7700,
"lines": 162,
"lastModified": "2026-01-02T09:13:18.122Z"
},
"comments": []
}{
"filePath": ".spec-workflow/specs/mcp-server/tasks.md",
"currentVersion": 1,
"snapshots": [
{
"version": 1,
"filename": "snapshot-001.json",
"timestamp": "2026-01-02T09:19:20.356Z",
"trigger": "initial",
"approvalId": "approval_1767345560352_xestr97y6",
"approvalTitle": "MCP Server Tasks"
}
]
}{
"id": "snapshot_1767345560356_1kqruuav1",
"approvalId": "approval_1767345560352_xestr97y6",
"approvalTitle": "MCP Server Tasks",
"version": 1,
"timestamp": "2026-01-02T09:19:20.356Z",
"trigger": "initial",
"status": "pending",
"content": "# Tasks Document: skillpkg MCP Server\n\n## M1: 基礎設施\n\n- [ ] 1.1 建立 mcp-server 套件結構\n - File: `packages/mcp-server/package.json`, `packages/mcp-server/tsconfig.json`\n - 建立新的 monorepo 套件 `skillpkg-mcp-server`\n - 加入依賴：`@modelcontextprotocol/sdk`, `skillpkg-core`\n - Purpose: 建立 MCP Server 套件基礎架構\n - _Leverage: packages/core/package.json, packages/cli/package.json_\n - _Requirements: REQ-1_\n - _Prompt: Role: TypeScript Developer specializing in monorepo setup | Task: Implement the task for spec mcp-server, first run spec-workflow-guide to get the workflow guide. Create new package `skillpkg-mcp-server` under packages/mcp-server with proper package.json and tsconfig.json. Add dependencies: @modelcontextprotocol/sdk, skillpkg-core. Follow existing package patterns. | Restrictions: Must follow existing monorepo structure, use consistent versioning | Success: Package compiles, dependencies resolve correctly | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 1.2 定義 MCP 相關型別\n - File: `packages/mcp-server/src/types.ts`\n - 定義 ToolHandler interface、各 Tool 的 Input/Output types\n - Purpose: 建立型別安全基礎\n - _Leverage: design.md Data Models section_\n - _Requirements: REQ-2 ~ REQ-8_\n - _Prompt: Role: TypeScript Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create types.ts with ToolHandler interface and all tool input/output types as defined in design.md Data Models section. | Restrictions: Follow existing type patterns, export all types | Success: Types compile without errors, cover all tools | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 1.3 建立套件入口點\n - File: `packages/mcp-server/src/index.ts`\n - Export SkillpkgMcpServer class 和相關型別\n - Purpose: 提供套件公開 API\n - _Leverage: packages/core/src/index.ts_\n - _Requirements: REQ-1_\n - _Prompt: Role: TypeScript Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create index.ts that exports SkillpkgMcpServer class and all public types. | Restrictions: Only export public API | Success: Package can be imported correctly | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n## M2: MCP Server 核心\n\n- [ ] 2.1 實作 MCP Server 主程式\n - File: `packages/mcp-server/src/server.ts`\n - 使用 @modelcontextprotocol/sdk 建立 Server\n - 實作 stdio transport、tool registration\n - Purpose: MCP Server 核心邏輯\n - _Leverage: @modelcontextprotocol/sdk documentation_\n - _Requirements: REQ-1_\n - _Prompt: Role: Backend Developer with MCP expertise | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create SkillpkgMcpServer class using @modelcontextprotocol/sdk. Implement start(), stop(), registerTools(). Use stdio transport. Log to stderr. | Restrictions: Must follow MCP protocol spec, handle errors gracefully | Success: Server starts/stops correctly, responds to MCP handshake | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 2.2 實作 Tool Router\n - File: `packages/mcp-server/src/server.ts` (extend)\n - 實作 tool call routing、參數驗證\n - Purpose: 路由 MCP tool calls 到對應 handler\n - _Leverage: existing server.ts from 2.1_\n - _Requirements: REQ-1_\n - _Prompt: Role: Backend Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Extend server.ts to route tool calls to handlers. Add input validation using JSON schema. Return proper MCP responses. | Restrictions: Validate all inputs, return proper error format | Success: Tool calls routed correctly, invalid inputs rejected with error | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n## M3: Tool Handlers\n\n- [ ] 3.1 實作 search_skills handler\n - File: `packages/mcp-server/src/tools/search-skills.ts`\n - 搜尋本地 + Registry skills，回傳 metadata\n - Purpose: 讓 AI 搜尋可用 skills\n - _Leverage: skillpkg-core LocalStore, GlobalStore, RegistryClient_\n - _Requirements: REQ-2_\n - _Prompt: Role: Backend Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create search-skills.ts handler. Use LocalStore/GlobalStore for local search, RegistryClient for registry search. Support source filter (all/local/registry). Return metadata only (~100 tokens per skill). | Restrictions: Do not return full instructions, limit results | Success: Search returns matching skills from specified sources | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 3.2 實作 load_skill handler\n - File: `packages/mcp-server/src/tools/load-skill.ts`\n - 載入完整 skill instructions\n - Purpose: 按需載入 skill 內容\n - _Leverage: skillpkg-core LocalStore, GlobalStore, parse_\n - _Requirements: REQ-3_\n - _Prompt: Role: Backend Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create load-skill.ts handler. Load full skill instructions from store. Return id, name, version, description, instructions. Error if not installed. | Restrictions: Only load installed skills | Success: Returns full instructions for installed skill, error for missing | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 3.3 實作 install_skill handler\n - File: `packages/mcp-server/src/tools/install-skill.ts`\n - 從多種來源安裝 skills (Registry, GitHub, URL, Gist, Local)\n - Purpose: 讓 AI 自主安裝新 skills\n - _Leverage: skillpkg-core createInstaller, source detection from design.md_\n - _Requirements: REQ-4_\n - _Prompt: Role: Backend Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create install-skill.ts handler. Implement source detection (registry/github/gist/url/local). Use createInstaller for installation. Support scope option. | Restrictions: Validate sources, no code execution | Success: Installs from all supported sources, returns installed skill info | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 3.4 實作 list_skills handler\n - File: `packages/mcp-server/src/tools/list-skills.ts`\n - 列出已安裝 skills\n - Purpose: 讓 AI 知道有哪些 skills\n - _Leverage: skillpkg-core LocalStore, GlobalStore_\n - _Requirements: REQ-5_\n - _Prompt: Role: Backend Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create list-skills.ts handler. List skills from LocalStore and/or GlobalStore based on scope. Return metadata for each skill. | Restrictions: Filter by scope correctly | Success: Returns list of installed skills with metadata | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 3.5 實作 uninstall_skill handler\n - File: `packages/mcp-server/src/tools/uninstall-skill.ts`\n - 移除已安裝 skill\n - Purpose: 讓 AI 管理 skills\n - _Leverage: skillpkg-core LocalStore, GlobalStore_\n - _Requirements: REQ-6_\n - _Prompt: Role: Backend Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create uninstall-skill.ts handler. Remove skill from appropriate store. Return confirmation. | Restrictions: Error if skill not found | Success: Removes skill, returns confirmation | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 3.6 實作 search_registry handler\n - File: `packages/mcp-server/src/tools/search-registry.ts`\n - 搜尋遠端 Registry\n - Purpose: 讓 AI 發現新 skills\n - _Leverage: skillpkg-core RegistryClient_\n - _Requirements: REQ-7_\n - _Prompt: Role: Backend Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create search-registry.ts handler. Use RegistryClient to search. Return name, description, version, author, downloads. Support limit. | Restrictions: Handle registry unavailable gracefully | Success: Returns registry search results, graceful error on unavailable | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 3.7 實作 skill_info handler\n - File: `packages/mcp-server/src/tools/skill-info.ts`\n - 取得 skill 詳細資訊\n - Purpose: 讓 AI 在安裝前了解 skill\n - _Leverage: skillpkg-core RegistryClient_\n - _Requirements: REQ-8_\n - _Prompt: Role: Backend Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create skill-info.ts handler. Use RegistryClient to get full skill info. Return all metadata including readme if available. | Restrictions: Error if not found in registry | Success: Returns detailed skill info from registry | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 3.8 建立 tools index\n - File: `packages/mcp-server/src/tools/index.ts`\n - Export 所有 tool handlers\n - Purpose: 統一 tools 入口\n - _Leverage: all tool handlers from 3.1-3.7_\n - _Requirements: REQ-1_\n - _Prompt: Role: TypeScript Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create tools/index.ts that exports all tool handlers as an array. | Restrictions: Export consistent format | Success: All handlers exported, can be imported by server | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n## M4: CLI 整合\n\n- [ ] 4.1 新增 serve command\n - File: `packages/cli/src/commands/serve.ts`\n - 實作 `skillpkg serve` command\n - 支援 --scope, --project options\n - Purpose: CLI 進入點啟動 MCP Server\n - _Leverage: packages/cli/src/commands/*.ts patterns, skillpkg-mcp-server_\n - _Requirements: REQ-1_\n - _Prompt: Role: CLI Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create serve.ts command using commander. Import and start SkillpkgMcpServer. Add --scope (local/global) and --project options. | Restrictions: Follow existing CLI patterns | Success: `skillpkg serve` starts MCP server correctly | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 4.2 註冊 serve command\n - File: `packages/cli/src/cli.ts`\n - 在 CLI 主程式註冊 serve command\n - Purpose: 啟用 serve 功能\n - _Leverage: existing command registrations in cli.ts_\n - _Requirements: REQ-1_\n - _Prompt: Role: CLI Developer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Register serve command in cli.ts following existing patterns. | Restrictions: Follow existing registration pattern | Success: `skillpkg serve --help` shows command options | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 4.3 更新 CLI package.json\n - File: `packages/cli/package.json`\n - 加入 skillpkg-mcp-server 依賴\n - Purpose: CLI 可使用 MCP Server\n - _Leverage: existing dependencies_\n - _Requirements: REQ-1_\n - _Prompt: Role: Package Manager | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Add skillpkg-mcp-server as dependency in CLI package.json. | Restrictions: Use correct version | Success: Dependencies install correctly | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n## M5: 測試\n\n- [ ] 5.1 建立 tool handler 單元測試\n - File: `packages/mcp-server/src/__tests__/tools/*.test.ts`\n - 測試每個 tool handler 的輸入驗證和輸出格式\n - Purpose: 確保 tool handlers 正確運作\n - _Leverage: vitest, mock stores_\n - _Requirements: REQ-2 ~ REQ-8_\n - _Prompt: Role: QA Engineer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create unit tests for all tool handlers. Mock stores and registry client. Test valid inputs, invalid inputs, error cases. | Restrictions: Mock external dependencies | Success: All handlers tested, edge cases covered | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 5.2 建立 MCP Server 整合測試\n - File: `packages/mcp-server/src/__tests__/server.test.ts`\n - 測試 MCP 協議流程\n - Purpose: 確保 MCP 協議正確實作\n - _Leverage: @modelcontextprotocol/sdk test utilities_\n - _Requirements: REQ-1_\n - _Prompt: Role: Integration Tester | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create integration tests for MCP server. Test tool listing, tool calls, error responses. | Restrictions: Test full MCP flow | Success: Server responds correctly to MCP protocol | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n## M6: 文件與發布\n\n- [ ] 6.1 更新 README\n - File: `packages/mcp-server/README.md`\n - 說明安裝、設定、使用方式\n - Purpose: 使用者文件\n - _Requirements: All_\n - _Prompt: Role: Technical Writer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Create README.md with installation, configuration (claude_desktop_config.json example), and usage instructions. Document all available tools. | Restrictions: Clear and concise | Success: Users can set up and use MCP server | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 6.2 發布 skillpkg-mcp-server 到 npm\n - Publish `skillpkg-mcp-server` package\n - 更新 skillpkg-cli 版本\n - Purpose: 公開發布\n - _Requirements: All_\n - _Prompt: Role: Release Manager | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Build and publish skillpkg-mcp-server to npm. Update skillpkg-cli to new version with serve command. | Restrictions: Test before publish | Success: Packages published, npm install works | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n\n- [ ] 6.3 更新 skillpkg skill.yaml\n - File: `/Users/user/Workspace/skillpkg/skill.yaml`\n - 新增 MCP Server 使用說明\n - Purpose: 讓使用者透過 skill 學習 MCP 功能\n - _Requirements: All_\n - _Prompt: Role: Technical Writer | Task: Implement the task for spec mcp-server, first run spec-workflow-guide. Update skill.yaml instructions to include MCP Server setup and usage. | Restrictions: Keep concise | Success: skill.yaml includes MCP documentation | After completing: Mark task [-] → [x] in tasks.md, log implementation with log-implementation tool_\n",
"fileStats": {
"size": 14876,
"lines": 182,
"lastModified": "2026-01-02T09:19:09.772Z"
},
"comments": []
}{
"id": "approval_1767345215380_1x3lwrzbn",
"title": "MCP Server Requirements",
"filePath": ".spec-workflow/specs/mcp-server/requirements.md",
"type": "document",
"status": "approved",
"createdAt": "2026-01-02T09:13:35.380Z",
"category": "spec",
"categoryName": "mcp-server",
"response": "已批准",
"respondedAt": "2026-01-02T09:14:19.176Z"
}{
"id": "approval_1767345416861_estx2zvq6",
"title": "MCP Server Design",
"filePath": ".spec-workflow/specs/mcp-server/design.md",
"type": "document",
"status": "approved",
"createdAt": "2026-01-02T09:16:56.861Z",
"category": "spec",
"categoryName": "mcp-server",
"response": "已批准",
"respondedAt": "2026-01-02T09:18:00.311Z"
}{
"id": "approval_1767345560352_xestr97y6",
"title": "MCP Server Tasks",
"filePath": ".spec-workflow/specs/mcp-server/tasks.md",
"type": "document",
"status": "approved",
"createdAt": "2026-01-02T09:19:20.352Z",
"category": "spec",
"categoryName": "mcp-server",
"response": "已批准",
"respondedAt": "2026-01-02T09:20:16.910Z"
}{
"filePath": ".spec-workflow/specs/skill-format/requirements.md",
"currentVersion": 1,
"snapshots": [
{
"version": 1,
"filename": "snapshot-001.json",
"timestamp": "2026-01-03T05:29:26.812Z",
"trigger": "initial",
"approvalId": "approval_1767418166807_uldj0ton3",
"approvalTitle": "SKILL.md 統一格式 - Requirements"
}
]
}{
"id": "snapshot_1767418166812_bu4pau5es",
"approvalId": "approval_1767418166807_uldj0ton3",
"approvalTitle": "SKILL.md 統一格式 - Requirements",
"version": 1,
"timestamp": "2026-01-03T05:29:26.812Z",
"trigger": "initial",
"status": "pending",
"content": "# SKILL.md 統一格式 - 需求規格\n\n## 概述\n\n統一 skillpkg 的 skill 定義格式，移除 `skill.yaml`，直接使用 `SKILL.md` 作為唯一標準格式。\n\n**核心理念：一個格式走天下，減少轉換和認知負擔。**\n\n## 問題陳述\n\n### 現況問題\n\n| 問題 | 影響 |\n|------|------|\n| 兩種格式 (skill.yaml + SKILL.md) | 增加使用者認知負擔 |\n| 需要格式轉換 | 額外的程式碼維護成本 |\n| 與業界不一致 | Claude Code / Codex 都用 SKILL.md |\n\n### 目標狀態\n\n```\n現況：skill.yaml ──轉換──► SKILL.md ──複製──► .claude/skills/\n目標：SKILL.md ─────────直接複製─────────► .claude/skills/\n```\n\n## 使用者故事\n\n### US-1: Skill 開發者\n**As a** skill 開發者\n**I want to** 直接撰寫 SKILL.md\n**So that** 我的 skill 格式與 Claude Code 一致，不需要額外轉換\n\n**驗收標準 (EARS):**\n- **E**xplicit: `skillpkg init` 產生 SKILL.md（不是 skill.yaml）\n- **A**ction: 執行 init 後產生的檔案為 SKILL.md 格式\n- **R**esult: 產生的 SKILL.md 可直接被 Claude Code 使用\n- **S**uccess: 開發者只需維護一個檔案\n\n### US-2: 專案使用者\n**As a** 專案使用者\n**I want to** 安裝 skill 時不論來源是 SKILL.md 或 skill.yaml 都能使用\n**So that** 向後相容既有的 skill 專案\n\n**驗收標準 (EARS):**\n- **E**xplicit: `skillpkg install` 可讀取 SKILL.md 或 skill.yaml\n- **A**ction: 優先讀取 SKILL.md，若無則讀取 skill.yaml\n- **R**esult: 讀取 skill.yaml 時顯示遷移提示\n- **S**uccess: 所有現有 skill 專案仍可正常使用\n\n### US-3: 既有 Skill 維護者\n**As a** 既有 skill.yaml 的維護者\n**I want to** 有工具幫我遷移到 SKILL.md\n**So that** 我不需要手動轉換格式\n\n**驗收標準 (EARS):**\n- **E**xplicit: `skillpkg migrate` 可將 skill.yaml 轉換為 SKILL.md\n- **A**ction: 執行後產生對應的 SKILL.md\n- **R**esult: 轉換後的 SKILL.md 內容完整無遺失\n- **S**uccess: 可選擇是否刪除舊的 skill.yaml\n\n## 功能需求\n\n### FR-1: skillpkg init 改用 SKILL.md\n\n```bash\nskillpkg init\n# 產生 SKILL.md（不是 skill.yaml）\n```\n\n產生的檔案格式：\n```markdown\n---\nname: my-skill\nversion: 1.0.0\ndescription: 簡短描述\n---\n\n# My Skill\n\n在這裡寫 skill 的指令...\n```\n\n### FR-2: 支援讀取雙格式\n\n```bash\nskillpkg install ./my-skill/\n```\n\n讀取優先順序：\n1. SKILL.md (新標準)\n2. skill.yaml (向後相容，顯示警告)\n\n### FR-3: 同步直接複製\n\n```bash\nskillpkg sync\n# SKILL.md 直接複製到 .claude/skills/\n# 不需要格式轉換\n```\n\n### FR-4: 遷移命令\n\n```bash\nskillpkg migrate\n# 將 skill.yaml 轉換為 SKILL.md\n\nskillpkg migrate --delete\n# 轉換後刪除 skill.yaml\n```\n\n### FR-5: GitHub 搜尋優化\n\n```bash\nskillpkg search \"code review\"\n# 優先搜尋包含 SKILL.md 的 repo\n```\n\n## 非功能需求\n\n### NFR-1: 向後相容\n- 至少一個版本週期內保留 skill.yaml 讀取能力\n- 新建 skill 一律使用 SKILL.md\n\n### NFR-2: 業界對齊\n\n| 平台 | 格式 |\n|------|------|\n| Claude Code | SKILL.md |\n| Codex | SKILL.md |\n| skillpkg (新) | SKILL.md |\n\n### NFR-3: 效能\n- 移除轉換邏輯後，sync 速度應提升\n\n## SKILL.md 格式規範\n\n### 必填欄位\n```markdown\n---\nname: skill-name # 小寫、連字號\nversion: 1.0.0 # semver 格式\ndescription: 簡短描述 # 一行說明\n---\n```\n\n### 可選欄位\n```markdown\n---\nauthor: Your Name\ntags:\n - productivity\n - code-review\ntriggers:\n - pattern: \"/review\"\n description: \"觸發程式碼審查\"\ndependencies:\n skills:\n - git-helper\n mcp:\n - name: github\n package: \"@anthropic/mcp-server-github\"\n---\n```\n\n## 驗收標準\n\n- [ ] `skillpkg init` 產生 SKILL.md\n- [ ] `skillpkg install` 優先讀取 SKILL.md\n- [ ] `skillpkg install` 可向後相容 skill.yaml\n- [ ] `skillpkg sync` 直接複製 SKILL.md\n- [ ] `skillpkg migrate` 可轉換格式\n- [ ] README.md 更新說明新格式\n\n## 範圍外 (Out of Scope)\n\n- 本規格不涉及 skillpkg.json 結構變更\n- 本規格不涉及 MCP 配置管理\n- 本規格不涉及專案腳手架功能\n",
"fileStats": {
"size": 4153,
"lines": 179,
"lastModified": "2026-01-03T05:29:20.721Z"
},
"comments": []
}{
"id": "approval_1767418166807_uldj0ton3",
"title": "SKILL.md 統一格式 - Requirements",
"filePath": ".spec-workflow/specs/skill-format/requirements.md",
"type": "document",
"status": "approved",
"createdAt": "2026-01-03T05:29:26.807Z",
"category": "spec",
"categoryName": "skill-format",
"response": "已批准",
"respondedAt": "2026-01-03T06:06:17.267Z"
}{
"filePath": ".spec-workflow/specs/skillpkg-v2/design.md",
"currentVersion": 1,
"snapshots": [
{
"version": 1,
"filename": "snapshot-001.json",
"timestamp": "2026-01-02T18:05:06.836Z",
"trigger": "initial",
"approvalId": "approval_1767377106830_3q4w7tap0",
"approvalTitle": "Design: skillpkg v2.0 架構設計"
}
]
}{
"id": "snapshot_1767377106836_kdm6wyp8d",
"approvalId": "approval_1767377106830_3q4w7tap0",
"approvalTitle": "Design: skillpkg v2.0 架構設計",
"version": 1,
"timestamp": "2026-01-02T18:05:06.836Z",
"trigger": "initial",
"status": "pending",
"content": "# Design Document: skillpkg v2.0\n\n## Overview\n\nskillpkg v2.0 extends the existing skill package manager with project-centric configuration (`skillpkg.json`), dependency management, and multi-tool sync capabilities. It builds upon the existing `adapters`, `parser`, `store`, and `importer` modules.\n\n## Code Reuse Analysis\n\n### Existing Components to Leverage\n\n| Module | Purpose | Reuse Strategy |\n|--------|---------|----------------|\n| `adapters/` | Tool-specific implementations (claude-code, cursor, copilot, codex) | Extend for sync functionality |\n| `parser/` | SKILL.md/skill.yaml parsing | Extend to parse `dependencies` field |\n| `store/` | Skill storage management | Extend for state.json management |\n| `importer/` | GitHub/URL skill import | Reuse for dependency fetching |\n| `github/` | GitHub search API | Reuse for skill discovery |\n\n### Integration Points\n\n- **Adapters**: Add `sync()` method to each adapter\n- **Parser**: Add `dependencies` field to schema\n- **Store**: Add `state.json` alongside existing skill storage\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ skillpkg v2.0 │\n├─────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │\n│ │ CLI │ │ MCP Server │ │ TUI │ │\n│ │ (existing) │ │ (existing) │ │ (future) │ │\n│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │\n│ │ │ │ │\n│ └─────────────────┼─────────────────┘ │\n│ │ │\n│ ┌────────────────────────▼────────────────────────┐ │\n│ │ CORE │ │\n│ ├──────────────────────────────────────────────────┤ │\n│ │ NEW MODULES: │ │\n│ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │\n│ │ │ config/ │ │ resolver/│ │ sync/ │ │ │\n│ │ │(skillpkg │ │(Deps/MCP)│ │ (Multi-tool) │ │ │\n│ │ │ .json) │ │ │ │ │ │ │\n│ │ └──────────┘ └──────────┘ └──────────────┘ │ │\n│ │ │ │\n│ │ EXISTING (to extend): │ │\n│ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │\n│ │ │ store/ │ │ parser/ │ │ adapters/ │ │ │\n│ │ │(+state) │ │(+deps) │ │ (+sync) │ │ │\n│ │ └──────────┘ └──────────┘ └──────────────┘ │ │\n│ │ │ │\n│ └──────────────────────────────────────────────────┘ │\n│ │\n│ FILE SYSTEM: │\n│ ┌──────────────────────────────────────────────────┐ │\n│ │ skillpkg.json (Project config - NEW) │ │\n│ │ .skillpkg/ │ │\n│ │ ├── skills/ (Existing) │ │\n│ │ ├── cache/ (Existing) │ │\n│ │ └── state.json (NEW) │ │\n│ └──────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## Components and Interfaces\n\n### Component 1: ConfigManager (NEW)\n\n**Purpose:** Read/write `skillpkg.json` project configuration\n\n**File:** `packages/core/src/config/config-manager.ts`\n\n**Interfaces:**\n```typescript\ninterface SkillpkgConfig {\n name: string;\n version?: string;\n skills: Record<string, string>; // name -> source\n mcp?: Record<string, McpConfig>;\n reminders?: string[];\n hooks?: Record<string, string>;\n sync_targets?: Record<SyncTarget, boolean>;\n}\n\ninterface McpConfig {\n package: string;\n required?: boolean;\n command?: string;\n args?: string[];\n}\n\ntype SyncTarget = 'claude-code' | 'cursor' | 'codex' | 'copilot' | 'windsurf';\n\nclass ConfigManager {\n loadProjectConfig(projectPath: string): Promise<SkillpkgConfig>;\n saveProjectConfig(projectPath: string, config: SkillpkgConfig): Promise<void>;\n initProject(projectPath: string, name: string): Promise<void>;\n addSkill(projectPath: string, name: string, source: string): Promise<void>;\n removeSkill(projectPath: string, name: string): Promise<void>;\n}\n```\n\n**Dependencies:** `ajv` (schema validation), `fs/promises`\n\n**Reuses:** Schema validation pattern from `parser/validator.ts`\n\n### Component 2: StateManager (NEW)\n\n**Purpose:** Track installation state, dependencies, and sync history\n\n**File:** `packages/core/src/state/state-manager.ts`\n\n**Interfaces:**\n```typescript\ninterface SkillState {\n version: string;\n source: string;\n installed_by: 'user' | string;\n installed_at: string;\n depended_by: string[];\n}\n\ninterface McpState {\n package: string;\n installed_by_skill?: string;\n installed_at: string;\n}\n\ninterface State {\n $schema: string;\n skills: Record<string, SkillState>;\n mcp: Record<string, McpState>;\n sync_history: Record<SyncTarget, string>;\n}\n\nclass StateManager {\n loadState(projectPath: string): Promise<State>;\n saveState(projectPath: string, state: State): Promise<void>;\n recordSkillInstall(projectPath: string, name: string, info: SkillInstallInfo): Promise<void>;\n recordSkillUninstall(projectPath: string, name: string): Promise<void>;\n getDependents(state: State, skillName: string): string[];\n canUninstall(state: State, skillName: string): { canUninstall: boolean; dependents: string[] };\n}\n```\n\n**Dependencies:** `fs/promises`\n\n**Reuses:** None (new module)\n\n### Component 3: DependencyResolver (NEW)\n\n**Purpose:** Resolve skill→skill and skill→MCP dependencies\n\n**File:** `packages/core/src/resolver/dependency-resolver.ts`\n\n**Interfaces:**\n```typescript\ninterface SkillDependencies {\n skills?: string[];\n mcp?: string[];\n}\n\ninterface ResolvedDependency {\n name: string;\n source: string;\n type: 'skill' | 'mcp';\n transitive: boolean;\n}\n\nclass DependencyResolver {\n resolveDependencies(skillSource: string, installed: Set<string>): Promise<ResolvedDependency[]>;\n buildDependencyTree(skillName: string, state: State): DependencyNode;\n detectCircular(dependencies: ResolvedDependency[]): string[] | null;\n}\n```\n\n**Dependencies:** `parser` module\n\n**Reuses:** `importer` for fetching skill metadata\n\n### Component 4: Syncer (NEW)\n\n**Purpose:** Sync skills to multiple AI tool directories\n\n**File:** `packages/core/src/sync/syncer.ts`\n\n**Interfaces:**\n```typescript\ninterface SyncTargetConfig {\n skillsDir: string;\n mcpConfigFile?: string;\n singleFile?: boolean;\n transformer?: (content: string) => string;\n}\n\ninterface SyncResult {\n success: boolean;\n skillsSynced: string[];\n errors: string[];\n}\n\nclass Syncer {\n syncToTarget(projectPath: string, target: SyncTarget, skills: Map<string, string>): Promise<SyncResult>;\n syncAll(projectPath: string): Promise<Map<SyncTarget, SyncResult>>;\n transformForTarget(content: string, target: SyncTarget): string;\n syncMcpConfig(projectPath: string, target: SyncTarget, mcp: Record<string, McpConfig>): Promise<void>;\n}\n```\n\n**Dependencies:** `adapters` module, `fs/promises`\n\n**Reuses:** Adapter implementations from `adapters/` for target-specific logic\n\n### Component 5: Extended Parser (EXTEND)\n\n**Purpose:** Parse `dependencies` field from SKILL.md frontmatter\n\n**File:** `packages/core/src/parser/schema.ts` (extend)\n\n**Changes:**\n```typescript\n// Add to existing SkillMetadata\ninterface SkillMetadata {\n // ... existing fields\n dependencies?: {\n skills?: string[];\n mcp?: string[];\n };\n}\n```\n\n**Reuses:** Existing `parser.ts` and `validator.ts`\n\n### Component 6: Extended Adapters (EXTEND)\n\n**Purpose:** Add sync capability to each adapter\n\n**Files:** `packages/core/src/adapters/*.ts`\n\n**Changes:**\n```typescript\n// Add to BaseAdapter interface\ninterface BaseAdapter {\n // ... existing methods\n sync(skills: Map<string, string>): Promise<SyncResult>;\n getSyncConfig(): SyncTargetConfig;\n}\n```\n\n**Reuses:** Existing adapter implementations\n\n## Data Models\n\n### skillpkg.json Schema\n```typescript\n{\n \"$schema\": \"https://skillpkg.dev/schemas/skillpkg.json\",\n \"name\": string, // Required\n \"version\": string, // Optional, semver\n \"skills\": {\n [name: string]: string // source (github:user/repo, url, local path)\n },\n \"mcp\": {\n [name: string]: {\n \"package\": string, // npm package name\n \"required\": boolean, // default: false\n \"command\": string, // executable command\n \"args\": string[] // command arguments\n }\n },\n \"reminders\": string[],\n \"hooks\": {\n [name: string]: string // script path\n },\n \"sync_targets\": {\n \"claude-code\": boolean,\n \"cursor\": boolean,\n \"codex\": boolean,\n \"copilot\": boolean,\n \"windsurf\": boolean\n }\n}\n```\n\n### state.json Schema\n```typescript\n{\n \"$schema\": \"skillpkg-state-v1\",\n \"skills\": {\n [name: string]: {\n \"version\": string,\n \"source\": string,\n \"installed_by\": \"user\" | string,\n \"installed_at\": string, // ISO 8601\n \"depended_by\": string[]\n }\n },\n \"mcp\": {\n [name: string]: {\n \"package\": string,\n \"installed_by_skill\": string | null,\n \"installed_at\": string\n }\n },\n \"sync_history\": {\n [target: string]: string // ISO 8601\n }\n}\n```\n\n## Sync Target Configurations\n\n| Target | Skills Directory | MCP Config | Format |\n|--------|------------------|------------|--------|\n| claude-code | `.claude/skills/{name}/SKILL.md` | `.mcp.json` | Directory per skill |\n| cursor | `.cursor/rules/{name}.md` | `.cursor/mcp.json` | File per skill |\n| codex | `AGENTS.md` | - | Single combined file |\n| copilot | `.github/copilot-instructions.md` | - | Single combined file |\n| windsurf | `.windsurf/rules/{name}.md` | `.windsurf/mcp.json` | File per skill |\n\n## Error Handling\n\n### Error Scenarios\n\n1. **Circular Dependency Detected**\n - **Handling:** Abort installation, show dependency chain\n - **User Impact:** \"Circular dependency detected: A → B → C → A\"\n\n2. **Uninstall with Dependents**\n - **Handling:** Show dependents, require `--force` or user confirmation\n - **User Impact:** \"Cannot uninstall X: depended on by Y, Z. Use --force to override.\"\n\n3. **MCP Installation Failed**\n - **Handling:** Log error, continue with skill install, mark MCP as not installed\n - **User Impact:** \"Warning: MCP 'cipher' failed to install. Skill may not work correctly.\"\n\n4. **Sync Target Not Writable**\n - **Handling:** Skip target, report error\n - **User Impact:** \"Failed to sync to cursor: Permission denied. Skipped.\"\n\n5. **Invalid skillpkg.json**\n - **Handling:** Show validation errors with line numbers\n - **User Impact:** \"Invalid skillpkg.json at line 5: 'skills' must be an object\"\n\n## Testing Strategy\n\n### Unit Testing\n- **ConfigManager**: Read/write/validate operations\n- **StateManager**: State updates, dependency queries\n- **DependencyResolver**: Resolution, circular detection\n- **Syncer**: Format transformation\n\n### Integration Testing\n- Full install flow with dependencies\n- Sync to multiple targets\n- Uninstall with dependency cleanup\n\n### E2E Testing\n- CLI command workflows\n- MCP server tool invocations\n\n## File Structure (Final)\n\n```\npackages/core/src/\n├── config/ # NEW\n│ ├── config-manager.ts\n│ ├── schemas/\n│ │ └── skillpkg.schema.json\n│ └── index.ts\n├── state/ # NEW\n│ ├── state-manager.ts\n│ └── index.ts\n├── resolver/ # NEW\n│ ├── dependency-resolver.ts\n│ └── index.ts\n├── sync/ # NEW\n│ ├── syncer.ts\n│ ├── transformers.ts\n│ └── index.ts\n├── adapters/ # EXTEND\n│ ├── base.ts # Add sync interface\n│ ├── claude-code.ts # Add sync implementation\n│ ├── cursor.ts # Add sync implementation\n│ ├── copilot.ts # Add sync implementation\n│ ├── codex.ts # Add sync implementation\n│ └── windsurf.ts # NEW adapter\n├── parser/ # EXTEND\n│ └── schema.ts # Add dependencies field\n├── store/ # EXISTING\n├── importer/ # EXISTING\n├── github/ # EXISTING\n├── types.ts\n└── index.ts # Export new modules\n```\n",
"fileStats": {
"size": 14670,
"lines": 400,
"lastModified": "2026-01-02T18:04:58.093Z"
},
"comments": []
}{
"filePath": ".spec-workflow/specs/skillpkg-v2/requirements.md",
"currentVersion": 1,
"snapshots": [
{
"version": 1,
"filename": "snapshot-001.json",
"timestamp": "2026-01-02T17:59:54.298Z",
"trigger": "initial",
"approvalId": "approval_1767376794286_zocz8l8mn",
"approvalTitle": "Requirements: skillpkg v2.0 需求規格"
}
]
}{
"id": "snapshot_1767376794298_cxxrchee8",
"approvalId": "approval_1767376794286_zocz8l8mn",
"approvalTitle": "Requirements: skillpkg v2.0 需求規格",
"version": 1,
"timestamp": "2026-01-02T17:59:54.298Z",
"trigger": "initial",
"status": "pending",
"content": "# Requirements Document: skillpkg v2.0\n\n## Introduction\n\nskillpkg v2.0 transforms from a \"skill marketplace\" into a **Project AI Workflow Manager** - essentially a `package.json` for AI workflows. It provides a unified configuration file (`skillpkg.json`) to define project skills, MCP dependencies, and sync settings across multiple AI coding tools (Claude Code, Cursor, Codex, Copilot, Windsurf).\n\n**Problem Statement:**\n- AI coding assistants have different config locations and formats\n- Skills may depend on other skills or MCP servers (no dependency management)\n- No cross-tool compatibility - skills work in one tool but not another\n- No state tracking - unclear what's installed or why\n\n**Value Proposition:**\n- Define once in `skillpkg.json`, sync to all tools\n- Automatic dependency resolution (skill→skill, skill→MCP)\n- State tracking for installation history\n- Team-shareable configuration\n\n## Alignment with Product Vision\n\nskillpkg aims to be the standard package manager for AI agent skills. v2.0 focuses on:\n- **Project-centric workflow**: Skills defined per-project, not globally\n- **Cross-tool compatibility**: One config works across all AI tools\n- **Dependency management**: Like npm for skills\n\n## Requirements\n\n### Requirement 1: Project Configuration (skillpkg.json)\n\n**User Story:** As a developer, I want a single configuration file to define my project's AI skills, so that I can version control and share my AI workflow setup.\n\n#### Acceptance Criteria\n\n1. WHEN user runs `skillpkg init` THEN system SHALL create a `skillpkg.json` file with project name and empty skills/mcp sections\n2. WHEN `skillpkg.json` exists THEN system SHALL read skills, mcp, reminders, and sync_targets from it\n3. IF skill is installed THEN system SHALL update `skillpkg.json` with the skill source\n4. WHEN user edits `skillpkg.json` manually THEN system SHALL validate the format on next command\n\n### Requirement 2: Dependency Resolution\n\n**User Story:** As a developer, I want skills to automatically install their dependencies, so that I don't have to manually track what each skill needs.\n\n#### Acceptance Criteria\n\n1. WHEN skill has `dependencies.skills` in metadata THEN system SHALL resolve and install those skills first\n2. WHEN skill has `dependencies.mcp` in metadata THEN system SHALL prompt user to install required MCP servers\n3. IF circular dependency is detected THEN system SHALL abort and show error message\n4. WHEN dependency is installed THEN system SHALL record `installed_by` in state.json\n\n### Requirement 3: Sync Mechanism\n\n**User Story:** As a developer using multiple AI tools, I want to sync my skills to all tools with one command, so that my skills work consistently everywhere.\n\n#### Acceptance Criteria\n\n1. WHEN user runs `skillpkg sync` THEN system SHALL copy skills to all enabled targets in `sync_targets`\n2. WHEN syncing to Claude Code THEN system SHALL copy SKILL.md files to `.claude/skills/`\n3. WHEN syncing to Cursor THEN system SHALL copy skill files to `.cursor/rules/`\n4. WHEN syncing to Codex THEN system SHALL combine all skills into `AGENTS.md`\n5. WHEN syncing to Copilot THEN system SHALL combine skills into `.github/copilot-instructions.md`\n6. IF target has MCP config file THEN system SHALL update it with MCP dependencies\n\n### Requirement 4: State Tracking\n\n**User Story:** As a developer, I want to see what skills are installed and why, so that I can manage my project's AI dependencies.\n\n#### Acceptance Criteria\n\n1. WHEN skill is installed THEN system SHALL record in `state.json`: version, source, installed_by, installed_at, depended_by\n2. WHEN querying dependents THEN system SHALL return list of skills that depend on the queried skill\n3. WHEN uninstalling skill with dependents THEN system SHALL warn user and require confirmation\n4. WHEN skill is uninstalled THEN system SHALL update depended_by of its dependencies\n\n### Requirement 5: Uninstall with Dependency Check\n\n**User Story:** As a developer, I want to safely uninstall skills without breaking dependencies, so that I don't accidentally break other skills.\n\n#### Acceptance Criteria\n\n1. WHEN user runs `skillpkg uninstall <name>` THEN system SHALL check if other skills depend on it\n2. IF skill has dependents THEN system SHALL show warning with list of dependents\n3. WHEN `--force` flag is provided THEN system SHALL uninstall regardless of dependents\n4. WHEN skill is uninstalled THEN system SHALL identify orphan dependencies and offer to remove them\n\n### Requirement 6: CLI Commands\n\n**User Story:** As a developer, I want intuitive CLI commands to manage my project's AI workflow, so that I can quickly install, sync, and check status.\n\n#### Acceptance Criteria\n\n1. WHEN user runs `skillpkg init` THEN system SHALL interactively create skillpkg.json\n2. WHEN user runs `skillpkg install <source>` THEN system SHALL install skill with dependencies\n3. WHEN user runs `skillpkg sync [target]` THEN system SHALL sync to specified or all targets\n4. WHEN user runs `skillpkg status` THEN system SHALL show installed skills, MCP, and sync status\n5. WHEN user runs `skillpkg deps <name>` THEN system SHALL show skill's dependencies\n6. WHEN user runs `skillpkg why <name>` THEN system SHALL show who depends on this skill\n\n## Non-Functional Requirements\n\n### Code Architecture and Modularity\n- **Single Responsibility Principle**: ConfigManager, StateManager, DependencyResolver, Syncer as separate modules\n- **Modular Design**: Core library separate from CLI and MCP server\n- **Dependency Management**: Minimal external dependencies\n- **Clear Interfaces**: TypeScript interfaces for all data structures\n\n### Performance\n- Install single skill: < 5 seconds\n- Sync to all targets: < 2 seconds\n- State read: < 100ms\n\n### Cross-Platform Compatibility\n- Support macOS, Linux, Windows\n- No symlinks (use file copy for cross-platform)\n- Handle path differences between platforms\n\n### Backward Compatibility\n- v1.x skills work in v2.x\n- skill.yaml format still supported\n- SKILL.md format preferred\n\n### Error Handling\n- Clear error messages for missing dependencies\n- Prompt before overwriting existing files\n- Rollback on partial failure\n",
"fileStats": {
"size": 6152,
"lines": 125,
"lastModified": "2026-01-02T17:59:45.776Z"
},
"comments": []
}{
"filePath": ".spec-workflow/specs/skillpkg-v2/tasks.md",
"currentVersion": 1,
"snapshots": [
{
"version": 1,
"filename": "snapshot-001.json",
"timestamp": "2026-01-02T18:16:53.872Z",
"trigger": "initial",
"approvalId": "approval_1767377813866_jdrgjioo7",
"approvalTitle": "Tasks: skillpkg v2.0 任務清單 (7 Milestones, 30 Tasks)"
}
]
}{
"id": "snapshot_1767377813872_f7xntng3f",
"approvalId": "approval_1767377813866_jdrgjioo7",
"approvalTitle": "Tasks: skillpkg v2.0 任務清單 (7 Milestones, 30 Tasks)",
"version": 1,
"timestamp": "2026-01-02T18:16:53.872Z",
"trigger": "initial",
"status": "pending",
"content": "# Tasks Document: skillpkg v2.0\n\n## Milestone 1: Config & State Management\n\n- [ ] 1.1 Define skillpkg.json JSON Schema\n - File: packages/core/src/config/schemas/skillpkg.schema.json\n - Create JSON Schema for skillpkg.json validation\n - Include skills, mcp, reminders, hooks, sync_targets fields\n - Purpose: Enable IDE autocomplete and validation\n - _Leverage: packages/core/src/parser/schema.ts for reference_\n - _Requirements: 1_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Schema Designer specializing in JSON Schema | Task: Create comprehensive JSON Schema for skillpkg.json following Requirement 1, supporting IDE autocomplete and validation | Restrictions: Follow JSON Schema draft-07 standard, ensure backward compatibility | Success: Schema validates all valid configs, rejects invalid ones, provides helpful error messages | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (schema fields, validation rules), then mark as [x]_\n\n- [ ] 1.2 Implement ConfigManager class\n - File: packages/core/src/config/config-manager.ts\n - Implement loadProjectConfig(), saveProjectConfig(), initProject()\n - Add addSkill(), removeSkill() helper methods\n - Purpose: Read/write skillpkg.json with validation\n - _Leverage: packages/core/src/parser/validator.ts_\n - _Requirements: 1_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: TypeScript Developer specializing in file I/O and validation | Task: Create ConfigManager class for skillpkg.json operations following Requirement 1 | Restrictions: Use ajv for validation, handle file not found gracefully | Success: Can read/write/validate skillpkg.json, proper error messages | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (class methods, interfaces), then mark as [x]_\n\n- [ ] 1.3 Define state.json schema and StateManager class\n - File: packages/core/src/state/state-manager.ts\n - Track skills (version, source, installed_by, depended_by)\n - Track mcp (package, installed_by_skill)\n - Track sync_history per target\n - Purpose: Maintain installation state and dependency graph\n - _Leverage: None (new module)_\n - _Requirements: 4_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Backend Developer specializing in state management | Task: Create StateManager class for state.json following Requirement 4 | Restrictions: Atomic writes, handle concurrent access | Success: Can track/query skill states and dependencies | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (class methods, state schema), then mark as [x]_\n\n- [ ] 1.4 Add getDependents() and canUninstall() to StateManager\n - File: packages/core/src/state/state-manager.ts (continue)\n - getDependents(skillName): Returns skills that depend on this skill\n - canUninstall(skillName): Check if safe to uninstall\n - Purpose: Support dependency-aware uninstall\n - _Leverage: packages/core/src/state/state-manager.ts_\n - _Requirements: 5_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Backend Developer with graph algorithms expertise | Task: Add dependency query methods following Requirement 5 | Restrictions: O(n) complexity max, handle circular refs | Success: Correctly identifies all dependents | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (methods added), then mark as [x]_\n\n- [ ] 1.5 Write unit tests for ConfigManager and StateManager\n - File: packages/core/src/config/__tests__/config-manager.test.ts\n - File: packages/core/src/state/__tests__/state-manager.test.ts\n - Test read/write operations, validation, edge cases\n - Purpose: Ensure reliability of config/state management\n - _Leverage: vitest testing framework_\n - _Requirements: 1, 4_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: QA Engineer with TypeScript testing expertise | Task: Create comprehensive unit tests for ConfigManager and StateManager | Restrictions: Mock file system, test edge cases | Success: >80% coverage, all edge cases handled | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (test cases), then mark as [x]_\n\n## Milestone 2: Dependency Resolution\n\n- [ ] 2.1 Extend SKILL.md parser for dependencies field\n - File: packages/core/src/parser/schema.ts (modify)\n - Add dependencies: { skills?: string[], mcp?: string[] } to schema\n - Update parser to extract dependencies from frontmatter\n - Purpose: Support skill dependency declaration\n - _Leverage: packages/core/src/parser/parser.ts_\n - _Requirements: 2_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Parser Developer | Task: Extend SKILL.md parser schema following Requirement 2 | Restrictions: Backward compatible, optional field | Success: Parses dependencies from existing and new skills | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (schema changes), then mark as [x]_\n\n- [ ] 2.2 Create DependencyResolver class\n - File: packages/core/src/resolver/dependency-resolver.ts\n - Implement resolveDependencies(source, installed): Recursive resolution\n - Implement detectCircular(): Check for circular dependencies\n - Purpose: Resolve skill→skill and skill→MCP dependencies\n - _Leverage: packages/core/src/importer/importer.ts_\n - _Requirements: 2_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Algorithm Developer specializing in graph traversal | Task: Create DependencyResolver with recursive resolution and circular detection following Requirement 2 | Restrictions: Handle transitive deps, detect cycles early | Success: Correctly resolves dependency tree, aborts on circular | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (class methods, algorithms), then mark as [x]_\n\n- [ ] 2.3 Add MCP dependency checking\n - File: packages/core/src/resolver/dependency-resolver.ts (continue)\n - checkMcpDependencies(mcpNames): Check against .mcp.json\n - Return missing MCP list with install instructions\n - Purpose: Identify missing MCP servers\n - _Leverage: packages/core/src/resolver/dependency-resolver.ts_\n - _Requirements: 2_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: MCP Integration Developer | Task: Add MCP dependency checking following Requirement 2 | Restrictions: Read .mcp.json, provide clear install instructions | Success: Correctly identifies missing MCPs | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (methods), then mark as [x]_\n\n- [ ] 2.4 Write unit tests for DependencyResolver\n - File: packages/core/src/resolver/__tests__/dependency-resolver.test.ts\n - Test single-level, multi-level, circular dependencies\n - Test MCP dependency checking\n - Purpose: Ensure correct dependency resolution\n - _Leverage: vitest_\n - _Requirements: 2_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: QA Engineer | Task: Create tests for DependencyResolver | Restrictions: Mock skill fetching, test all scenarios | Success: All resolution scenarios tested | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (test cases), then mark as [x]_\n\n## Milestone 3: Sync Mechanism\n\n- [ ] 3.1 Define SyncTargetConfig for each AI tool\n - File: packages/core/src/sync/targets.ts\n - Define configs for: claude-code, cursor, codex, copilot, windsurf\n - Include: skillsDir, mcpConfigFile, singleFile, transformer\n - Purpose: Configure how skills sync to each tool\n - _Leverage: packages/core/src/adapters/*.ts for reference_\n - _Requirements: 3_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Integration Developer | Task: Define sync target configurations following Requirement 3 | Restrictions: Follow each tool's conventions | Success: All 5 targets properly configured | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (target configs), then mark as [x]_\n\n- [ ] 3.2 Create Syncer class\n - File: packages/core/src/sync/syncer.ts\n - Implement syncToTarget(projectPath, target, skills)\n - Implement syncAll(projectPath)\n - Handle file copy and format conversion\n - Purpose: Sync skills to AI tool directories\n - _Leverage: packages/core/src/sync/targets.ts_\n - _Requirements: 3_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: File System Developer | Task: Create Syncer class following Requirement 3 | Restrictions: Atomic operations, handle errors gracefully | Success: Skills correctly synced to all targets | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (class methods), then mark as [x]_\n\n- [ ] 3.3 Implement format transformers\n - File: packages/core/src/sync/transformers.ts\n - SKILL.md → directory structure (Claude Code)\n - SKILL.md → single file (Codex AGENTS.md, Copilot)\n - Purpose: Convert skill format for each target\n - _Leverage: packages/core/src/sync/syncer.ts_\n - _Requirements: 3_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Format Conversion Developer | Task: Create format transformers following Requirement 3 | Restrictions: Preserve skill content, handle frontmatter | Success: Correct format for each target | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (transformer functions), then mark as [x]_\n\n- [ ] 3.4 Add MCP config sync\n - File: packages/core/src/sync/syncer.ts (continue)\n - syncMcpConfig(projectPath, target, mcpConfig)\n - Update .mcp.json / .cursor/mcp.json etc.\n - Purpose: Sync MCP configuration to targets\n - _Leverage: packages/core/src/sync/syncer.ts_\n - _Requirements: 3_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Config Sync Developer | Task: Add MCP config sync following Requirement 3 | Restrictions: Merge with existing config, don't overwrite user settings | Success: MCP config correctly synced | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (methods), then mark as [x]_\n\n- [ ] 3.5 Write unit tests for Syncer\n - File: packages/core/src/sync/__tests__/syncer.test.ts\n - Test sync to each target\n - Test format transformation\n - Test MCP config sync\n - Purpose: Ensure correct sync behavior\n - _Leverage: vitest, mock file system_\n - _Requirements: 3_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: QA Engineer | Task: Create tests for Syncer | Restrictions: Mock file system, test all targets | Success: All sync scenarios tested | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (test cases), then mark as [x]_\n\n## Milestone 4: Installer Updates\n\n- [ ] 4.1 Update install flow with dependency resolution\n - File: packages/core/src/store/skill-store.ts (modify)\n - Integrate DependencyResolver before installation\n - Install dependencies in correct order\n - Record installed_by in state.json\n - Purpose: Auto-install skill dependencies\n - _Leverage: packages/core/src/resolver/dependency-resolver.ts_\n - _Requirements: 2_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Package Manager Developer | Task: Update install flow following Requirement 2 | Restrictions: Maintain backward compat, atomic operations | Success: Dependencies auto-installed in order | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (flow changes), then mark as [x]_\n\n- [ ] 4.2 Update uninstall flow with dependency check\n - File: packages/core/src/store/skill-store.ts (modify)\n - Check dependents before uninstall\n - Support --force flag\n - Clean up orphan dependencies\n - Purpose: Safe uninstall with dependency awareness\n - _Leverage: packages/core/src/state/state-manager.ts_\n - _Requirements: 5_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Package Manager Developer | Task: Update uninstall flow following Requirement 5 | Restrictions: Warn before removing deps, support force | Success: Safe uninstall with orphan cleanup | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (flow changes), then mark as [x]_\n\n- [ ] 4.3 Implement installFromConfig()\n - File: packages/core/src/store/skill-store.ts (continue)\n - Read skillpkg.json and install all listed skills\n - Similar to `npm install` from package.json\n - Purpose: Install all project skills from config\n - _Leverage: packages/core/src/config/config-manager.ts_\n - _Requirements: 1_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Package Manager Developer | Task: Implement installFromConfig following Requirement 1 | Restrictions: Skip already installed, handle partial failures | Success: All config skills installed | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (method), then mark as [x]_\n\n- [ ] 4.4 Write integration tests for install/uninstall\n - File: packages/core/src/store/__tests__/skill-store.integration.test.ts\n - Test install with dependencies\n - Test uninstall with dependents\n - Test installFromConfig\n - Purpose: Ensure correct install/uninstall behavior\n - _Leverage: vitest_\n - _Requirements: 2, 5_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: QA Engineer | Task: Create integration tests for install/uninstall | Restrictions: Use temp directories, clean up | Success: All scenarios tested | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (test cases), then mark as [x]_\n\n## Milestone 5: CLI Commands\n\n- [ ] 5.1 Add `skillpkg init` command\n - File: packages/cli/src/commands/init.ts\n - Interactive prompts for project name, sync targets\n - Create skillpkg.json\n - Purpose: Initialize new project with skillpkg\n - _Leverage: packages/core/src/config/config-manager.ts_\n - _Requirements: 6_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: CLI Developer | Task: Create init command following Requirement 6 | Restrictions: Interactive prompts, handle existing config | Success: Creates valid skillpkg.json | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (command implementation), then mark as [x]_\n\n- [ ] 5.2 Add `skillpkg sync` command\n - File: packages/cli/src/commands/sync.ts\n - Support: skillpkg sync [target] --dry-run\n - Show progress and results\n - Purpose: Sync skills to AI tools\n - _Leverage: packages/core/src/sync/syncer.ts_\n - _Requirements: 6_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: CLI Developer | Task: Create sync command following Requirement 6 | Restrictions: Support dry-run, show progress | Success: Syncs to all targets correctly | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (command implementation), then mark as [x]_\n\n- [ ] 5.3 Add dependency commands (deps, why, tree)\n - File: packages/cli/src/commands/deps.ts\n - skillpkg deps <name>: Show skill dependencies\n - skillpkg why <name>: Show who depends on skill\n - skillpkg tree: Show full dependency tree\n - Purpose: Query dependency information\n - _Leverage: packages/core/src/state/state-manager.ts_\n - _Requirements: 6_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: CLI Developer | Task: Create dependency query commands following Requirement 6 | Restrictions: Clear output format, handle missing skills | Success: Correct dependency info displayed | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (commands), then mark as [x]_\n\n- [ ] 5.4 Add `skillpkg status` command\n - File: packages/cli/src/commands/status.ts\n - Show installed skills with versions\n - Show MCP status\n - Show sync status per target\n - Purpose: Overview of project AI workflow\n - _Leverage: packages/core/src/state/state-manager.ts_\n - _Requirements: 6_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: CLI Developer | Task: Create status command following Requirement 6 | Restrictions: Clear table format, show warnings | Success: Complete status overview | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (command implementation), then mark as [x]_\n\n- [ ] 5.5 Update install/uninstall commands\n - File: packages/cli/src/commands/install.ts (modify)\n - File: packages/cli/src/commands/uninstall.ts (modify)\n - Show dependency resolution output\n - Add --force flag for uninstall\n - Prompt for sync after install\n - Purpose: Enhanced install/uninstall UX\n - _Leverage: packages/core/src/store/skill-store.ts_\n - _Requirements: 6_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: CLI Developer | Task: Update install/uninstall commands following Requirement 6 | Restrictions: Show deps, support force | Success: Clear feedback during install/uninstall | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (changes), then mark as [x]_\n\n## Milestone 6: MCP Server Updates\n\n- [ ] 6.1 Update install_skill MCP tool\n - File: packages/mcp-server/src/tools/install.ts (modify)\n - Return dependency info in result\n - Return missing MCP list\n - Prompt for sync\n - Purpose: MCP tool reflects new features\n - _Leverage: packages/core/src/store/skill-store.ts_\n - _Requirements: 2, 6_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: MCP Developer | Task: Update install_skill tool | Restrictions: Maintain backward compat | Success: Returns deps and MCP info | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (tool changes), then mark as [x]_\n\n- [ ] 6.2 Update uninstall_skill MCP tool\n - File: packages/mcp-server/src/tools/uninstall.ts (modify)\n - Return dependents warning\n - Support force parameter\n - Purpose: MCP tool reflects uninstall changes\n - _Leverage: packages/core/src/store/skill-store.ts_\n - _Requirements: 5, 6_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: MCP Developer | Task: Update uninstall_skill tool | Restrictions: Return warnings, support force | Success: Safe uninstall via MCP | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (tool changes), then mark as [x]_\n\n- [ ] 6.3 Add sync_skills MCP tool\n - File: packages/mcp-server/src/tools/sync.ts (new)\n - Sync skills to specified target\n - Return sync results\n - Purpose: Enable sync via MCP\n - _Leverage: packages/core/src/sync/syncer.ts_\n - _Requirements: 3, 6_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: MCP Developer | Task: Create sync_skills tool | Restrictions: Support all targets | Success: Skills synced via MCP | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (new tool), then mark as [x]_\n\n## Milestone 7: Migration & Polish\n\n- [ ] 7.1 Implement migrate command\n - File: packages/cli/src/commands/migrate.ts (new)\n - Detect v1.x installations (skills without skillpkg.json)\n - Generate skillpkg.json from installed skills\n - Generate state.json\n - Purpose: Smooth upgrade from v1.x\n - _Leverage: packages/core/src/config/config-manager.ts_\n - _Requirements: Non-functional: Backward Compatibility_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Migration Developer | Task: Create migrate command | Restrictions: Don't break existing installs | Success: v1.x users can upgrade smoothly | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (migration logic), then mark as [x]_\n\n- [ ] 7.2 Update README and documentation\n - File: README.md (modify)\n - File: docs/migration.md (new)\n - Document skillpkg.json format\n - Document sync targets\n - Add migration guide\n - Purpose: User documentation\n - _Leverage: existing docs_\n - _Requirements: All_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Technical Writer | Task: Update documentation | Restrictions: Clear examples, cover all features | Success: Users can understand and use v2.0 | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (docs), then mark as [x]_\n\n- [ ] 7.3 E2E testing\n - File: packages/core/src/__tests__/e2e.test.ts (new)\n - Test full workflow: init → install → sync → uninstall\n - Test migration from v1.x\n - Purpose: Validate complete user journeys\n - _Leverage: vitest_\n - _Requirements: All_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: E2E Test Engineer | Task: Create end-to-end tests | Restrictions: Test real workflows, clean up | Success: All user journeys validated | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (test scenarios), then mark as [x]_\n\n- [ ] 7.4 Version bump and release\n - File: packages/*/package.json\n - Bump versions to 0.3.0\n - Update CHANGELOG.md\n - npm publish\n - Purpose: Release v2.0\n - _Leverage: npm_\n - _Requirements: All_\n - _Prompt: Implement the task for spec skillpkg-v2, first run spec-workflow-guide to get the workflow guide then implement the task: Role: Release Engineer | Task: Prepare and execute release | Restrictions: Follow semver, update changelogs | Success: v0.3.0 published to npm | Instructions: Mark task as [-] in tasks.md before starting, use log-implementation tool after completion with artifacts (version changes), then mark as [x]_\n",
"fileStats": {
"size": 24574,
"lines": 301,
"lastModified": "2026-01-02T18:16:39.637Z"
},
"comments": []
}{
"id": "approval_1767377813866_jdrgjioo7",
"title": "Tasks: skillpkg v2.0 任務清單 (7 Milestones, 30 Tasks)",
"filePath": ".spec-workflow/specs/skillpkg-v2/tasks.md",
"type": "document",
"status": "approved",
"createdAt": "2026-01-02T18:16:53.866Z",
"category": "spec",
"categoryName": "skillpkg-v2",
"response": "已批准",
"respondedAt": "2026-01-02T18:35:08.134Z"
}Design Document: skillpkg MCP Server
Overview
skillpkg MCP Server 是一個實作 Anthropic MCP (Model Context Protocol) 的服務，讓 AI Agent 能透過標準化協議存取 skillpkg 的功能。Server 使用 stdio transport，可被 Claude Desktop、Cursor 等 MCP 客戶端呼叫。
┌─────────────────────────────────────────────────────────────────┐
│ Architecture │
│ │
│ ┌──────────────┐ stdio ┌──────────────────────────┐ │
│ │ MCP Client │ ◄────────────► │ skillpkg serve │ │
│ │ (Claude/ │ │ │ │
│ │ Cursor) │ │ ┌────────────────────┐ │ │
│ └──────────────┘ │ │ MCP Server │ │ │
│ │ │ (Tool Router) │ │ │
│ │ └─────────┬──────────┘ │ │
│ │ │ │ │
│ │ ┌─────────▼──────────┐ │ │
│ │ │ Tool Handlers │ │ │
│ │ │ ├─ search_skills │ │ │
│ │ │ ├─ load_skill │ │ │
│ │ │ ├─ install_skill │ │ │
│ │ │ ├─ list_skills │ │ │
│ │ │ ├─ uninstall_skill│ │ │
│ │ │ ├─ search_registry│ │ │
│ │ │ └─ skill_info │ │ │
│ │ └─────────┬──────────┘ │ │
│ │ │ │ │
│ │ ┌─────────▼──────────┐ │ │
│ │ │ skillpkg-core │ │ │
│ │ │ (Existing Logic) │ │ │
│ │ └────────────────────┘ │ │
│ └──────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘Registry Architecture (GitHub-based)
┌─────────────────────────────────────────────────────────────────┐
│ github.com/skillpkg/registry │
│ │
│ ├── skills/ # 所有 skills │
│ │ ├── self-evolving-agent/ │
│ │ │ ├── skill.yaml │
│ │ │ └── README.md │
│ │ ├── code-reviewer/ │
│ │ └── comfyui-expert/ │
│ │ │
│ ├── index.json # 自動生成的索引 │
│ │ { │
│ │ "skills": [{ │
│ │ "name": "self-evolving-agent", │
│ │ "description": "...", │
│ │ "version": "1.0.0", │
│ │ "stars": 42, ← GitHub stars │
│ │ "updatedAt": "2025-01-02" │
│ │ }] │
│ │ } │
│ │ │
│ └── .github/workflows/ │
│ ├── validate-pr.yml # PR 驗證 skill.yaml 格式 │
│ └── update-index.yml # merge 後更新 index.json │
└─────────────────────────────────────────────────────────────────┘Registry URLs
| 用途 | URL |
|---|---|
| Index | https://raw.githubusercontent.com/skillpkg/registry/main/index.json |
| Skill | https://raw.githubusercontent.com/skillpkg/registry/main/skills/{name}/skill.yaml |
| README | https://raw.githubusercontent.com/skillpkg/registry/main/skills/{name}/README.md |
| Stars API | https://api.github.com/repos/skillpkg/registry |
數據映射
| MCP 欄位 | GitHub 來源 |
|---|---|
rating | GitHub stars (正規化到 1-5) |
downloads | index.json 中的 install_count (透過 CI 追蹤) |
updatedAt | skill 目錄最後 commit 時間 |
author | skill.yaml 中的 author 欄位 |
Code Reuse Analysis
Existing Components to Leverage
| Component | Location | Usage |
|---|---|---|
LocalStore | skillpkg-core/store/local.ts | 讀取/寫入本地 skills |
GlobalStore | skillpkg-core/store/global.ts | 讀取/寫入全域 skills |
RegistryClient | skillpkg-core/registry/client.ts | 搜尋/下載 registry skills |
parse() | skillpkg-core/parser/ | 解析 skill.yaml |
createInstaller | skillpkg-core/installer/ | 安裝 skills |
Integration Points
- CLI Commands: MCP tools 與 CLI commands 共用相同的 core 邏輯
- Store: 使用現有的 LocalStore/GlobalStore 存取 skills
- Registry: 使用現有的 RegistryClient 與 registry 互動
Architecture
Package Structure
packages/
├── core/ # 現有 (不變)
│ ├── store/
│ ├── parser/
│ ├── registry/
│ └── installer/
├── cli/ # 現有 (新增 serve command)
│ ├── commands/
│ │ ├── serve.ts # NEW: 啟動 MCP Server
│ │ └── ... (existing)
│ └── index.ts
└── mcp-server/ # NEW: MCP Server 套件
├── server.ts # MCP Server 主程式
├── tools/ # Tool handlers
│ ├── index.ts
│ ├── search-skills.ts
│ ├── load-skill.ts
│ ├── install-skill.ts
│ ├── list-skills.ts
│ ├── uninstall-skill.ts
│ ├── search-registry.ts
│ └── skill-info.ts
├── types.ts # MCP 相關型別
└── index.tsComponents and Interfaces
Component 1: MCP Server (server.ts)
- Purpose: 處理 MCP 協議、路由 tool 呼叫
- Interfaces:
class SkillpkgMcpServer {
constructor(options?: ServerOptions)
start(): Promise<void>
stop(): Promise<void>
}
interface ServerOptions {
scope?: 'local' | 'global' // 預設 scope
projectPath?: string // 專案路徑
}- Dependencies:
@modelcontextprotocol/sdk,skillpkg-core - Reuses: 無，全新組件
Component 2: Tool Handlers (tools/)
每個 tool 是一個獨立模組，遵循相同介面：
- Purpose: 處理特定 MCP tool 的邏輯
- Interfaces:
interface ToolHandler {
name: string
description: string
inputSchema: JSONSchema
execute(args: unknown): Promise<ToolResult>
}
interface ToolResult {
content: Array<{
type: 'text'
text: string
}>
isError?: boolean
}- Dependencies:
skillpkg-core - Reuses: Store, Parser, Registry, Installer from core
Component 3: Serve Command (cli/commands/serve.ts)
- Purpose: CLI 進入點，啟動 MCP Server
- Interfaces:
skillpkg serve [options]
--scope <scope> # local | global (default: local)
--project <path> # Project path for local scope- Dependencies:
skillpkg-mcp-server - Reuses: CLI framework (commander)
Data Models
Tool: search_skills
// Input
interface SearchSkillsInput {
query: string // 搜尋關鍵字
source?: 'all' | 'local' | 'registry' // 預設 'all'
limit?: number // 預設 20
}
// Output
interface SearchSkillsOutput {
results: Array<{
id: string // skill identifier
name: string
description: string
version: string
source: 'local' | 'registry'
installed: boolean // 是否已安裝
rating: number // 評分 (1-5)
downloads: number // 下載次數
updatedAt: string // 最後更新 ISO timestamp
tags: string[] // 標籤
relevanceScore: number // 綜合相關性分數
}>
total: number
query: string
}Tool: load_skill
// Input
interface LoadSkillInput {
id: string // skill id
}
// Output
interface LoadSkillOutput {
id: string
name: string
version: string
description: string
instructions: string // 完整 instructions 內容
author?: {
name: string
url?: string
}
}Tool: install_skill
// Input
interface InstallSkillInput {
source: string // skill name, GitHub URL, HTTP URL, gist:id, 或本地路徑
scope?: 'local' | 'global' // 預設 'local'
}
// Output
interface InstallSkillOutput {
success: boolean
skill: {
id: string
name: string
version: string
source: string // 安裝來源
installedAt: string // ISO timestamp
}
message: string
}Tool: list_skills
// Input
interface ListSkillsInput {
scope?: 'all' | 'local' | 'global' // 預設 'all'
}
// Output
interface ListSkillsOutput {
skills: Array<{
id: string
name: string
description: string
version: string
scope: 'local' | 'global'
installedAt: string
}>
total: number
}Tool: uninstall_skill
// Input
interface UninstallSkillInput {
id: string
scope?: 'local' | 'global'
}
// Output
interface UninstallSkillOutput {
success: boolean
message: string
}Tool: search_registry
// Input
interface SearchRegistryInput {
query: string
limit?: number // 預設 20
}
// Output
interface SearchRegistryOutput {
results: Array<{
name: string
description: string
version: string
author: string
downloads: number
}>
total: number
}Tool: skill_info
// Input
interface SkillInfoInput {
name: string // skill name in registry
}
// Output
interface SkillInfoOutput {
name: string
description: string
version: string
author: {
name: string
email?: string
url?: string
}
repository?: string
license?: string
platforms?: string[]
tags?: string[]
readme?: string // README 內容（如有）
}Tool: recommend_skill
// Input
interface RecommendSkillInput {
query: string // 任務描述或關鍵字
criteria?: 'auto' | 'popular' | 'highest_rated' | 'newest' // 預設 'auto'
}
// Output
interface RecommendSkillOutput {
recommendation: {
id: string
name: string
description: string
version: string
rating: number
downloads: number
updatedAt: string
author: string
tags: string[]
}
reason: string // 推薦理由
alternatives: Array<{ // 備選方案 (最多 3 個)
name: string
description: string
rating: number
}>
installCommand: string // 安裝指令提示
}Relevance Scoring Algorithm
function calculateRelevanceScore(skill: SkillMetadata, query: string): number {
// 文字相關性 (0-40 分)
const textRelevance = calculateTextMatch(skill, query) * 40
// 評分權重 (0-25 分)
const ratingScore = (skill.rating / 5) * 25
// 熱門程度 (0-20 分) - log scale
const popularityScore = Math.min(Math.log10(skill.downloads + 1) / 4, 1) * 20
// 新鮮度 (0-15 分) - 30天內滿分，逐漸衰減
const daysSinceUpdate = daysBetween(skill.updatedAt, now())
const freshnessScore = Math.max(0, 1 - daysSinceUpdate / 180) * 15
return textRelevance + ratingScore + popularityScore + freshnessScore
}Source Detection Logic
install_skill 需要自動偵測來源類型：
function detectSourceType(source: string): SourceType {
// GitHub URL
if (source.startsWith('github:') ||
source.includes('github.com/')) {
return 'github'
}
// Gist
if (source.startsWith('gist:') ||
source.includes('gist.github.com/')) {
return 'gist'
}
// HTTP URL (zip/tarball)
if (source.startsWith('http://') ||
source.startsWith('https://')) {
return 'url'
}
// Local path
if (source.startsWith('./') ||
source.startsWith('/') ||
source.startsWith('~')) {
return 'local'
}
// Default: registry
return 'registry'
}
type SourceType = 'registry' | 'github' | 'gist' | 'url' | 'local'Error Handling
Error Scenarios
1. Skill Not Found
- Handling: 回傳 error result，建議搜尋或安裝
- User Impact: AI 收到建議訊息，可選擇搜尋或安裝
2. Registry Unavailable
- Handling: 回傳 error，但本地功能仍可用
- User Impact: AI 知道只能使用本地 skills
3. Installation Failed
- Handling: 回傳詳細錯誤訊息和可能的解決方案
- User Impact: AI 可以嘗試其他安裝方式
4. Invalid Source Format
- Handling: 回傳 error，列出支援的格式
- User Impact: AI 可以修正 source 格式
Error Response Format
interface ErrorResult {
content: [{
type: 'text'
text: string // 包含錯誤訊息和建議
}]
isError: true
}
// Example
{
content: [{
type: 'text',
text: `Error: Skill "foo" not found locally.
Suggestions:
- Search registry: search_skills({ query: "foo" })
- Install from registry: install_skill({ source: "foo" })
- Check available skills: list_skills()`
}],
isError: true
}Testing Strategy
Unit Testing
- Tool Handlers: 每個 tool 獨立測試輸入驗證和輸出格式
- Source Detection: 測試各種來源格式的偵測
- Error Handling: 測試各種錯誤情況的回應
Integration Testing
- MCP Protocol: 測試完整的 MCP request/response 流程
- Store Integration: 測試與 LocalStore/GlobalStore 的整合
- Registry Integration: 測試與 Registry API 的整合
End-to-End Testing
- Claude Desktop: 手動測試與 Claude Desktop 的整合
- Full Workflow: 測試 search → install → load → use 完整流程
Configuration
MCP Client Configuration
// claude_desktop_config.json
{
"mcpServers": {
"skillpkg": {
"command": "skillpkg",
"args": ["serve"],
"env": {
"SKILLPKG_SCOPE": "local"
}
}
}
}
// With global scope
{
"mcpServers": {
"skillpkg": {
"command": "skillpkg",
"args": ["serve", "--scope", "global"]
}
}
}Environment Variables
| Variable | Description | Default |
|---|---|---|
SKILLPKG_SCOPE | Default scope for operations | local |
SKILLPKG_REGISTRY_URL | Custom registry URL | (default registry) |
SKILLPKG_PROJECT_PATH | Project path for local scope | (current directory) |
Requirements Document: skillpkg MCP Server
Introduction
skillpkg MCP Server 將 skillpkg 從「CLI 同步工具」轉變為「AI 可呼叫的 MCP 服務」。這使得 AI Agent 能夠： 1. 按需載入 skills，解決 context 爆炸問題 2. 自主搜尋與安裝 新 skills，實現 Self-Evolving Agent 3. 動態管理 skills 生命週期
核心價值：讓 AI 遇到不會的任務時，能自己找工具、學會、然後完成任務。
Problem Statement
現有問題
目前 skillpkg sync 做法：
┌─────────────────────────────────────────────────────────┐
│ 50+ skills 全部同步到 .claude/skills/ │
│ → 啟動時載入 ~30,000 tokens │
│ → 實際只用 1-2 個 skill │
│ → Context 空間被浪費 │
│ → AI 無法自主學習新 skills │
└─────────────────────────────────────────────────────────┘解決方案
MCP Server 按需載入：
┌─────────────────────────────────────────────────────────┐
│ AI 啟動時只載入 MCP tools (~200 tokens) │
│ → 需要時才 search_skills / load_skill │
│ → 可以 install_skill 學習新技能 │
│ → Context 空間有效利用 │
└─────────────────────────────────────────────────────────┘Requirements
REQ-1: MCP Server 基礎架構
User Story: As an AI Agent, I want skillpkg to run as an MCP Server, so that I can call its functions through MCP protocol.
Acceptance Criteria
1. WHEN skillpkg serve is executed THEN system SHALL start an MCP server using stdio transport 2. WHEN MCP client connects THEN system SHALL respond with available tools list 3. IF server encounters an error THEN system SHALL return proper MCP error response 4. WHEN server starts THEN system SHALL log startup message to stderr (not stdout, to avoid MCP protocol interference)
REQ-2: Skills 搜尋功能 (search_skills)
User Story: As an AI Agent, I want to search for skills by keyword, so that I can find relevant skills without loading all content.
Acceptance Criteria
1. WHEN search_skills(query) is called THEN system SHALL return matching skills with metadata only (~100 tokens per skill) 2. WHEN searching THEN system SHALL search both local installed skills AND remote registry 3. IF source parameter is "local" THEN system SHALL only search installed skills 4. IF source parameter is "registry" THEN system SHALL only search remote registry 5. WHEN results are returned THEN system SHALL include: id, name, description, version, source, rating, downloads, updatedAt 6. IF no matches found THEN system SHALL return empty array with helpful message 7. WHEN results are returned THEN system SHALL sort by relevance score (rating × downloads × recency)
REQ-3: Skills 載入功能 (load_skill)
User Story: As an AI Agent, I want to load full skill instructions on demand, so that I only consume context when needed.
Acceptance Criteria
1. WHEN load_skill(id) is called for installed skill THEN system SHALL return full instructions content 2. IF skill is not installed THEN system SHALL return error with suggestion to install first 3. WHEN loading THEN system SHALL return: id, name, version, instructions (full content) 4. IF skill file is corrupted THEN system SHALL return descriptive error
REQ-4: Skills 安裝功能 (install_skill)
User Story: As an AI Agent, I want to install skills from multiple sources, so that I can learn new capabilities autonomously.
Acceptance Criteria
1. WHEN install_skill(source) is called with skill name THEN system SHALL install from registry 2. WHEN source is GitHub URL (github.com/* or github:user/repo) THEN system SHALL clone/download from GitHub 3. WHEN source is HTTP URL ending with .zip/.tar.gz THEN system SHALL download and extract 4. WHEN source is gist URL or gist:id THEN system SHALL download from GitHub Gist 5. WHEN source is local path THEN system SHALL install from local directory 6. AFTER successful install THEN system SHALL return installed skill metadata 7. IF installation fails THEN system SHALL return descriptive error with recovery suggestion
REQ-5: Skills 列表功能 (list_skills)
User Story: As an AI Agent, I want to list installed skills, so that I know what capabilities I have.
Acceptance Criteria
1. WHEN list_skills() is called THEN system SHALL return all installed skills with metadata 2. WHEN listing THEN system SHALL include: id, name, description, version, installed_at 3. IF scope is "global" THEN system SHALL list globally installed skills 4. IF scope is "local" THEN system SHALL list project-local skills 5. IF no skills installed THEN system SHALL return empty array with helpful message
REQ-6: Skills 移除功能 (uninstall_skill)
User Story: As an AI Agent, I want to uninstall skills I no longer need, so that I can manage my capabilities.
Acceptance Criteria
1. WHEN uninstall_skill(id) is called THEN system SHALL remove the skill 2. IF skill not found THEN system SHALL return error 3. AFTER uninstall THEN system SHALL return confirmation message
REQ-7: Registry 搜尋功能 (search_registry)
User Story: As an AI Agent, I want to search the skill registry, so that I can discover new skills to install.
Acceptance Criteria
1. WHEN search_registry(query) is called THEN system SHALL search remote registry 2. WHEN results returned THEN system SHALL include: name, description, version, author, downloads 3. IF registry unavailable THEN system SHALL return error with offline suggestion 4. WHEN limit parameter provided THEN system SHALL limit results count
REQ-8: Skill 詳情功能 (skill_info)
User Story: As an AI Agent, I want to get detailed info about a skill before installing, so that I can make informed decisions.
Acceptance Criteria
1. WHEN skill_info(name) is called THEN system SHALL return full skill metadata from registry 2. WHEN returning info THEN system SHALL include: name, description, version, author, repository, dependencies, platforms 3. IF skill not found in registry THEN system SHALL return error
REQ-9: 智慧推薦功能 (recommend_skill)
User Story: As an AI Agent, I want to get the best skill recommendation for my task, so that I can quickly acquire the right capability without manual comparison.
Acceptance Criteria
1. WHEN recommend_skill(query) is called THEN system SHALL return single best matching skill 2. WHEN recommending THEN system SHALL consider: rating, downloads, recency, relevance to query 3. IF criteria is "popular" THEN system SHALL prioritize downloads count 4. IF criteria is "highest_rated" THEN system SHALL prioritize rating 5. IF criteria is "newest" THEN system SHALL prioritize updatedAt 6. WHEN returning recommendation THEN system SHALL include: skill metadata + reason for recommendation 7. IF no suitable skill found THEN system SHALL return helpful message with alternative suggestions
Non-Functional Requirements
Code Architecture and Modularity
- Single Responsibility: MCP Server 邏輯與現有 CLI 邏輯分離
- Reuse Core: 使用 skillpkg-core 的現有功能 (Store, Parser, Registry Client)
- Transport Abstraction: MCP transport 層可替換 (stdio, HTTP future)
Performance
- Cold Start: Server 啟動時間 < 500ms
- Response Time: 本地操作 < 100ms，Registry 操作 < 2s
- Memory: 常駐記憶體 < 50MB
Security
- Source Validation: 從 URL 安裝時驗證來源合法性
- No Code Execution: 安裝過程不執行任何 skill 內的程式碼
- Path Traversal: 防止路徑穿越攻擊
Reliability
- Graceful Degradation: Registry 不可用時，本地功能仍可用
- Error Messages: 所有錯誤都有清楚的訊息和建議
Compatibility
- MCP Protocol: 遵循 Anthropic MCP Specification
- Clients: 支援 Claude Desktop, Cursor, Windsurf, 其他 MCP 客戶端
專案腳手架 - 設計文件
設計理念
最小可用配置 - 快速模式給出能立即使用的預設，互動模式提供客製化選項。
架構概覽
┌─────────────────────────────────────────────────────────────┐
│ skillpkg init [-i] │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ 快速模式 │ │ 互動模式 │ │
│ │ (預設) │ │ (-i flag) │ │
│ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ ProjectInitializer │ │
│ │ │ │
│ │ - getDefaultConfig() │ │
│ │ - promptForOptions() (互動模式) │ │
│ │ - generate() │ │
│ └─────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ skillpkg.json │
└─────────────────────────────────────────────────────────────┘資料結構
ProjectConfig
interface ProjectConfig {
name: string;
skills: Record<string, string>;
mcp: Record<string, McpConfig>;
sync_targets: Record<string, boolean>;
}
interface McpConfig {
package?: string;
command?: string;
args?: string[];
env?: Record<string, string>;
}預設配置
const DEFAULT_PROJECT_CONFIG: Partial<ProjectConfig> = {
skills: {},
mcp: {
context7: {
package: '@context7/mcp-server'
}
},
sync_targets: {
'claude-code': true
}
};
const OPTIONAL_MCP: Record<string, McpConfig & { description: string; requiresEnv?: string }> = {
github: {
package: '@anthropic/mcp-server-github',
description: 'GitHub 操作',
requiresEnv: 'GITHUB_TOKEN'
},
filesystem: {
package: '@anthropic/mcp-server-filesystem',
description: '檔案系統存取'
}
};模組設計
ProjectInitializer (packages/core/src/project/)
export class ProjectInitializer {
/**
* 取得預設配置
*/
getDefaultConfig(projectName: string): ProjectConfig {
return {
name: projectName,
...DEFAULT_PROJECT_CONFIG
};
}
/**
* 互動式取得配置
*/
async promptForOptions(): Promise<ProjectConfig> {
const name = await input({ message: '專案名稱:' });
const includeMcp = await confirm({
message: '加入推薦 MCP?',
default: true
});
const config = this.getDefaultConfig(name);
if (includeMcp) {
// 顯示可選 MCP 列表
const selected = await checkbox({
message: '選擇 MCP servers:',
choices: Object.entries(OPTIONAL_MCP).map(([key, val]) => ({
name: `${key} - ${val.description}`,
value: key
}))
});
for (const key of selected) {
config.mcp[key] = OPTIONAL_MCP[key];
}
}
return config;
}
/**
* 產生 skillpkg.json
*/
async generate(config: ProjectConfig): Promise<void> {
const content = JSON.stringify(config, null, 2);
await fs.writeFile('skillpkg.json', content);
}
}CLI 命令
// packages/cli/src/commands/init.ts
program
.command('init')
.description('Initialize project configuration (skillpkg.json)')
.option('-i, --interactive', '互動模式')
.action(async (options) => {
const initializer = new ProjectInitializer();
const config = options.interactive
? await initializer.promptForOptions()
: initializer.getDefaultConfig(path.basename(process.cwd()));
await initializer.generate(config);
console.log('✓ Created skillpkg.json');
console.log('');
console.log('Next steps:');
console.log(' skillpkg sync # Sync to Claude Code');
});注意：skillpkg new 命令用於建立 SKILL.md，見 skill-format spec。
檔案變更清單
packages/core/src/
├── project/
│ ├── initializer.ts ← 新增
│ ├── defaults.ts ← 新增 (預設配置)
│ └── index.ts ← 新增
└── index.ts ← 更新導出
packages/cli/src/
├── commands/
│ └── init.ts ← 更新 (加入 --project)
└── index.ts依賴
{
"@inquirer/prompts": "^5.0.0" // 互動式詢問
}測試策略
1. 單元測試
- getDefaultConfig() 返回正確結構
- generate() 產生有效 JSON
2. 整合測試
skillpkg init --project產生 skillpkg.jsonskillpkg sync可正常執行
Skill Directory Support - 需求規格
背景
目前 skillpkg 只下載 SKILL.md 檔案。許多 skills 包含額外資源：
scripts/- 可執行腳本resources/- 參考文件、範本templates/- 程式碼範本examples/- 範例檔案
目標
支援下載完整 skill 目錄，包含所有子檔案和子目錄。
功能需求
F1: 目錄列舉
- 從 GitHub API 取得 skill 目錄的完整檔案清單
- 支援巢狀目錄結構
F2: 批次下載
- 下載 SKILL.md + 所有額外檔案
- 保持目錄結構
F3: 儲存擴展
- StoreManager 支援儲存額外檔案
- 保持現有 SKILL.md 解析邏輯
F4: 同步擴展
- Syncer 複製完整目錄（非只有 SKILL.md）
- 保持現有同步邏輯
非功能需求
- 向後相容：只有 SKILL.md 的 skills 繼續正常運作
- 效能：並行下載檔案
- 錯誤處理：單一檔案失敗不影響整體安裝
驗收標準
# 安裝含 scripts 的 skill
skillpkg install github:user/repo#skill-with-scripts
# 驗證目錄結構
ls .skillpkg/skills/skill-name/
# → SKILL.md
# → scripts/
# → resources/
# 同步後驗證
skillpkg sync
ls .claude/skills/skill-name/
# → SKILL.md
# → scripts/
# → resources/Related skills
Find SkillsSo their agent can intelligently recommend and install the right modular skills from the open ecosystem when they ask how to do something.3M27.9k
Lark Skill MakerRapidly create custom skills for Lark (Feishu) that can be invoked by their AI agents and automation workflows.513k
Skill CreatorGenerate, test, and iterate on new reusable agent skills directly inside their Claude or Cursor workflow.337k166k
BrainstormingTurn vague product ideas into clear, approved designs and specifications through guided collaborative dialogue before writing any code.307k265k
Writing Great SkillsCreate high-quality, reusable agent skills that other developers can discover and install from the Skillselion catalog.290k200k
Find SkillsInstantly surface the best relevant agent skills, MCP servers, and workflows across multiple registries before starting any new project.226k12Skill Developmentagents