skillbay 0.1.0__tar.gz

skillbay-0.1.0/.gitattributes

@@ -0,0 +1,13 @@
+# Normalize line endings: LF in the repository and in working trees.
+* text=auto eol=lf
+
+# Source files are always LF.
+*.py text eol=lf
+*.toml text eol=lf
+*.md text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+
+# Windows scripts keep CRLF.
+*.bat text eol=crlf
+*.ps1 text eol=crlf

skillbay-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write  # Required for creating releases
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  pypi-publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

skillbay-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Run tests
+        run: uv run pytest

skillbay-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Dependency lock file (library project - let consumers resolve versions)
+uv.lock
+
+# Test and tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/

skillbay-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

skillbay-0.1.0/AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md
+
+## 项目定位
+
+skillbay 是一个面向 LangChain 的、可插拔的、面向后端业务服务的 Agent Skill 系统。
+核心思路 1:1 借鉴 Claude Code 的 Skill 系统（参考其 Python 移植版），但按后端
+场景做了两项改造：技能是部署产物（构造时加载并锁定）、allowed-tools 工具闸
+（wrap_tool_call 强制执行）。
+
+完整的业务改造设计思路见 `README.md` / `README.zh-CN.md`，不要把设计论述写进
+py 文件头。包已从 `skillkit` 完成改名迁移，现在一律叫 `skillbay`。
+
+## 目录结构
+
+- `src/skillbay/` — 核心包（src 布局），五个模块：
+  - `middleware.py` — 主入口 `SkillMiddleware`（LangChain `AgentMiddleware`）。
+    含 skill 工具、allowed-tools 闸门（`check_allowed_tools` 纯函数）、
+    `before_model`（清单播报 + 压缩存活重注入）。改它之前先读 README 的
+    「业务改造」章节。
+  - `core.py` — `Skill` 数据模型、目录加载（约定 `<skills_dir>/<name>/SKILL.md`，
+    靠后目录覆盖靠前目录、按 realpath 去重）、清单格式化（1% 上下文预算 +
+    三级降级）。
+  - `expansion.py` — SKILL.md 展开管线，五步顺序固定不能颠倒：
+    Base directory 头 → 参数替换（$ARGUMENTS/$0/$foo）→ ${SKILL_DIR} →
+    ${SESSION_ID} → 可选 !`命令` shell 块。
+  - `frontmatter.py` — YAML 头解析。PyYAML 可选（没有则用平铺子集解析器），
+    解析失败先修特殊字符再重试——一个技能写坏不能拖垮 agent 启动。
+  - `__init__.py` — 公共 API 面；新增导出需同步 `__all__`。
+- `tests/` — pytest 测试（纯函数级 + 中间件集成）。
+- `pyproject.toml` — 包元数据与工具配置（Python >= 3.12，hatchling 构建，
+  pytest / ruff 配置）。
+- `uv.lock` / `.venv/` — uv 管理的锁文件与虚拟环境（Windows，
+  激活脚本在 `.venv/Scripts/`）。
+- `.python-version` — 钉住 Python 3.12。
+
+## 架构边界（改动必读）
+
+- 三层渐进式披露：① `before_model` 把预算化清单包进 `<system-reminder>` 作为
+  user 消息写入 state；② 模型调 `skill` 工具时展开 SKILL.md 全文作为
+  ToolMessage 返回；③ 正文里的相对路径靠 "Base directory" 头解析，由 agent
+  自己的文件工具按需读取（本中间件不提供文件工具）。
+- 技能记账（`announced_skills` / `skill_invocations`）放在 `SkillState`
+  （AgentState 扩展），不放进程级 dict——为了随 checkpointer 持久化、按
+  thread 隔离、resume 后不重复播报。
+- allowed-tools 闸门 `check_allowed_tools` 是纯函数（便于单测）：生效窗口从
+  成功的 "Launching skill:" ToolMessage 起，到下一条真实 user 消息止；多个
+  技能的白名单取并集；限制只紧不松；窗口内连 skill 工具本身也拦（防提权）。
+- 只有成功展开的技能调用才会激活其白名单（失败不能成为提权通道）。
+- `` !`命令` `` shell 块默认关闭（`enable_shell_blocks=False`），是安全开关。
+  Windows 注意：PATH 里的 bash 可能解析到未配置的 WSL 存根，输出需按 UTF-8
+  解码（`errors="replace"`，见 expansion.py）。
+- 技能集合在构造时一次性加载并锁定，不做运行时动态发现。
+
+## 环境与命令
+
+- 依赖已声明：`langchain`（1.x 的 `langchain.agents.middleware` API）/
+  `langgraph` / `pydantic` / `typing-extensions`；`pyyaml` 为可选 extras
+  （dev 组里也装了）。
+- `uv sync` 装依赖；`uv run pytest` 跑测试（当前 52 个全过）；
+  `uv run ruff check src tests` 与 `uv run ruff format src tests` 做 lint
+  和格式化；不要用裸 pip / python。
+
+## 约定
+
+- **py 文件只放 `src/` 或 `tests/`，绝不放仓库根目录。**
+- 代码注释与 docstring 用英文、保持简短；文件开头不写长篇设计论述（设计思路
+  进 README）。日志与提示文案用英文。
+- 日志用 `logging`（各模块 `logging.getLogger(__name__)`，包 logger 名
+  `skillbay`）；`verbose=True` 时由 `_install_verbose_handler` 挂
+  StreamHandler（`[skillbay]` 前缀）。不要用 print。
+- 技能名以目录名为准，frontmatter 里的 name 只是显示名。
+- Windows 环境运行：展开时把路径反斜杠统一为正斜杠（${SKILL_DIR} 处理），
+  新增路径相关逻辑沿用此约定。
+- 主分支是 `main`；提交信息用英文祈使句（chore/feat/test/docs 前缀）。

skillbay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ezzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skillbay-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.5
+Name: skillbay
+Version: 0.1.0
+Summary: Pluggable skill middleware for LangChain agents: a skill system designed for business services.
+Project-URL: Homepage, https://github.com/Ezzi/skillbay
+Project-URL: Repository, https://github.com/Ezzi/skillbay
+Project-URL: Issues, https://github.com/Ezzi/skillbay/issues
+Project-URL: Documentation, https://github.com/Ezzi/skillbay#readme
+Author: Ezzi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,langchain,llm,middleware,skill
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: langchain>=1.0
+Requires-Dist: langgraph>=1.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typing-extensions>=4.12
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0.1; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# skillbay
+
+**Pluggable skill middleware for LangChain — a skill system designed for business services.**
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+![Python](https://img.shields.io/badge/python-3.12+-3776AB?logo=python&logoColor=white)
+![LangChain](https://img.shields.io/badge/langchain-1.x-1C3C3C?logo=langchain&logoColor=white)
+![uv](https://img.shields.io/badge/uv-managed-DE5FE9)
+![Ruff](https://img.shields.io/badge/ruff-checked-261230?logo=ruff)
+
+</div>
+
+## Why skillbay
+
+Anthropic proposes a remarkably good skill model: a single `SKILL.md` file turns a
+directory of procedures, references and scripts into capabilities the model can discover
+on demand, load lazily, and execute precisely. It is one of the standout contributions of
+Anthropic's Harness team in this area, solving a classic problem — *how does one agent
+carry many specialties without blowing its context window?*
+
+The mechanism itself is general, but the mainstream implementation was built for one
+specific scenario: a developer's coding and workbench. skillbay moves it into another —
+**business services**: a consumer app's support entrance, a company's finance/HR
+assistant, an ops copilot wired into internal systems. The context-window problem to
+solve is the same, but the runtime environment and rules are completely different.
+
+| | Claude Code: coding / workbench | skillbay: business services |
+|---|---|---|
+| Who talks to the agent | A developer, able to judge "should this command run?" | An end customer or an employee — nobody able to review a tool call, and no conversation that can hang on a confirmation prompt |
+| What a skill is | A coding workflow, installed ad hoc by its user | A business capability — refund handling, reimbursement policy, leave inquiry — owned by the company and governed like any business code |
+| Whose authority the agent acts with | The developer's own account | The company's — customers never opted into the agent's internals, so blast radius must be bounded by design |
+| Session shape | One developer, one terminal session | Thousands of concurrent conversations, checkpointed and resumable |
+
+**skillbay** therefore ports the skill system 1:1 in semantics onto LangChain's middleware
+API, then deliberately diverges wherever the scenario — not the mechanics — demands it.
+These divergences are the real content of this project.
+
+## Business transformation
+
+### 1. Skills are deploy artifacts, not runtime discoveries
+
+In Claude Code, the person who installs a skill is the person affected by it — runtime
+discovery and skill marketplaces are reasonable. A business service breaks that symmetry:
+the company operates the agent, while customers and employees bear the consequences. The
+skills also differ in kind — refund rules, reimbursement workflows and HR policies are
+business capabilities, not developer conveniences. A skill "appearing" in a mounted
+directory would put unreviewed behavior in front of customers: no review, no version, no
+rollback.
+
+In a coding agent, the person who installs a skill is the person who uses it, so runtime
+discovery is reasonable. In a business service, developers provide the skills, customers
+use them, and the company bears the consequences. Skills must therefore be supplied by the
+backend team — there is no runtime discovery.
+
+skillbay therefore loads the skill set **once, at construction, and freezes it**:
+
+- Skills live in git, go through code review, and ship with the release.
+- Runtime file changes have no effect until the process restarts.
+- Skill identity is the directory name; the frontmatter `name` is display-only — renames on
+  disk cannot silently re-route behavior.
+
+### 2. The allowed-tools gate
+
+An agent in a business service acts as a customer-service/smart assistant — a
+customer-service skill must never reach tools beyond its charter. A skill's frontmatter can
+declare `allowed-tools`; while that skill is active, the middleware's `wrap_tool_call` hook
+**enforces** the whitelist on every single tool call — the model is not trusted to comply,
+it is prevented.
+
+The enforcement window is derived purely from the message history (no extra state to
+corrupt):
+
+- **Opens** when a skill call succeeds — its ToolMessage starts with `Launching skill:`.
+- **Closes** at the next real user message; `<system-reminder>` injections don't count as a
+  new task and don't close the window.
+- **Union**: when several skills are active at once, their whitelists are unioned, or
+  multiple skills are disallowed from being active simultaneously (a subagent mechanism can
+  be used to invoke multiple skills) — and it **only tightens**: a skill without
+  `allowed-tools` can never loosen an active restriction.
+- **The `skill` tool itself is blocked inside the window**: this closes the escalation path
+  of calling a restricted skill and then chaining into an unrestricted one.
+
+### 3. Accounting lives in agent state, not process globals
+
+The reference implementation records announced/invoked skills in module-level dicts — fine
+for one developer's single-session process; wrong for a customer-service system serving
+thousands of resumable, checkpointed conversations at once. skillbay puts both ledgers in
+`SkillState` (an `AgentState` extension), which gives three things:
+
+- **Persistence** — the ledgers survive checkpoints; no duplicate announcements after a
+  process resumes.
+- **Isolation** — per-thread state; concurrent conversations don't interfere with each
+  other.
+- **Summarization survival** — when a `SummarizationMiddleware` compresses away the turn
+  that invoked the skill, the invocation record stays in state. `before_model` notices the
+  `tool_call_id` is gone from the message list, re-expands the body, and injects it as a
+  system-reminder. The skill's guidance survives the compaction that killed its transcript.
+
+### 4. Skill dismissal — the model can release skills it no longer needs
+
+Other skill systems (Claude Code, Codex, Cursor, and every LangChain skill middleware we
+have seen) treat skill activation as fire-and-once: once a skill's body is injected, it
+occupies the context window until the conversation ends or the context is compacted away.
+That is fine for a developer session — the human knows when the task is done — but wrong
+for a service agent handling multi-turn conversations, which naturally drift across topics.
+
+skillbay introduces **skill dismissal**: the model can call `skill_dismiss` to release a
+skill whose scope no longer matches the conversation. After dismissal:
+
+- The skill's full body is **no longer re-injected** into the post-compaction context.
+- The dismissal is **persisted in agent state** (survives checkpoint/resume).
+- An **audit event** (`skill_dismissed`) records which skill was dismissed and why.
+
+The model decides when to dismiss based on the conversation — a customer who asks about
+refund policy and then pivots to shipping times does not need the refund skill's 12-step
+procedure consuming context for the rest of the session.
+
+It is a small mechanism, but it matters for long-lived service conversations, for two
+reasons: it reduces the number of tokens a backend service consumes, and it helps avoid
+topic drift.
+
+## Robustness design
+
+- **One broken skill never breaks startup.** Frontmatter parsing never throws: it tries the
+  raw text first, retries with auto-quoting on failure (guarding against the classic
+  `paths: **/*.{ts,tsx}` mistake), and degrades to an empty header as a last resort. A
+  skill missing its `description` is skipped with a warning, not fatal.
+- **Audit built in.** Five audit events (`skill_invoked`, `skill_reinjected`,
+  `skills_announced`, `tool_call_blocked`, `skill_dismissed`) flow through one callback
+  seam; wire it to your logging/metrics stack. Audit failures never take down the agent.
+- **Context budget with graceful degradation.** When the listing exceeds its 1% budget,
+  each description is truncated to an equal share of what remains; in the extreme case only
+  names are announced. The discovery layer never crowds out the task itself.
+
+### LangChain integration
+
+Wire it into any LangChain `create_agent` agent:
+
+```python
+from skillbay import SkillMiddleware
+
+mw = SkillMiddleware(
+    skills_dirs=["skills"],
+    audit=lambda event: print(event),  # route to your observability stack
+)
+agent = create_agent(model, tools=[...], middleware=[mw])
+```
+
+### Frontmatter reference
+
+| Field | Required | Effect |
+|---|---|---|
+| `description` | yes | Listing text; drives model selection. Missing → skill skipped. |
+| `allowed-tools` | no | Tool whitelist enforced while the skill's window is open. |
+| `arguments` | no | Declares named arguments (`$foo`), mapped positionally. |
+| `argument-hint` | no | Human-facing hint for the argument string. |
+| `when_to_use` | no | Extra trigger guidance, appended to the listing description. |
+| `disable-model-invocation` | no | Kept out of the listing; user-triggered only. |
+| `shell` | no | Interpreter for `` !`...` `` blocks (feature is off by default). |
+| `model` / `paths` / `version` | no | Parsed and carried; enforcement is on the roadmap. |

skillbay-0.1.0/README.md

@@ -0,0 +1,163 @@
+<div align="center">
+
+# skillbay
+
+**Pluggable skill middleware for LangChain — a skill system designed for business services.**
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+![Python](https://img.shields.io/badge/python-3.12+-3776AB?logo=python&logoColor=white)
+![LangChain](https://img.shields.io/badge/langchain-1.x-1C3C3C?logo=langchain&logoColor=white)
+![uv](https://img.shields.io/badge/uv-managed-DE5FE9)
+![Ruff](https://img.shields.io/badge/ruff-checked-261230?logo=ruff)
+
+</div>
+
+## Why skillbay
+
+Anthropic proposes a remarkably good skill model: a single `SKILL.md` file turns a
+directory of procedures, references and scripts into capabilities the model can discover
+on demand, load lazily, and execute precisely. It is one of the standout contributions of
+Anthropic's Harness team in this area, solving a classic problem — *how does one agent
+carry many specialties without blowing its context window?*
+
+The mechanism itself is general, but the mainstream implementation was built for one
+specific scenario: a developer's coding and workbench. skillbay moves it into another —
+**business services**: a consumer app's support entrance, a company's finance/HR
+assistant, an ops copilot wired into internal systems. The context-window problem to
+solve is the same, but the runtime environment and rules are completely different.
+
+| | Claude Code: coding / workbench | skillbay: business services |
+|---|---|---|
+| Who talks to the agent | A developer, able to judge "should this command run?" | An end customer or an employee — nobody able to review a tool call, and no conversation that can hang on a confirmation prompt |
+| What a skill is | A coding workflow, installed ad hoc by its user | A business capability — refund handling, reimbursement policy, leave inquiry — owned by the company and governed like any business code |
+| Whose authority the agent acts with | The developer's own account | The company's — customers never opted into the agent's internals, so blast radius must be bounded by design |
+| Session shape | One developer, one terminal session | Thousands of concurrent conversations, checkpointed and resumable |
+
+**skillbay** therefore ports the skill system 1:1 in semantics onto LangChain's middleware
+API, then deliberately diverges wherever the scenario — not the mechanics — demands it.
+These divergences are the real content of this project.
+
+## Business transformation
+
+### 1. Skills are deploy artifacts, not runtime discoveries
+
+In Claude Code, the person who installs a skill is the person affected by it — runtime
+discovery and skill marketplaces are reasonable. A business service breaks that symmetry:
+the company operates the agent, while customers and employees bear the consequences. The
+skills also differ in kind — refund rules, reimbursement workflows and HR policies are
+business capabilities, not developer conveniences. A skill "appearing" in a mounted
+directory would put unreviewed behavior in front of customers: no review, no version, no
+rollback.
+
+In a coding agent, the person who installs a skill is the person who uses it, so runtime
+discovery is reasonable. In a business service, developers provide the skills, customers
+use them, and the company bears the consequences. Skills must therefore be supplied by the
+backend team — there is no runtime discovery.
+
+skillbay therefore loads the skill set **once, at construction, and freezes it**:
+
+- Skills live in git, go through code review, and ship with the release.
+- Runtime file changes have no effect until the process restarts.
+- Skill identity is the directory name; the frontmatter `name` is display-only — renames on
+  disk cannot silently re-route behavior.
+
+### 2. The allowed-tools gate
+
+An agent in a business service acts as a customer-service/smart assistant — a
+customer-service skill must never reach tools beyond its charter. A skill's frontmatter can
+declare `allowed-tools`; while that skill is active, the middleware's `wrap_tool_call` hook
+**enforces** the whitelist on every single tool call — the model is not trusted to comply,
+it is prevented.
+
+The enforcement window is derived purely from the message history (no extra state to
+corrupt):
+
+- **Opens** when a skill call succeeds — its ToolMessage starts with `Launching skill:`.
+- **Closes** at the next real user message; `<system-reminder>` injections don't count as a
+  new task and don't close the window.
+- **Union**: when several skills are active at once, their whitelists are unioned, or
+  multiple skills are disallowed from being active simultaneously (a subagent mechanism can
+  be used to invoke multiple skills) — and it **only tightens**: a skill without
+  `allowed-tools` can never loosen an active restriction.
+- **The `skill` tool itself is blocked inside the window**: this closes the escalation path
+  of calling a restricted skill and then chaining into an unrestricted one.
+
+### 3. Accounting lives in agent state, not process globals
+
+The reference implementation records announced/invoked skills in module-level dicts — fine
+for one developer's single-session process; wrong for a customer-service system serving
+thousands of resumable, checkpointed conversations at once. skillbay puts both ledgers in
+`SkillState` (an `AgentState` extension), which gives three things:
+
+- **Persistence** — the ledgers survive checkpoints; no duplicate announcements after a
+  process resumes.
+- **Isolation** — per-thread state; concurrent conversations don't interfere with each
+  other.
+- **Summarization survival** — when a `SummarizationMiddleware` compresses away the turn
+  that invoked the skill, the invocation record stays in state. `before_model` notices the
+  `tool_call_id` is gone from the message list, re-expands the body, and injects it as a
+  system-reminder. The skill's guidance survives the compaction that killed its transcript.
+
+### 4. Skill dismissal — the model can release skills it no longer needs
+
+Other skill systems (Claude Code, Codex, Cursor, and every LangChain skill middleware we
+have seen) treat skill activation as fire-and-once: once a skill's body is injected, it
+occupies the context window until the conversation ends or the context is compacted away.
+That is fine for a developer session — the human knows when the task is done — but wrong
+for a service agent handling multi-turn conversations, which naturally drift across topics.
+
+skillbay introduces **skill dismissal**: the model can call `skill_dismiss` to release a
+skill whose scope no longer matches the conversation. After dismissal:
+
+- The skill's full body is **no longer re-injected** into the post-compaction context.
+- The dismissal is **persisted in agent state** (survives checkpoint/resume).
+- An **audit event** (`skill_dismissed`) records which skill was dismissed and why.
+
+The model decides when to dismiss based on the conversation — a customer who asks about
+refund policy and then pivots to shipping times does not need the refund skill's 12-step
+procedure consuming context for the rest of the session.
+
+It is a small mechanism, but it matters for long-lived service conversations, for two
+reasons: it reduces the number of tokens a backend service consumes, and it helps avoid
+topic drift.
+
+## Robustness design
+
+- **One broken skill never breaks startup.** Frontmatter parsing never throws: it tries the
+  raw text first, retries with auto-quoting on failure (guarding against the classic
+  `paths: **/*.{ts,tsx}` mistake), and degrades to an empty header as a last resort. A
+  skill missing its `description` is skipped with a warning, not fatal.
+- **Audit built in.** Five audit events (`skill_invoked`, `skill_reinjected`,
+  `skills_announced`, `tool_call_blocked`, `skill_dismissed`) flow through one callback
+  seam; wire it to your logging/metrics stack. Audit failures never take down the agent.
+- **Context budget with graceful degradation.** When the listing exceeds its 1% budget,
+  each description is truncated to an equal share of what remains; in the extreme case only
+  names are announced. The discovery layer never crowds out the task itself.
+
+### LangChain integration
+
+Wire it into any LangChain `create_agent` agent:
+
+```python
+from skillbay import SkillMiddleware
+
+mw = SkillMiddleware(
+    skills_dirs=["skills"],
+    audit=lambda event: print(event),  # route to your observability stack
+)
+agent = create_agent(model, tools=[...], middleware=[mw])
+```
+
+### Frontmatter reference
+
+| Field | Required | Effect |
+|---|---|---|
+| `description` | yes | Listing text; drives model selection. Missing → skill skipped. |
+| `allowed-tools` | no | Tool whitelist enforced while the skill's window is open. |
+| `arguments` | no | Declares named arguments (`$foo`), mapped positionally. |
+| `argument-hint` | no | Human-facing hint for the argument string. |
+| `when_to_use` | no | Extra trigger guidance, appended to the listing description. |
+| `disable-model-invocation` | no | Kept out of the listing; user-triggered only. |
+| `shell` | no | Interpreter for `` !`...` `` blocks (feature is off by default). |
+| `model` / `paths` / `version` | no | Parsed and carried; enforcement is on the roadmap. |