mpfaffenberger · arnonuem · Jan 12, 2026
diff --git a/README.md b/README.md
@@ -5,18 +5,20 @@
 **🐶✨The sassy AI code agent that makes IDEs look outdated** ✨🐶
 
 [![Version](https://img.shields.io/pypi/v/code-puppy?style=for-the-badge&logo=python&label=Version&color=purple)](https://pypi.org/project/code-puppy/)
-[![Downloads](https://img.shields.io/badge/Downloads-170k%2B-brightgreen?style=for-the-badge&logo=download)](https://pypi.org/project/code-puppy/)
+[![Downloads](https://img.shields.io/badge/Downloads-100k%2B-brightgreen?style=for-the-badge&logo=download)](https://pypi.org/project/code-puppy/)
 [![Python](https://img.shields.io/badge/Python-3.11%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
 [![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
 [![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen?style=for-the-badge&logo=github)](https://github.com/mpfaffenberger/code_puppy/actions)
+[![Coverage](https://img.shields.io/badge/Coverage-95%25-brightgreen?style=for-the-badge)](https://github.com/mpfaffenberger/code_puppy)
+[![Code Style](https://img.shields.io/badge/Code%20Style-Black-black?style=for-the-badge)](https://github.com/psf/black)
 [![Tests](https://img.shields.io/badge/Tests-Passing-success?style=for-the-badge&logo=pytest)](https://github.com/mpfaffenberger/code_puppy/tests)
 
-[![OpenAI](https://img.shields.io/badge/OpenAI-GPT--5.2--Codex-orange?style=flat-square&logo=openai)](https://openai.com)
+[![OpenAI](https://img.shields.io/badge/OpenAI-GPT--5-orange?style=flat-square&logo=openai)](https://openai.com)
 [![Gemini](https://img.shields.io/badge/Google-Gemini-blue?style=flat-square&logo=google)](https://ai.google.dev/)
 [![Anthropic](https://img.shields.io/badge/Anthropic-Claude-orange?style=flat-square&logo=anthropic)](https://anthropic.com)
-[![Cerebras](https://img.shields.io/badge/Cerebras-GLM%204.7-red?style=flat-square)](https://cerebras.ai)
-[![Z.AI](https://img.shields.io/badge/Z.AI-GLM%204.7-purple?style=flat-square)](https://z.ai/)
-[![Synthetic](https://img.shields.io/badge/Synthetic-MINIMAX_M2.1-green?style=flat-square)](https://synthetic.new)
+[![Cerebras](https://img.shields.io/badge/Cerebras-GLM%204.6-red?style=flat-square)](https://cerebras.ai)
+[![Z.AI](https://img.shields.io/badge/Z.AI-GLM%204.6-purple?style=flat-square)](https://z.ai/)
+[![Synthetic](https://img.shields.io/badge/Synthetic-MINIMAX_M2-green?style=flat-square)](https://synthetic.new)
 
 [![100% Open Source](https://img.shields.io/badge/100%25-Open%20Source-blue?style=for-the-badge)](https://github.com/mpfaffenberger/code_puppy)
 [![Pydantic AI](https://img.shields.io/badge/Pydantic-AI-success?style=for-the-badge)](https://github.com/pydantic/pydantic-ai)
@@ -26,9 +28,6 @@
 [![GitHub stars](https://img.shields.io/github/stars/mpfaffenberger/code_puppy?style=for-the-badge&logo=github)](https://github.com/mpfaffenberger/code_puppy/stargazers)
 [![GitHub forks](https://img.shields.io/github/forks/mpfaffenberger/code_puppy?style=for-the-badge&logo=github)](https://github.com/mpfaffenberger/code_puppy/network)
 
-[![Discord](https://img.shields.io/badge/Discord-Community-purple?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/SqYAaXVy)
-[![Docs](https://img.shields.io/badge/Read-The%20Docs-blue?style=for-the-badge&logo=readthedocs)](https://code-puppy.dev)
-
 **[⭐ Star this repo if you hate expensive IDEs! ⭐](#quick-start)**
 
 *"Who needs an IDE when you have 1024 angry puppies?"* - Someone, probably.
@@ -62,32 +61,66 @@ uvx code-puppy -i
 
 ### UV (Recommended)
 
-#### macOS / Linux
-
 ```bash
 # Install UV if you don't have it
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
-uvx code-puppy
+# Set UV to always use managed Python (one-time setup)
+echo 'export UV_MANAGED_PYTHON=1' >> ~/.zshrc  # or ~/.bashrc
+source ~/.zshrc  # or ~/.bashrc
+
+# Install and run code-puppy
+uvx code-puppy -i
+```
+
+UV will automatically download the latest compatible Python version (3.11+) if your system doesn't have one.
+
+### pip (Alternative)
+
+```bash
+pip install code-puppy
 ```
 
-#### Windows
+*Note: pip installation requires your system Python to be 3.11 or newer.*
+
+### Permanent Python Management
 
-On Windows, we recommend installing code-puppy as a global tool for the best experience with keyboard shortcuts (Ctrl+C/Ctrl+X cancellation):
+To make UV always use managed Python versions (recommended):
 
-```powershell
-# Install UV if you don't have it (run in PowerShell as Admin)
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```bash
+# Set environment variable permanently
+echo 'export UV_MANAGED_PYTHON=1' >> ~/.zshrc  # or ~/.bashrc
+source ~/.zshrc  # or ~/.bashrc
 
-uvx code-puppy
+# Now all UV commands will prefer managed Python installations
+uvx code-puppy  # No need for --managed-python flag anymore
 ```
 
-## Changelog (By Kittylog!)
+### Verifying Python Version
+
+```bash
+# Check which Python UV will use
+uv python find
 
-[📋 View the full changelog on Kittylog](https://kittylog.app/c/mpfaffenberger/code_puppy)
+# Or check the current project's Python
+uv run python --version
+```
 
 ## Usage
 
+### Custom Commands
+Create markdown files in `.claude/commands/`, `.github/prompts/`, or `.agents/commands/` to define custom slash commands. The filename becomes the command name and the content runs as a prompt.
+
+```bash
+# Create a custom command
+echo "# Code Review
+
+Please review this code for security issues." > .claude/commands/review.md
+
+# Use it in Code Puppy
+/review with focus on authentication
+```
+
 ### Adding Models from models.dev 🆕
 
 While there are several models configured right out of the box from providers like Synthetic, Cerebras, OpenAI, Google, and Anthropic, Code Puppy integrates with [models.dev](https://models.dev) to let you browse and add models from **65+ providers** with a single command:
@@ -155,18 +188,6 @@ The following environment variables control DBOS behavior:
 - `DBOS_SYSTEM_DATABASE_URL`: Database URL used by DBOS. Can point to a local SQLite file or a Postgres instance. Example: `postgresql://postgres:dbos@localhost:5432/postgres`. Default: `dbos_store.sqlite` file in the config directory.
 - `DBOS_APP_VERSION`: If set, Code Puppy uses it as the [DBOS application version](https://docs.dbos.dev/architecture#application-and-workflow-versions) and automatically tries to recover pending workflows for this version. Default: Code Puppy version + Unix timestamp in millisecond (disable automatic recovery).
 
-### Custom Commands
-Create markdown files in `.claude/commands/`, `.github/prompts/`, or `.agents/commands/` to define custom slash commands. The filename becomes the command name and the content runs as a prompt.
-
-```bash
-# Create a custom command
-echo "# Code Review
-
-Please review this code for security issues." > .claude/commands/review.md
-
-# Use it in Code Puppy
-/review with focus on authentication
-```
 
 ## Requirements
 
@@ -186,6 +207,58 @@ For examples and more information about agent rules, visit [https://agent.md](ht
 
 Use the `/mcp` command to manage MCP (list, start, stop, status, etc.)
 
+Watch this video for examples! https://www.youtube.com/watch?v=1t1zEetOqlo
+
+
+## Skills Plugin 📚
+
+Code Puppy supports **Claude Code-compatible skills** - modular knowledge packages that extend the LLM with specialized expertise.
+
+### Quick Start
+
+```bash
+/skill list              # List installed skills
+/skill add ~/my-skill    # Install a skill
+/skill info <name>       # View skill details
+/skill show <name>       # Show full documentation
+/skill remove <name>     # Uninstall skill
+/skill refresh           # Rescan skills directory
+```
+
+### Skills Directory
+
+```
+~/.code_puppy/skills/
+├── pdf/
+│   └── SKILL.md
+└── docx/
+    └── SKILL.md
+```
+
+### SKILL.md Format
+
+```yaml
+---
+name: my-skill              # kebab-case, required
+description: "What it does" # required
+license: "MIT"              # optional
+---
+
+# Skill Documentation
+
+Full instructions go here...
+```
+
+### How It Works
+
+1. **Startup** → Plugin scans `~/.code_puppy/skills/` for valid skills
+2. **Prompts** → Skill catalog is injected into system prompts
+3. **Usage** → LLM sees available skills and can request full docs
+
+See [Skills Plugin README](code_puppy/plugins/skills/README.md) for full documentation.
+
+---
+
 ## Round Robin Model Distribution
 
 Code Puppy supports **Round Robin model distribution** to help you overcome rate limits and distribute load across multiple AI models. This feature automatically cycles through configured models with each request, maximizing your API usage while staying within rate limits.

diff --git a/code_puppy/agents/agent_code_puppy.py b/code_puppy/agents/agent_code_puppy.py
@@ -150,7 +150,7 @@ def get_system_prompt(self) -> str:
 Return your final response as a string output
 """
 
-        prompt_additions = callbacks.on_load_prompt()
-        if len(prompt_additions):
+        prompt_additions = [p for p in callbacks.on_load_prompt() if p]
+        if prompt_additions:
             result += "\n".join(prompt_additions)
         return result
diff --git a/code_puppy/agents/agent_planning.py b/code_puppy/agents/agent_planning.py
@@ -30,7 +30,6 @@ def get_available_tools(self) -> list[str]:
             "list_files",
             "read_file",
             "grep",
-            "agent_run_shell_command",
             "agent_share_your_reasoning",
             "list_agents",
             "invoke_agent",
@@ -158,7 +157,7 @@ def get_system_prompt(self) -> str:
 IMPORTANT: Only when the user gives clear approval to proceed (such as "execute plan", "go ahead", "let's do it", "start", "begin", "proceed", "sounds good", or any equivalent phrase indicating they want to move forward), coordinate with the appropriate agents to implement your roadmap step by step, otherwise don't start invoking other tools such read file or other agents.
 """
 
-        prompt_additions = callbacks.on_load_prompt()
-        if len(prompt_additions):
+        prompt_additions = [p for p in callbacks.on_load_prompt() if p]
+        if prompt_additions:
             result += "\n".join(prompt_additions)
         return result
diff --git a/code_puppy/agents/prompt_reviewer.py b/code_puppy/agents/prompt_reviewer.py
@@ -139,7 +139,7 @@ def get_system_prompt(self) -> str:
 Remember: Great prompts lead to great results, but perfect is the enemy of good enough.
 """
 
-        prompt_additions = callbacks.on_load_prompt()
-        if len(prompt_additions):
+        prompt_additions = [p for p in callbacks.on_load_prompt() if p]
+        if prompt_additions:
             result += "\n" + "\n".join(prompt_additions)
         return result
diff --git a/code_puppy/plugins/skills/README.md b/code_puppy/plugins/skills/README.md
@@ -0,0 +1,102 @@
+# Skills Plugin 📚
+
+Claude Code-compatible skill support for Code Puppy.
+
+## What Are Skills?
+
+Skills are modular knowledge packages (`SKILL.md` files) that extend the LLM's capabilities with specialized expertise, workflows, and resources.
+
+## Quick Start
+
+```bash
+# List installed skills
+/skill list
+
+# Install a skill
+/skill add ~/my-skills/pdf
+
+# View skill details
+/skill info pdf
+
+# Show full documentation
+/skill show pdf
+
+# Remove a skill
+/skill remove pdf
+
+# Rescan skills directory
+/skill refresh
+```
+
+## Skills Directory
+
+```
+~/.code_puppy/skills/
+├── pdf/
+│   ├── SKILL.md          # Required: skill definition
+│   ├── scripts/          # Optional: helper scripts
+│   └── references/       # Optional: reference docs
+└── docx/
+    └── SKILL.md
+```
+
+## SKILL.md Format
+
+```yaml
+---
+name: my-skill              # kebab-case, required
+description: "What it does" # required
+license: "MIT"              # optional
+---
+
+# Skill Title
+
+Full documentation goes here...
+```
+
+**Rules:**
+- Must start with `---` (YAML frontmatter)
+- `name` and `description` are required
+- Body content follows the second `---`
+
+## How It Works
+
+1. **Startup** → Plugin scans `~/.code_puppy/skills/` for valid skills
+2. **Prompts** → Skill catalog is injected into system prompts
+3. **Usage** → LLM sees available skills and can request full docs
+
+## Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `/skill` | Show help |
+| `/skill list` | List installed skills |
+| `/skill info <name>` | Show metadata |
+| `/skill show <name>` | Show full SKILL.md |
+| `/skill add <path>` | Install from directory |
+| `/skill remove <name>` | Uninstall skill |
+| `/skill refresh` | Rescan directory |
+
+## Creating a Skill
+
+```bash
+mkdir -p ~/.code_puppy/skills/my-skill
+cat > ~/.code_puppy/skills/my-skill/SKILL.md << 'EOF'
+---
+name: my-skill
+description: "My awesome skill for doing X"
+---
+
+# My Skill
+
+## When to Use
+Use this skill when the user asks about X...
+
+## Workflow
+1. Step one
+2. Step two
+3. Done!
+EOF
+```
+
+Then run `/skill refresh` to load it.
diff --git a/code_puppy/plugins/skills/__init__.py b/code_puppy/plugins/skills/__init__.py
@@ -0,0 +1,7 @@
+"""Skills Plugin for Code Puppy - Claude Code compatible skill support."""
+
+from code_puppy.plugins.skills.skill_loader import SkillLoader, SkillLoaderError
+from code_puppy.plugins.skills.skill_manager import SkillManager
+from code_puppy.plugins.skills.skill_types import SkillMetadata
+
+__all__ = ["SkillMetadata", "SkillLoader", "SkillLoaderError", "SkillManager"]