mcp2skill-setup

Declarative setup CLI for FORCE Lab AI Agent Skills.

Eliminates duplicate setup.py scripts across AI Agent Skills by providing a unified mcp2skill-setup setup <skill-dir> command that reads a skill-setup.yaml config file.

Installation

pip install mcp2skill-setup
# or use without installing:
uvx mcp2skill-setup setup <skill-dir>

Usage

# Initialize a skill (reads skill-dir/skill-setup.yaml)
uvx mcp2skill-setup setup ~/.claude/skills/hitl
uvx mcp2skill-setup setup ~/.claude/skills/tapd-story-intake

# List configured MCP bakes
uvx mcp2skill-setup list-bakes

skill-setup.yaml Format

Each skill directory contains a skill-setup.yaml that declaratively describes:

• env: required environment variables and how to obtain them
• bakes: mcp2cli baked connections to create
• verify: post-setup verification steps

Env fetch strategies

Example: hitl skill

name: hitl
env:
  - key: HITL_CHAT_ID
    fetch: prompt
    prompt: "请输入企微群 Chat ID（格式: wrkXXXXX）"
    required: true
bakes:
  - name: hitl
    type: stdio
    command: "npx -y hitl-mcp --service-url https://hitl.woa.com/api --chat-id {HITL_CHAT_ID} --timeout 3600"
    clear_proxy: true
verify:
  - bake: hitl
    expect_tool: send-and-wait-reply

Example: tapd-story-intake skill (Playwright auto-fetch + optional HITL)

name: tapd-story-intake
env:
  - key: TAPD_ACCESS_TOKEN
    fetch: playwright
    url: "https://tapd.woa.com/platform/myhome#tab=tab-mytoken"
    pattern: "[a-f0-9]{40}"
    fallback: prompt
    prompt: "无法自动获取，请手动粘贴 TAPD token"
  - key: HITL_CHAT_ID
    fetch: prompt
    prompt: "请输入企微群 Chat ID（可选，留空跳过）"
    required: false
bakes:
  - name: tapd
    type: http
    url: "https://mcpgw.knot.woa.com/tapd/"
    auth_header: "X-Tapd-Access-Token:env:TAPD_ACCESS_TOKEN"
    transport: streamable
  - name: hitl
    type: stdio
    command: "npx -y hitl-mcp --service-url https://hitl.woa.com/api --chat-id {HITL_CHAT_ID} --timeout 3600"
    clear_proxy: true
    skip_if_empty: [HITL_CHAT_ID]
verify:
  - bake: tapd
    expect_list: true

Example: mr-review skill (auto-discover gongfeng token)

name: mr-review
env:
  - key: GONGFENG_ACCESS_TOKEN
    fetch: ai-platform-config
    server_hint: gongfeng
    fallback: prompt
    prompt: "请输入工蜂 Access Token"
    derive:
      - key: GONGFENG_AUTH_HEADER
        value: "Bearer {value}"
bakes:
  - name: gongfeng
    type: http
    url: "https://mcpgw.knot.woa.com/gongfeng"
    auth_header: "Authorization:env:GONGFENG_AUTH_HEADER"
    transport: streamable
verify:
  - bake: gongfeng
    tool: get-current-user
    expect_field: username

Publishing

cd infra/mcp2skill
pip install hatch
hatch build && hatch publish   # requires PyPI token

Development

pip install -e "."
mcp2skill-setup --help
mcp2skill-setup setup path/to/skill