inspecting-skills

スキルの調査

スキル全体から Python コードを検出し、あらゆるスキルをインポートできるようにします。スキルディレクトリ（例：browsing-bluesky）と Python のインポート名（例：browsing_bluesky）の間にある、ハイフンとアンダースコアの命名の不一致を解消します。

インストール

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

クイックスタート

スキルをインポートする

from inspecting_skills import skill_import

# Import by skill name (dash or underscore form)
bsky = skill_import("browsing-bluesky")
posts = bsky.search_posts("python")

# Import specific functions
search, profile = skill_import("browsing-bluesky", ["search_posts", "get_profile"])

透過的なインポートを有効にする

from inspecting_skills import setup_skill_path

# Configure once at session start
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

利用可能なスキルを検出する

from inspecting_skills import list_importable_skills

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

主な関数

検出

関数	目的
discover_skill(path)	単一のスキルディレクトリを分析します
discover_all_skills(root)	Python コードを含むすべてのスキルを検出します
find_skill_by_name(name, root)	名前（どちらの形式でも）でスキルを検索します
skill_name_to_module(name)	「browsing-bluesky」を「browsing_bluesky」に変換します

インデックス作成

関数	目的
index_skill(layout)	検出したスキルからシンボルを抽出します
index_all_skills(root)	リポジトリ内のすべてのスキルのインデックスを作成します
generate_registry(root, output)	registry.json マニフェストを作成します

インポート

関数	目的
setup_skill_path(root)	透過的なスキルのインポートを有効にします
skill_import(name, symbols)	スキルまたは特定のシンボルをインポートします
register_skill(name, path)	カスタムパスにスキルを登録します
list_importable_skills()	インポート可能なすべてのスキルを一覧表示します

スキルのレイアウト

スキルでは、次の 3 つのパターンで Python コードを整理します。

1. スクリプトディレクトリ

browsing-bluesky/
  SKILL.md
  __init__.py          # Re-exports from scripts/
  scripts/
    __init__.py
    bsky.py            # Main implementation

2. ルートレベルのモジュール

remembering/
  SKILL.md
  __init__.py          # Re-exports functions
  memory.py            # Core functionality
  boot.py
  config.py

3. シンプルなパッケージ

simple-skill/
  SKILL.md
  __init__.py          # Contains all code

レジストリを生成する

オフラインでシンボルを検索できるように、registry.json を作成します。

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",
#   "skills": {
#     "browsing-bluesky": {
#       "module_name": "browsing_bluesky",
#       "exports": ["search_posts", "get_profile", ...],
#       "modules": [...]
#     }
#   }
# }

単一のスキルのインデックスを作成する

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]}")

# 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 ''}")

tree-sitting との連携

このスキルは、実行時にコード構造を抽出する tree-sitting を補完します。

• tree-sitting：tree-sitter を介して AST から構造を導出します。複数の言語に対応します
• inspecting-skills：実行時のインポートをサポートします。Python に特化し、動的に検出します

両方を組み合わせて使用します。

1. ナビゲーションとコードレビューには tree-sitting を使用します
2. 実際のコードのインポートと実行には inspecting-skills を使用します

トラブルシューティング

インポートエラー

# If skill_import fails, check:

# 1. Skill exists and has __init__.py
from inspecting_skills import discover_skill
layout = discover_skill(Path("/path/to/skill"))
print(layout.has_init)  # Must be True for importing

# 2. Skills root is configured
from inspecting_skills import get_skills_root
print(get_skills_root())

# 3. Symbol is exported in __all__
import ast
init_code = open("/path/to/skill/__init__.py").read()
# Check for __all__ definition

パスが見つからない場合

# Manually set skills root
from inspecting_skills import set_skills_root
set_skills_root("/home/user/claude-skills")

API リファレンス

SkillLayout

@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"

SkillIndex

@dataclass
class SkillIndex:
    name: str              # "browsing-bluesky"
    module_name: str       # "browsing_bluesky"
    layout_type: str
    modules: list[ModuleIndex]
    exports: list[str]     # From __all__

Symbol

@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