skill-capture 1.0.0__tar.gz

skill_capture-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

skill_capture-1.0.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: skill-capture
+Version: 1.0.0
+Summary: A privacy-first AI agent that learns your workflows and turns them into one-click Skills.
+Author: SkillCapture Contributors
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: apscheduler>=3.10.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: google-genai>=1.0.0
+Dynamic: license-file
+
+# SkillCapture 🧠
+
+A **privacy-first, local AI agent** that watches your daily chats, automatically learns your repetitive workflows, and turns them into one-click **Skills** — all stored safely on your own hard drive.
+
+Built with [FastMCP](https://github.com/jlowin/fastmcp) · Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.
+
+---
+
+## How It Works
+
+SkillCapture uses a **two-tier pipeline** inspired by how human memory consolidation works:
+
+### Day 1 — Lightweight Draft (Cheap)
+The AI scans your chat log and extracts potential workflows into a flat JSON cache. No heavy processing — just keywords and action summaries.
+
+### Day 2 — Heavy Promotion (Only on Match)
+If you repeat a workflow, the system detects the keyword overlap and *only then* triggers the expensive generation: building a full, reusable Skill with named variables, step-by-step actions, and trigger phrases.
+
+```
+DISCOVERED → PENDING → PROMOTED → DEPRECATED
+   (Day 1)    (Cache)   (Vault)    (30d unused)
+```
+
+### The Storage Architecture
+
+| Layer | Location | Purpose |
+|-------|----------|---------|
+| **The Sandbox** | `data/pending.json` | Lightweight Day 1 cache — fast read/write |
+| **The Vault** | `skills/*.md` | Promoted skills as human-readable Markdown with YAML frontmatter |
+| **The Index** | `skills/index.json` | Ultra-light manifest so the AI never overloads its context window |
+
+Skills are stored as **Markdown files** — you can read, edit, and version-control them with Git.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+**Python (uvx / pipx)** 🐍
+```bash
+uvx skill-capture-mcp
+# or
+pipx install skill-capture
+```
+
+### 2. Configure your LLM provider
+
+```bash
+cp .env.example .env
+# Edit .env with your provider and API key
+```
+
+SkillCapture ships with **three built-in providers**. Set `LLM_PROVIDER` in `.env`:
+
+| Provider | `LLM_PROVIDER` | API Key Env Var | Default Model |
+|----------|---------------|-----------------|---------------|
+| OpenAI | `openai` | `OPENAI_API_KEY` | `gpt-4o-mini` |
+| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| Google Gemini | `gemini` | `GOOGLE_API_KEY` | `gemini-2.0-flash` |
+
+> **Extensible**: Need a different provider? Implement the `LLMClient.chat()` interface in `core/providers.py`.
+
+### 3. Run the MCP Server
+
+```bash
+skill-capture-mcp
+# (or `npx @YOUR_USERNAME/skill-capture-mcp`)
+```
+
+Then connect from **Claude Desktop**, **Cursor**, **Windsurf**, or any MCP-compatible client.
+
+### 4. Connect to your MCP client
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "skill-capture": {
+      "command": "python",
+      "args": ["/absolute/path/to/skill-capture/server.py"],
+      "env": { "LLM_PROVIDER": "openai", "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "skill-capture": {
+      "command": "skill-capture-mcp",
+      "args": [],
+      "env": { "LLM_PROVIDER": "openai", "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "skill-capture": {
+      "command": "skill-capture-mcp",
+      "args": [],
+      "env": { "LLM_PROVIDER": "openai", "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Codex CLI</strong></summary>
+
+Run:
+
+```bash
+codex mcp add skill-capture -- skill-capture-mcp
+```
+
+Or add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.skill-capture]
+type = "stdio"
+command = "skill-capture-mcp"
+args = []
+
+[mcp_servers.skill-capture.env]
+LLM_PROVIDER = "openai"
+OPENAI_API_KEY = "sk-..."
+```
+</details>
+
+---
+
+## CLI Mode
+
+Don't need MCP? Use SkillCapture standalone from the terminal:
+
+```bash
+skill-capture-cli analyze           # Run the Day 1/Day 2 pipeline
+skill-capture-cli list              # List all promoted skills
+skill-capture-cli pending           # View pending drafts in the sandbox
+skill-capture-cli run "Deploy App"  # Load and display a specific skill
+```
+
+---
+
+## MCP Tools
+
+Once connected, your AI client has access to these tools:
+
+| Tool | Description |
+|------|-------------|
+| `list_skills()` | Browse all promoted skills (reads the lightweight index) |
+| `run_skill(name)` | Load the full content of a specific skill from the Vault |
+| `analyze_today()` | Manually trigger the Day 1/Day 2 pipeline |
+| `get_pending()` | View workflow drafts sitting in the sandbox |
+
+---
+
+## Project Structure
+
+```
+skill-capture/
+├── data/
+│   └── pending.json          # The Sandbox
+├── skills/
+│   ├── index.json            # The Index
+│   └── *.md                  # The Vault
+├── logs/                     # Daily chat logs (input)
+├── core/
+│   ├── models.py             # Two-tier Pydantic schemas
+│   ├── storage.py            # File-system I/O layer
+│   ├── evaluator.py          # LLM client interface + evaluator logic
+│   ├── providers.py          # OpenAI, Anthropic, Gemini clients
+│   └── scheduler.py          # APScheduler nightly worker
+├── server.py                 # FastMCP server
+├── cli.py                    # Standalone CLI interface
+└── requirements.txt
+```
+
+---
+
+## Tech Stack
+
+- **Python** — Core language
+- **[FastMCP](https://github.com/jlowin/fastmcp)** — Model Context Protocol server framework
+- **[Pydantic](https://docs.pydantic.dev/)** — Structured data validation
+- **[OpenAI](https://platform.openai.com/) · [Anthropic](https://docs.anthropic.com/) · [Google Gemini](https://ai.google.dev/)** — LLM providers (swappable)
+- **[python-frontmatter](https://github.com/eyeseast/python-frontmatter)** — Markdown + YAML parsing
+- **[APScheduler](https://apscheduler.readthedocs.io/)** — Background task scheduling
+
+---
+
+## Contributing
+
+Contributions are welcome! Some ideas:
+
+- 🔌 Add more LLM providers (Ollama, local models)
+- 🎨 Build the web UI for skill management
+- 📊 Add usage analytics and skill effectiveness tracking
+- 🧪 Improve the keyword matching with embeddings
+- 📝 Add support for more chat log formats
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

skill_capture-1.0.0/README.md

@@ -0,0 +1,228 @@
+# SkillCapture 🧠
+
+A **privacy-first, local AI agent** that watches your daily chats, automatically learns your repetitive workflows, and turns them into one-click **Skills** — all stored safely on your own hard drive.
+
+Built with [FastMCP](https://github.com/jlowin/fastmcp) · Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.
+
+---
+
+## How It Works
+
+SkillCapture uses a **two-tier pipeline** inspired by how human memory consolidation works:
+
+### Day 1 — Lightweight Draft (Cheap)
+The AI scans your chat log and extracts potential workflows into a flat JSON cache. No heavy processing — just keywords and action summaries.
+
+### Day 2 — Heavy Promotion (Only on Match)
+If you repeat a workflow, the system detects the keyword overlap and *only then* triggers the expensive generation: building a full, reusable Skill with named variables, step-by-step actions, and trigger phrases.
+
+```
+DISCOVERED → PENDING → PROMOTED → DEPRECATED
+   (Day 1)    (Cache)   (Vault)    (30d unused)
+```
+
+### The Storage Architecture
+
+| Layer | Location | Purpose |
+|-------|----------|---------|
+| **The Sandbox** | `data/pending.json` | Lightweight Day 1 cache — fast read/write |
+| **The Vault** | `skills/*.md` | Promoted skills as human-readable Markdown with YAML frontmatter |
+| **The Index** | `skills/index.json` | Ultra-light manifest so the AI never overloads its context window |
+
+Skills are stored as **Markdown files** — you can read, edit, and version-control them with Git.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+**Python (uvx / pipx)** 🐍
+```bash
+uvx skill-capture-mcp
+# or
+pipx install skill-capture
+```
+
+### 2. Configure your LLM provider
+
+```bash
+cp .env.example .env
+# Edit .env with your provider and API key
+```
+
+SkillCapture ships with **three built-in providers**. Set `LLM_PROVIDER` in `.env`:
+
+| Provider | `LLM_PROVIDER` | API Key Env Var | Default Model |
+|----------|---------------|-----------------|---------------|
+| OpenAI | `openai` | `OPENAI_API_KEY` | `gpt-4o-mini` |
+| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| Google Gemini | `gemini` | `GOOGLE_API_KEY` | `gemini-2.0-flash` |
+
+> **Extensible**: Need a different provider? Implement the `LLMClient.chat()` interface in `core/providers.py`.
+
+### 3. Run the MCP Server
+
+```bash
+skill-capture-mcp
+# (or `npx @YOUR_USERNAME/skill-capture-mcp`)
+```
+
+Then connect from **Claude Desktop**, **Cursor**, **Windsurf**, or any MCP-compatible client.
+
+### 4. Connect to your MCP client
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "skill-capture": {
+      "command": "python",
+      "args": ["/absolute/path/to/skill-capture/server.py"],
+      "env": { "LLM_PROVIDER": "openai", "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "skill-capture": {
+      "command": "skill-capture-mcp",
+      "args": [],
+      "env": { "LLM_PROVIDER": "openai", "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "skill-capture": {
+      "command": "skill-capture-mcp",
+      "args": [],
+      "env": { "LLM_PROVIDER": "openai", "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Codex CLI</strong></summary>
+
+Run:
+
+```bash
+codex mcp add skill-capture -- skill-capture-mcp
+```
+
+Or add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.skill-capture]
+type = "stdio"
+command = "skill-capture-mcp"
+args = []
+
+[mcp_servers.skill-capture.env]
+LLM_PROVIDER = "openai"
+OPENAI_API_KEY = "sk-..."
+```
+</details>
+
+---
+
+## CLI Mode
+
+Don't need MCP? Use SkillCapture standalone from the terminal:
+
+```bash
+skill-capture-cli analyze           # Run the Day 1/Day 2 pipeline
+skill-capture-cli list              # List all promoted skills
+skill-capture-cli pending           # View pending drafts in the sandbox
+skill-capture-cli run "Deploy App"  # Load and display a specific skill
+```
+
+---
+
+## MCP Tools
+
+Once connected, your AI client has access to these tools:
+
+| Tool | Description |
+|------|-------------|
+| `list_skills()` | Browse all promoted skills (reads the lightweight index) |
+| `run_skill(name)` | Load the full content of a specific skill from the Vault |
+| `analyze_today()` | Manually trigger the Day 1/Day 2 pipeline |
+| `get_pending()` | View workflow drafts sitting in the sandbox |
+
+---
+
+## Project Structure
+
+```
+skill-capture/
+├── data/
+│   └── pending.json          # The Sandbox
+├── skills/
+│   ├── index.json            # The Index
+│   └── *.md                  # The Vault
+├── logs/                     # Daily chat logs (input)
+├── core/
+│   ├── models.py             # Two-tier Pydantic schemas
+│   ├── storage.py            # File-system I/O layer
+│   ├── evaluator.py          # LLM client interface + evaluator logic
+│   ├── providers.py          # OpenAI, Anthropic, Gemini clients
+│   └── scheduler.py          # APScheduler nightly worker
+├── server.py                 # FastMCP server
+├── cli.py                    # Standalone CLI interface
+└── requirements.txt
+```
+
+---
+
+## Tech Stack
+
+- **Python** — Core language
+- **[FastMCP](https://github.com/jlowin/fastmcp)** — Model Context Protocol server framework
+- **[Pydantic](https://docs.pydantic.dev/)** — Structured data validation
+- **[OpenAI](https://platform.openai.com/) · [Anthropic](https://docs.anthropic.com/) · [Google Gemini](https://ai.google.dev/)** — LLM providers (swappable)
+- **[python-frontmatter](https://github.com/eyeseast/python-frontmatter)** — Markdown + YAML parsing
+- **[APScheduler](https://apscheduler.readthedocs.io/)** — Background task scheduling
+
+---
+
+## Contributing
+
+Contributions are welcome! Some ideas:
+
+- 🔌 Add more LLM providers (Ollama, local models)
+- 🎨 Build the web UI for skill management
+- 📊 Add usage analytics and skill effectiveness tracking
+- 🧪 Improve the keyword matching with embeddings
+- 📝 Add support for more chat log formats
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

skill_capture-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skill-capture"
+version = "1.0.0"
+description = "A privacy-first AI agent that learns your workflows and turns them into one-click Skills."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "SkillCapture Contributors" }
+]
+dependencies = [
+    "fastmcp>=2.0.0",
+    "pydantic>=2.0.0",
+    "openai>=1.0.0",
+    "python-frontmatter>=1.1.0",
+    "apscheduler>=3.10.0",
+    "python-dotenv>=1.0.0",
+    "anthropic>=0.40.0",
+    "google-genai>=1.0.0"
+]
+
+[project.scripts]
+skill-capture-cli = "skill_capture.cli:main"
+skill-capture-mcp = "skill_capture.server:main"
+
+[tool.setuptools]
+packages = ["skill_capture", "skill_capture.core"]

skill_capture-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skill_capture-1.0.0/skill_capture/cli.py

@@ -0,0 +1,127 @@
+"""
+CLI — Standalone command-line interface for SkillCapture.
+
+Usage:
+    python cli.py analyze           Run the Day 1/Day 2 pipeline
+    python cli.py list              List all promoted skills
+    python cli.py pending           View pending drafts in the sandbox
+    python cli.py run <skill_name>  Load and display a promoted skill
+"""
+
+import argparse
+import json
+import sys
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from skill_capture.core.storage import load_index, load_skill_from_vault, load_pending
+from skill_capture.core.scheduler import run_pipeline
+
+
+def cmd_analyze(args: argparse.Namespace) -> None:
+    """Run the memory pipeline (Day 1 extraction or Day 2 promotion)."""
+    result = run_pipeline()
+    action = result.get("action", "unknown")
+    details = result.get("details", {})
+
+    if action == "skipped":
+        print(f"⏭  Skipped — {details.get('reason', 'no reason given')}")
+    elif action == "day1_extraction":
+        count = details.get("drafts_cached", 0)
+        print(f"📋 Day 1 — Extracted {count} draft(s) to pending cache.")
+        for s in details.get("summaries", []):
+            print(f"   • {s}")
+    elif action == "day2_promotion":
+        promoted = details.get("skills_promoted", [])
+        remaining = details.get("remaining_pending", 0)
+        print(f"🚀 Day 2 — Promoted {len(promoted)} skill(s), {remaining} draft(s) remain pending.")
+        for name in promoted:
+            print(f"   ✅ {name}")
+    else:
+        print(json.dumps(result, indent=2))
+
+
+def cmd_list(args: argparse.Namespace) -> None:
+    """List all promoted skills from the index."""
+    entries = load_index()
+    if not entries:
+        print("No skills promoted yet. Run 'python cli.py analyze' after logging workflows.")
+        return
+
+    print(f"📚 {len(entries)} skill(s) in the Vault:\n")
+    for e in entries:
+        print(f"   {e.name}")
+        print(f"      {e.trigger_description}")
+        print()
+
+
+def cmd_pending(args: argparse.Namespace) -> None:
+    """View pending drafts in the sandbox."""
+    drafts = load_pending()
+    if not drafts:
+        print("Sandbox is empty — no pending drafts.")
+        return
+
+    print(f"📝 {len(drafts)} pending draft(s):\n")
+    for i, d in enumerate(drafts, 1):
+        print(f"   {i}. {d.action_summary}")
+        print(f"      Keywords: {', '.join(d.keywords)}")
+        print(f"      First seen: {d.first_seen}  |  Occurrences: {d.occurrences}")
+        print()
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    """Load and display a promoted skill."""
+    skill = load_skill_from_vault(args.skill_name)
+    if not skill:
+        available = load_index()
+        names = [e.name for e in available]
+        print(f"❌ Skill '{args.skill_name}' not found.")
+        if names:
+            print(f"   Available: {', '.join(names)}")
+        return
+
+    print(f"🔧 {skill.name}  (v{skill.version})\n")
+    print(f"   {skill.description}\n")
+    if skill.trigger_phrases:
+        print(f"   Triggers: {', '.join(skill.trigger_phrases)}")
+    if skill.variables:
+        print(f"   Variables: {', '.join(skill.variables)}")
+    print()
+    for action in skill.actions:
+        tool = f"  [{action.tool_call}]" if action.tool_call else ""
+        print(f"   {action.step_number}. {action.description}{tool}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="skill-capture",
+        description="SkillCapture — Turn repeated workflows into reusable Skills.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # analyze
+    sub_analyze = subparsers.add_parser("analyze", help="Run the Day 1/Day 2 pipeline")
+    sub_analyze.set_defaults(func=cmd_analyze)
+
+    # list
+    sub_list = subparsers.add_parser("list", help="List all promoted skills")
+    sub_list.set_defaults(func=cmd_list)
+
+    # pending
+    sub_pending = subparsers.add_parser("pending", help="View pending drafts")
+    sub_pending.set_defaults(func=cmd_pending)
+
+    # run
+    sub_run = subparsers.add_parser("run", help="Load and display a promoted skill")
+    sub_run.add_argument("skill_name", help="Name of the skill to load")
+    sub_run.set_defaults(func=cmd_run)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()