skill-finder

Skill Search and Discovery

Help users discover and install new Skills, browse installed Skills, and search for and download Skills from the community.

Use Cases

• The user says "Is there a Skill for XX" or "Help me find a skill that can do XX"
• The user says "What Skills do I have" or "List all skills"
• The user says "Install an XX Skill" or "Find a Skill from the community"
• The user wants to extend the Agent's capabilities and asks "Can it do XX" but there is currently no corresponding Skill
• The user mentions skills.sh or the Agent Skills ecosystem
• The user requests installing an MCP Server or MCP tool (such as chrome-mcp, filesystem-mcp, etc.)

---

Feature 1: Browse Installed Skills

List all installed Skills

Read skill_registry.yaml to get the complete list:

import os
import yaml
from pathlib import Path

instance_name = os.environ.get("AGENT_INSTANCE", "xiaodazi")
registry_path = Path(f"instances/{instance_name}/skills/skill_registry.yaml")
registry = yaml.safe_load(registry_path.read_text(encoding="utf-8"))

skills = registry.get("skills", [])
for s in skills:
    status_icon = {"ready": "✅", "need_auth": "🔐", "need_setup": "⚙️", "unavailable": "❌"}.get(s.get("status", ""), "❓")
    name = s.get("name", "")
    enabled = "启用" if s.get("enabled", True) else "禁用"
    print(f"{status_icon} {name} ({enabled})")

print(f"\n共 {len(skills)} 个 Skill")

View Skill Details

Read the SKILL.md of the specified Skill to get detailed information:

import os
from pathlib import Path

instance_name = os.environ.get("AGENT_INSTANCE", "xiaodazi")
skill_name = "要查看的skill名称"

# 按优先级搜索
for base in [
    Path(f"instances/{instance_name}/skills"),
    Path("skills/library"),
]:
    skill_md = base / skill_name / "SKILL.md"
    if skill_md.exists():
        content = skill_md.read_text(encoding="utf-8")
        print(content[:2000])  # 输出前 2000 字符
        break
else:
    print(f"未找到 Skill: {skill_name}")

Filter by Category

Read config/skills.yaml in skill_groups and display by group:

import os
import yaml
from pathlib import Path

instance_name = os.environ.get("AGENT_INSTANCE", "xiaodazi")
config_path = Path(f"instances/{instance_name}/config/skills.yaml")
config = yaml.safe_load(config_path.read_text(encoding="utf-8"))

groups = config.get("skill_groups", {})
for group_name, group_info in groups.items():
    if group_name.startswith("_"):
        continue
    desc = group_info.get("description", "")
    skills = group_info.get("skills", [])
    print(f"\n📂 {group_name} ({len(skills)} 个)")
    print(f"   {desc}")
    for s in skills:
        print(f"   - {s}")

---

Feature 2: Search Community Skills Online

Method A: Search via the Skill Hub index (recommended)

Search community Skills from the local Skill Hub index (available offline and fast):

import os
import yaml
from pathlib import Path

def search_skill_hub(query, tags=None):
    """从 Skill Hub 索引搜索 Skill"""
    index_path = Path("skills/hub/index.yaml")
    if not index_path.exists():
        print("Skill Hub 索引不存在，尝试方式 B")
        return []

    index = yaml.safe_load(index_path.read_text(encoding="utf-8"))
    skills = index.get("skills", [])
    query_lower = query.lower()

    results = []
    for s in skills:
        name = s.get("name", "")
        desc = s.get("description", "")
        skill_tags = s.get("tags", [])

        # 名称、描述、标签匹配
        match = (
            query_lower in name.lower()
            or query_lower in desc.lower()
            or any(query_lower in t.lower() for t in skill_tags)
        )
        # 标签过滤
        if tags:
            match = match and any(t in skill_tags for t in tags)

        if match:
            results.append(s)

    # 按推荐指数排序
    results.sort(key=lambda x: x.get("stars", 0), reverse=True)
    return results

results = search_skill_hub("搜索关键词")
for r in results:
    stars = "⭐" * r.get("stars", 0)
    print(f"📦 {r['name']} {stars}")
    print(f"   {r['description']}")
    print(f"   标签: {', '.join(r.get('tags', []))}")
    print(f"   来源: {r.get('repo', '')}")

Method B: Search via skills.sh

Use the npx skills find command to search the open Skill ecosystem:

npx skills find "搜索关键词"

If the user does not have Node.js installed or npx is unavailable, fall back to Method C.

Method C: Search via the GitHub API

Search well-known Skill repositories directly:

import urllib.request
import json

def search_github_skills(query, repos=None):
    """搜索 GitHub 上的 Skill 仓库"""
    if repos is None:
        repos = [
            "anthropics/skills",
            "vercel-labs/agent-skills",
        ]

    results = []
    for repo in repos:
        url = f"https://api.github.com/search/code?q={query}+filename:SKILL.md+repo:{repo}"
        req = urllib.request.Request(url, headers={"Accept": "application/vnd.github.v3+json"})
        try:
            with urllib.request.urlopen(req, timeout=10) as resp:
                data = json.loads(resp.read())
                for item in data.get("items", []):
                    path = item.get("path", "")
                    html_url = item.get("html_url", "")
                    parts = path.split("/")
                    if len(parts) >= 2:
                        skill_name = parts[-2]
                        results.append({
                            "name": skill_name,
                            "repo": repo,
                            "path": path,
                            "url": html_url,
                        })
        except Exception as e:
            print(f"搜索 {repo} 失败: {e}")

    return results

results = search_github_skills("关键词")
for r in results:
    print(f"📦 {r['name']} (from {r['repo']})")
    print(f"   {r['url']}")

Method D: Browse the skills.sh website

If none of the above methods are convenient, guide the user to visit https://skills.sh/ to browse and search online.

---

Feature 3: Install Community Skills

Download Skills from the Skill Hub index or GitHub and install them into the current instance.

Step 0: One-click install from the Hub index (recommended)

If the user found the desired Skill through Skill Hub, it can be installed directly:

import os
import yaml
import urllib.request
from pathlib import Path

def install_from_hub(skill_name):
    """从 Skill Hub 索引一键安装"""
    index_path = Path("skills/hub/index.yaml")
    if not index_path.exists():
        print("Skill Hub 索引不存在")
        return None

    index = yaml.safe_load(index_path.read_text(encoding="utf-8"))
    skills = index.get("skills", [])

    # 查找 Skill
    skill_info = next((s for s in skills if s["name"] == skill_name), None)
    if not skill_info:
        print(f"Hub 中未找到 Skill: {skill_name}")
        return None

    repo = skill_info["repo"]
    skill_path = skill_info["path"]

    # 下载
    content = download_skill(repo, skill_path)
    if not content:
        return None

    # 提示依赖信息
    requires = skill_info.get("requires", {})
    if requires:
        print(f"⚠️ 此 Skill 需要以下依赖:")
        if requires.get("bins"):
            print(f"   命令行工具: {', '.join(requires['bins'])}")
        if requires.get("env"):
            print(f"   环境变量: {', '.join(requires['env'])}")
        if requires.get("packages"):
            print(f"   Python 包: {', '.join(requires['packages'])}")

    return content

content = install_from_hub("要安装的skill名称")

Step 1: Download SKILL.md

import os
import urllib.request
from pathlib import Path

def download_skill(repo, skill_path):
    """从 GitHub 下载 SKILL.md"""
    raw_url = f"https://raw.githubusercontent.com/{repo}/main/{skill_path}"
    req = urllib.request.Request(raw_url)
    with urllib.request.urlopen(req, timeout=15) as resp:
        return resp.read().decode("utf-8")

# 示例：从 anthropics/skills 下载 frontend-design
content = download_skill("anthropics/skills", "skills/frontend-design/SKILL.md")
print(content[:500])

Step 2: Adapt the frontmatter

The frontmatter of a community Skill may not have the metadata.xiaodazi block, and it needs to be added:

import yaml

def adapt_frontmatter(content, instance_name="xiaodazi"):
    """为社区 Skill 添加实例适配的 metadata"""
    if not content.startswith("---"):
        return content

    parts = content.split("---", 2)
    if len(parts) < 3:
        return content

    meta = yaml.safe_load(parts[1])
    if not isinstance(meta, dict):
        return content

    # 补充 metadata.xiaodazi 块（如果缺失）
    if "metadata" not in meta:
        meta["metadata"] = {}
    if instance_name not in meta.get("metadata", {}):
        meta["metadata"][instance_name] = {
            "dependency_level": "builtin",
            "os": ["common"],
            "backend_type": "local",
            "user_facing": True,
        }

    # 重新组装
    new_frontmatter = yaml.dump(meta, allow_unicode=True, default_flow_style=False)
    return f"---\n{new_frontmatter}---{parts[2]}"

adapted = adapt_frontmatter(content)

Step 3: Save and register

import os
import yaml
from pathlib import Path

instance_name = os.environ.get("AGENT_INSTANCE", "xiaodazi")
skill_name = "下载的skill名称"

# 保存 SKILL.md
skill_dir = Path(f"instances/{instance_name}/skills/{skill_name}")
skill_dir.mkdir(parents=True, exist_ok=True)
(skill_dir / "SKILL.md").write_text(adapted_content, encoding="utf-8")

# 注册到 skill_registry.yaml
registry_path = Path(f"instances/{instance_name}/skills/skill_registry.yaml")
registry = yaml.safe_load(registry_path.read_text(encoding="utf-8"))
skills_list = registry.get("skills", [])

if not any(s.get("name") == skill_name for s in skills_list):
    skills_list.append({
        "name": skill_name,
        "enabled": True,
        "status": "ready",
    })
    registry["skills"] = skills_list
    registry_path.write_text(
        yaml.dump(registry, allow_unicode=True, default_flow_style=False),
        encoding="utf-8",
    )

print(f"✅ {skill_name} 已安装到 {skill_dir}")
print(f"   当前对话即可使用（Agent 会按路径读取 SKILL.md）")

---

Common Skill Sources

Source	URL	Features
Anthropic Official	anthropics/skills	High-quality examples, including document processing, frontend design, MCP construction, etc.
Vercel Agent Skills	vercel-labs/agent-skills	Community selections, covering React/Next.js best practices, etc.
Skills Directory	https://skills.sh	Open ecosystem search engine

Available Skills in the Anthropic Repository

• algorithmic-art — Algorithmic art generation
• brand-guidelines — Brand guidelines
• canvas-design — Canvas design
• doc-coauthoring — Document collaboration
• frontend-design — Frontend design
• internal-comms — Internal communication
• mcp-builder — MCP Server construction
• slack-gif-creator — Slack GIF creation
• theme-factory — Theme factory
• web-artifacts-builder — Web component construction
• webapp-testing — Web application testing

---

---

Feature 4: Handle MCP-related Requests

When the user requests installing an MCP tool (such as "chrome-mcp", "filesystem-mcp", etc.), handle it according to the following process:

Decision Process

用户说「安装 XX-mcp」或「用 MCP 连接 XX」
    │
    ├── 1. 先检查已安装的 Skill 是否已有该能力
    │      （如用户要 chrome-mcp → 检查是否有 browser 工具可替代）
    │      → 有替代方案 → 告知用户并演示
    │
    ├── 2. 检查 skill_registry.yaml 中是否有同名 MCP Skill
    │      → 有 → 直接使用
    │
    ├── 3. 搜索社区是否有对应 Skill
    │      → 有 → 下载安装（走功能 3 的流程）
    │
    └── 4. 都没有 → 引导用户用 skill-creator 创建 MCP Skill
           需要用户提供：
           - MCP Server 的 URL（本地或远程）
           - 认证方式（如需要）
           - MCP Server 提供的工具列表

Key Principles

• Do not blindly install npm packages. An MCP Server requires connection configuration through the framework via backend_type: mcp and server_url ; it won't work just by installing an npm package
• Do not install system-level dependencies(homebrew, node, etc.) to "patch together" an MCP Server. This exceeds the responsibilities of skill-finder
• Evaluate alternatives first. Many MCP tool features can be implemented with existing Skills or tools (e.g., the browser tool instead of chrome-mcp, the nodes tool instead of filesystem-mcp)
• If it is confirmed that an MCP Skill needs to be created, guide the user to use skill-creator, which has a complete MCP Skill creation template

Output Specifications

• When listing Skills, use a table or checklist format, including name, status, and brief description
• After installation is complete, inform the user of the file path and suggest trial phrases
• If the search returns no results, suggest that the user use skill-creator to create one themselves
• Before installing a community Skill, first use the hitl tool to request user confirmation (show a summary of the Skill content)
• For MCP-related requests: first explain how the framework's MCP works, then guide the next step