diff --git a/.cursorrules b/.cursorrules
index 576ae16f6..033353e71 100644
--- a/.cursorrules
+++ b/.cursorrules
@@ -1,5 +1,12 @@
 Hermes-Agent is an agent harness for LLMs.
 
+## Development Environment
+
+**IMPORTANT**: Always use the virtual environment if it exists:
+```bash
+source venv/bin/activate  # Before running any Python commands
+```
+
 ## Project Structure
 
 - `tools/` - Individual tool implementations (web, terminal, browser, vision, etc.)
@@ -125,4 +132,40 @@ For processing multiple prompts:
 
 ## Logging
 
-Trajectories restructure tools as a system prompt for storage in a format suitable for later training use.
\ No newline at end of file
+Trajectories restructure tools as a system prompt for storage in a format suitable for later training use.
+
+## Skills System
+
+Skills are on-demand knowledge documents the agent can load. Located in `skills/` directory:
+
+```
+skills/
+├── mlops/                    # Category folder
+│   ├── axolotl/             # Skill folder
+│   │   ├── SKILL.md         # Main instructions (required)
+│   │   ├── references/      # Additional docs, API specs
+│   │   └── templates/       # Output formats, configs
+│   └── vllm/
+│       └── SKILL.md
+└── example-skill/
+    └── SKILL.md
+```
+
+**Progressive disclosure** (token-efficient):
+1. `skills_categories()` - List category names (~50 tokens)
+2. `skills_list(category)` - Name + description per skill (~3k tokens)
+3. `skill_view(name)` - Full content + tags + linked files
+
+SKILL.md files use YAML frontmatter:
+```yaml
+---
+name: skill-name
+description: Brief description for listing
+tags: [tag1, tag2]
+related_skills: [other-skill]
+version: 1.0.0
+---
+# Skill Content...
+```
+
+Tool files: `tools/skills_tool.py` → `model_tools.py` → `toolsets.py`
\ No newline at end of file
diff --git a/README.md b/README.md
index 699bd88bf..5ceece4dd 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@ An AI agent with advanced tool-calling capabilities, featuring a flexible toolse
 - **Vision Tools**: Analyze images from URLs
 - **Reasoning Tools**: Advanced multi-model reasoning (Mixture of Agents)
 - **Creative Tools**: Generate images from text prompts
+- **Skills Tools**: On-demand knowledge documents with progressive disclosure
 - **Toolsets System**: Organize tools into logical groups for different scenarios
 - **Batch Processing**: Process datasets in parallel with checkpointing and statistics tracking
 - **Ephemeral System Prompts**: Guide model behavior without polluting training datasets
@@ -179,6 +180,58 @@ python batch_runner.py \
 
 See `.env.example` for all available configuration options including debug settings.
 
+### Skills Tools
+
+Skills are on-demand knowledge documents the agent can load when needed. They follow a **progressive disclosure** pattern to minimize token usage:
+
+```
+skills/
+├── mlops/                    # Category folder
+│   ├── axolotl/             # Skill folder
+│   │   ├── SKILL.md         # Main instructions (required)
+│   │   ├── references/      # Additional docs, API specs
+│   │   └── templates/       # Output formats, configs
+│   └── vllm/
+│       └── SKILL.md
+```
+
+**Available Skills Tools:**
+
+| Tool | Description |
+|------|-------------|
+| `skills_categories` | List available skill categories (~50 tokens) |
+| `skills_list` | List skills with name + description (~3k tokens for 40 skills) |
+| `skill_view` | Load full skill content, tags, and linked files |
+
+**Example Usage:**
+```bash
+# Use skills tools
+python run_agent.py \
+  --query "What skills do you have for fine-tuning? Show me the axolotl skill." \
+  --enabled_toolsets=skills
+```
+
+**Creating Skills:**
+
+Skills use YAML frontmatter for metadata:
+```yaml
+---
+name: my-skill
+description: Brief description shown in skills_list
+tags: [tag1, tag2]
+related_skills: [other-skill]
+version: 1.0.0
+---
+# Skill Content
+
+Instructions, examples, and guidelines here...
+```
+
+Skills can include:
+- `references/` - Additional documentation, API specs, examples
+- `templates/` - Output formats, config files, boilerplate code
+- `scripts/` - Executable helpers (Python, shell scripts)
+
 ## Toolsets System
 
 The agent uses a toolsets system for organizing and managing tools. All tools must be part of a toolset to be accessible - individual tool selection is not supported. This ensures consistent and logical grouping of capabilities.
@@ -410,5 +463,7 @@ All environment variables can be configured in the `.env` file (copy from `.env.
 | `toolset_distributions.py` | Probability distributions for data generation |
 | `trajectory_compressor.py` | Post-process trajectories for training |
 | `tools/` | Individual tool implementations |
+| `tools/skills_tool.py` | Skills system with progressive disclosure |
+| `skills/` | On-demand knowledge documents |
 | `architecture/` | Design documentation |
 | `configs/` | Example batch run scripts |
diff --git a/architecture/tools.md b/architecture/tools.md
index 37a82a370..edad6d6c8 100644
--- a/architecture/tools.md
+++ b/architecture/tools.md
@@ -44,6 +44,7 @@ async def web_search(query: str) -> dict:
 | **Vision** | `vision_tools.py` | `vision_analyze` |
 | **Image Gen** | `image_generation_tool.py` | `image_generate` |
 | **Reasoning** | `mixture_of_agents_tool.py` | `mixture_of_agents` |
+| **Skills** | `skills_tool.py` | `skills_categories`, `skills_list`, `skill_view` |
 
 ## Tool Registration
 
@@ -100,3 +101,33 @@ Some tools maintain state across calls within a session:
 - **Browser**: Maintains browser session for multi-step navigation
 
 State is managed per `task_id` and cleaned up automatically.
+
+## Skills Tools (Progressive Disclosure)
+
+Skills are on-demand knowledge documents. They use **progressive disclosure** to minimize tokens:
+
+```
+Level 0: skills_categories()     → ["mlops", "devops"]           (~50 tokens)
+Level 1: skills_list(category)   → [{name, description}, ...]   (~3k tokens)
+Level 2: skill_view(name)        → Full content + metadata       (varies)
+Level 3: skill_view(name, path)  → Specific reference file       (varies)
+```
+
+Skill directory structure:
+```
+skills/
+└── mlops/
+    └── axolotl/
+        ├── SKILL.md           # Main instructions (required)
+        ├── references/        # Additional docs
+        └── templates/         # Output formats, configs
+```
+
+SKILL.md uses YAML frontmatter:
+```yaml
+---
+name: axolotl
+description: Fine-tuning LLMs with Axolotl
+tags: [Fine-Tuning, LoRA, DPO]
+---
+```