# LangSkills

Python SDK for Skills — 轻松集成到 LangChain 的 skills 功能，支持**渐进式披露**（Progressive Disclosure）。

## 特性

- **渐进式披露**：启动时只加载每个 Skill 的 frontmatter（name、description），完整内容在 agent 选择该 skill 后才加载
- **节省 Token**：避免将大量 skill 全文一次性注入 context
- **LangChain 原生集成**：提供 `load_skill` Tool，与 LangChain / LangGraph agent 无缝配合
- **标准 Skill 格式**：遵循 [Agent Skills](https://agentskills.io/) / Cursor SKILL.md 规范

## 安装

```bash
pip install langskills
# 或
uv add langskills
```

## 快速开始

### 1. 准备 Skills 目录

每个 skill 是一个子目录，包含 `SKILL.md`：

```
skills/
├── pdf_parser/
│   └── SKILL.md
├── excel_analysis/
│   └── SKILL.md
└── code_review/
    └── SKILL.md
```

`SKILL.md` 格式（YAML frontmatter + Markdown body）：

```markdown
---
name: PDF Text Extractor
description: Extract text and basic structure from PDF documents
version: 1.0
---

This skill parses PDF files and returns cleaned text with page numbers.
Use it when you need to feed document content into an LLM.
```

### 2. 集成到 LangChain

```python
from langskills import SkillsLoader

loader = SkillsLoader.from_directory("./skills")
tools = loader.to_langchain_tools()  # 返回 [load_skill] Tool

# 传给 agent
agent = create_agent(model, tools=tools)
```

### 3. 渐进式披露流程

1. Agent 启动时只看到 `load_skill` 的 description（列出所有 skills 的 name + description）
2. 用户提问时，agent 判断是否需要某 skill
3. 若需要，调用 `load_skill(skill_name="PDF Text Extractor")` 加载完整内容
4. 根据加载的内容执行任务

## API

### SkillsLoader

```python
from langskills import SkillsLoader

loader = SkillsLoader.from_directory("./skills")

# 列出所有 skill 名称
loader.list_skill_names()

# 获取 skill 简要信息（仅 metadata）
loader.get_skill_summaries()

# 按需加载完整内容
loader.load_skill_content("PDF Text Extractor")
```

### LangChain 集成

```python
from langskills import SkillsLoader, create_load_skill_tool, to_langchain_tools

loader = SkillsLoader.from_directory("./skills")

# 方式 1：直接获取 tools 列表
tools = loader.to_langchain_tools()

# 方式 2：仅创建 load_skill Tool
load_skill_tool = create_load_skill_tool(loader)
```

## 开发与测试

```bash
# 安装开发依赖
uv sync  # 或 pip install -e ".[dev]"

# 运行测试
pytest
```

## 发布到 PyPI

```bash
# 安装构建工具
pip install build twine

# 构建
uv build
# 或: python -m build

# 上传（需要 PyPI 账号，首次需配置 ~/.pypirc）
twine upload dist/*
```

## License

MIT
