Back to Details

inspecting-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Inspecting Skills

技能检查

Discover Python code across skills and enable universal imports. Solves the dash-underscore naming mismatch between skill directories (e.g., 
browsing-bluesky
) and Python imports (e.g., 
browsing_bluesky
).
跨技能发现Python代码并支持通用导入。解决技能目录（如
browsing-bluesky
）与Python导入（如
browsing_bluesky
）之间的短横线与下划线命名不匹配问题。

Installation

安装

python
import sys
sys.path.insert(0, '/home/user/claude-skills')
from inspecting_skills import setup_skill_path, skill_import
python
import sys
sys.path.insert(0, '/home/user/claude-skills')
from inspecting_skills import setup_skill_path, skill_import

Quick Start

快速开始

Import a Skill

导入技能

python
from inspecting_skills import skill_import
python
from inspecting_skills import skill_import

Import by skill name (dash or underscore form)

通过技能名称导入（短横线或下划线形式）

bsky = skill_import("browsing-bluesky") posts = bsky.search_posts("python")
bsky = skill_import("browsing-bluesky") posts = bsky.search_posts("python")

Import specific functions

导入特定函数

search, profile = skill_import("browsing-bluesky", ["search_posts", "get_profile"])
undefined
search, profile = skill_import("browsing-bluesky", ["search_posts", "get_profile"])
undefined

Enable Transparent Imports

启用透明导入

python
from inspecting_skills import setup_skill_path
python
from inspecting_skills import setup_skill_path

Configure once at session start

在会话开始时配置一次

setup_skill_path("/home/user/claude-skills")
setup_skill_path("/home/user/claude-skills")

Now import skills directly (underscore form)

现在可以直接导入技能（下划线形式）

from browsing_bluesky import search_posts, get_profile from remembering import remember, recall
undefined
from browsing_bluesky import search_posts, get_profile from remembering import remember, recall
undefined

Discover Available Skills

发现可用技能

python
from inspecting_skills import list_importable_skills

skills = list_importable_skills()
for s in skills:
    print(f"{s['name']} -> import {s['module_name']}")
python
from inspecting_skills import list_importable_skills

skills = list_importable_skills()
for s in skills:
    print(f"{s['name']} -> import {s['module_name']}")

Core Functions

核心功能

Discovery

发现功能

FunctionPurpose
discover_skill(path)
Analyze a single skill directory
discover_all_skills(root)
Find all skills with Python code
find_skill_by_name(name, root)
Find skill by name (either form)
skill_name_to_module(name)
Convert "browsing-bluesky" to "browsing_bluesky"
函数用途
discover_skill(path)
分析单个技能目录
discover_all_skills(root)
查找所有包含Python代码的技能
find_skill_by_name(name, root)
通过名称查找技能（两种命名形式均可）
skill_name_to_module(name)
将"browsing-bluesky"转换为"browsing_bluesky"

Indexing

索引功能

FunctionPurpose
index_skill(layout)
Extract symbols from a discovered skill
index_all_skills(root)
Index all skills in repository
generate_registry(root, output)
Create registry.json manifest
函数用途
index_skill(layout)
从已发现的技能中提取符号
index_all_skills(root)
索引代码库中的所有技能
generate_registry(root, output)
创建registry.json清单文件

Importing

导入功能

FunctionPurpose
setup_skill_path(root)
Enable transparent skill imports
skill_import(name, symbols)
Import skill or specific symbols
register_skill(name, path)
Register skill at custom path
list_importable_skills()
List all importable skills
函数用途
setup_skill_path(root)
启用技能透明导入
skill_import(name, symbols)
导入技能或特定符号
register_skill(name, path)
在自定义路径注册技能
list_importable_skills()
列出所有可导入的技能

Skill Layouts

技能布局

Skills organize Python code in three patterns:
技能中的Python代码有三种组织模式：

1. Scripts Directory

1. 脚本目录结构

browsing-bluesky/
  SKILL.md
  __init__.py          # Re-exports from scripts/
  scripts/
    __init__.py
    bsky.py            # Main implementation
browsing-bluesky/
  SKILL.md
  __init__.py          # 重新导出scripts/中的内容
  scripts/
    __init__.py
    bsky.py            # 主要实现代码

2. Root-Level Modules

2. 根级别模块结构

remembering/
  SKILL.md
  __init__.py          # Re-exports functions
  memory.py            # Core functionality
  boot.py
  config.py
remembering/
  SKILL.md
  __init__.py          # 导出函数
  memory.py            # 核心功能代码
  boot.py
  config.py

3. Simple Package

3. 简单包结构

simple-skill/
  SKILL.md
  __init__.py          # Contains all code
simple-skill/
  SKILL.md
  __init__.py          # 包含所有代码

Generating a Registry

生成注册表

Create a 
registry.json
for offline symbol lookup:
python
from inspecting_skills import generate_registry
from pathlib import Path

registry = generate_registry(
    Path("/home/user/claude-skills"),
    output_path=Path("registry.json")
)
创建
registry.json
文件用于离线符号查找：
python
from inspecting_skills import generate_registry
from pathlib import Path

registry = generate_registry(
    Path("/home/user/claude-skills"),
    output_path=Path("registry.json")
)

Registry structure:

注册表结构:

{

{

"version": "1.0.0",

"version": "1.0.0",

"skills": {

"skills": {

"browsing-bluesky": {

"browsing-bluesky": {

"module_name": "browsing_bluesky",

"module_name": "browsing_bluesky",

"exports": ["search_posts", "get_profile", ...],

"exports": ["search_posts", "get_profile", ...],

"modules": [...]

"modules": [...]

}

}

}

}

}

}

undefined
undefined

Indexing a Single Skill

索引单个技能

python
from inspecting_skills import discover_skill, index_skill
from pathlib import Path
python
from inspecting_skills import discover_skill, index_skill
from pathlib import Path

Discover the skill layout

发现技能布局

layout = discover_skill(Path("/home/user/claude-skills/remembering")) print(f"Layout: {layout.layout_type}") print(f"Has init.py: {layout.has_init}") print(f"Python files: {[f.name for f in layout.python_files]}")
layout = discover_skill(Path("/home/user/claude-skills/remembering")) print(f"布局类型: {layout.layout_type}") print(f"包含__init__.py: {layout.has_init}") print(f"Python文件: {[f.name for f in layout.python_files]}")

Index symbols

索引符号

index = index_skill(layout) for module in index.modules: print(f"\n{module.file_path}:") for sym in module.symbols: print(f" {sym.kind} {sym.name}{sym.signature or ''}")
undefined
index = index_skill(layout) for module in index.modules: print(f"\n{module.file_path}:") for sym in module.symbols: print(f" {sym.kind} {sym.name}{sym.signature or ''}")
undefined

Integration with mapping-codebases

与mapping-codebases集成

This skill complements 
mapping-codebases
which generates 
_MAP.md
files:
  • mapping-codebases: Static documentation via tree-sitter, multi-language
  • inspecting-skills: Runtime import support, Python-focused, dynamic discovery
Use both together:
  1. mapping-codebases
    for navigation and code review
  2. inspecting-skills
    for actual code imports and execution
本工具与
mapping-codebases
互补，后者用于生成
_MAP.md
文件：
  • mapping-codebases: 基于tree-sitter的静态文档工具，支持多语言
  • inspecting-skills: 运行时导入支持工具，专注于Python，支持动态发现
两者结合使用：
  1. 使用
    mapping-codebases
    进行导航和代码审查
  2. 使用
    inspecting-skills
    进行实际的代码导入和执行

Troubleshooting

故障排除

Import Errors

导入错误

python
undefined
python
undefined

If skill_import fails, check:

如果skill_import失败，请检查：

1. Skill exists and has init.py

1. 技能存在且包含__init__.py

from inspecting_skills import discover_skill layout = discover_skill(Path("/path/to/skill")) print(layout.has_init) # Must be True for importing
from inspecting_skills import discover_skill layout = discover_skill(Path("/path/to/skill")) print(layout.has_init) # 导入必须确保此值为True

2. Skills root is configured

2. 已配置技能根目录

from inspecting_skills import get_skills_root print(get_skills_root())
from inspecting_skills import get_skills_root print(get_skills_root())

3. Symbol is exported in all

3. 符号已在__all__中导出

import ast init_code = open("/path/to/skill/init.py").read()
import ast init_code = open("/path/to/skill/init.py").read()

Check for all definition

检查__all__定义

undefined
undefined

Path Not Found

路径未找到

python
undefined
python
undefined

Manually set skills root

手动设置技能根目录

from inspecting_skills import set_skills_root set_skills_root("/home/user/claude-skills")
undefined
from inspecting_skills import set_skills_root set_skills_root("/home/user/claude-skills")
undefined

API Reference

API参考

SkillLayout

SkillLayout

python
@dataclass
class SkillLayout:
    name: str              # "browsing-bluesky"
    path: Path             # Full path to skill directory
    layout_type: str       # "scripts" | "root" | "package" | "none"
    python_files: list[Path]
    has_init: bool         # Can be imported as package
    entry_module: str      # "browsing_bluesky"
python
@dataclass
class SkillLayout:
    name: str              # "browsing-bluesky"
    path: Path             # 技能目录的完整路径
    layout_type: str       # "scripts" | "root" | "package" | "none"
    python_files: list[Path]
    has_init: bool         # 是否可作为包导入
    entry_module: str      # "browsing_bluesky"

SkillIndex

SkillIndex

python
@dataclass
class SkillIndex:
    name: str              # "browsing-bluesky"
    module_name: str       # "browsing_bluesky"
    layout_type: str
    modules: list[ModuleIndex]
    exports: list[str]     # From __all__
python
@dataclass
class SkillIndex:
    name: str              # "browsing-bluesky"
    module_name: str       # "browsing_bluesky"
    layout_type: str
    modules: list[ModuleIndex]
    exports: list[str]     # 来自__all__的导出内容

Symbol

Symbol

python
@dataclass
class Symbol:
    name: str              # Function/class name
    kind: str              # "function" | "class" | "method"
    signature: str | None  # "(self, x: int)"
    line: int | None       # 1-indexed
    docstring: str | None  # First line
    children: list[Symbol] # Methods for classes
python
@dataclass
class Symbol:
    name: str              # 函数/类名称
    kind: str              # "function" | "class" | "method"
    signature: str | None  # "(self, x: int)"
    line: int | None       # 从1开始的行号
    docstring: str | None  # 第一行文档字符串
    children: list[Symbol] # 类的方法