ollama/docs/skills.md

Ollama Skills

Skills are reusable capability packages that extend what agents can do. They bundle instructions, scripts, and data that teach an agent how to perform specific tasks.

Quick Start

Creating a Skill

Create a directory with a SKILL.md file:

my-skill/
├── SKILL.md          # Required: Instructions for the agent
└── scripts/          # Optional: Executable scripts
    └── run.py

The SKILL.md file must have YAML frontmatter:

---
name: my-skill
description: A brief description of what this skill does
---

# My Skill

## Purpose
Explain what this skill does and when to use it.

## Instructions
Step-by-step instructions for the agent on how to use this skill.

## Examples
Show example inputs and expected outputs.

Using Skills in an Agent

Reference skills in your Agentfile:

FROM llama3.2:3b
AGENT_TYPE conversational

# Local skill (bundled with agent)
SKILL ./path/to/my-skill

# Registry skill (pulled from ollama.com)
SKILL library/skill/calculator:1.0.0

# User skill from registry
SKILL myname/skill/calculator:1.0.0

SYSTEM You are a helpful assistant.

Managing Skills

# Push a skill to the registry (uses your namespace)
ollama skill push myname/skill/calculator:1.0.0 ./my-skill

# Pull a skill from the official library
ollama skill pull skill/calculator:1.0.0

# Pull a skill from a user's namespace
ollama skill pull myname/skill/calculator:1.0.0

# List installed skills
ollama skill list

# Show skill details
ollama skill show skill/calculator:1.0.0

# Remove a skill
ollama skill rm skill/calculator:1.0.0

Dynamic Skills in Chat

You can add and remove skills dynamically during an interactive chat session:

>>> /skills
Available Skills:
  calculator (sha256:abc123def456...)

>>> /skill add ./my-local-skill
Added skill 'my-skill' from ./my-local-skill

>>> /skill list
Skills loaded in this session:
  my-skill (local: /path/to/my-local-skill)

>>> /skill remove my-skill
Removed skill 'my-skill'

Command	Description
/skills	Show all available skills (model + session)
/skill add <path>	Add a skill from a local path
/skill remove <name>	Remove a skill by name
/skill list	List skills loaded in this session

Dynamic skills take effect on the next message. This is useful for:

• Testing skills during development
• Temporarily adding capabilities to a model
• Experimenting with skill combinations

Skill Reference Formats

Skills use a 5-part name structure: host/namespace/kind/model:tag

Format	Example	Description
Local path	./skills/calc	Bundled with agent at create time
Library skill	skill/calculator:1.0.0	From the official skill library (library/skill/calculator)
User skill	alice/skill/calc:1.0.0	From a user's namespace
Full path	registry.ollama.ai/alice/skill/calc:1.0.0	Fully qualified with host

The kind field distinguishes skills from models:

• skill - Skill packages
• agent - Agent packages (future)
• (empty) - Regular models

SKILL.md Structure

Required Frontmatter

---
name: skill-name        # Must match directory name
description: Brief description of the skill
---

Recommended Sections

1. Purpose: What the skill does and when to use it
2. When to use: Trigger conditions for the agent
3. Instructions: Step-by-step usage guide
4. Examples: Input/output examples
5. Scripts: Documentation for any bundled scripts

Example: Calculator Skill

---
name: calculator
description: Performs mathematical calculations using Python
---

# Calculator Skill

## Purpose
This skill performs mathematical calculations using a bundled Python script.

## When to use
- User asks to calculate something
- User wants to do math operations
- Any arithmetic is needed

## Instructions
1. When calculation is needed, use the `run_skill_script` tool
2. Call: `python3 scripts/calculate.py "<expression>"`
3. Return the result to the user

## Examples

**Input**: "What is 25 * 4?"
**Action**: `run_skill_script` with command `python3 scripts/calculate.py '25 * 4'`
**Output**: "25 * 4 = 100"

Storage Layout

~/.ollama/models/
├── blobs/
│   └── sha256-<digest>           # Skill tar.gz blob
├── manifests/
│   └── registry.ollama.ai/
│       └── skill/                # Library skills
│           └── calculator/
│               └── 1.0.0
│       └── skill-username/       # User skills
│           └── my-skill/
│               └── latest
└── skills/
    └── sha256-<digest>/          # Extracted skill cache
        ├── SKILL.md
        └── scripts/

---

Security Considerations

Current State (Development)

The current implementation has several security considerations that need to be addressed before production use.

1. Script Execution

Risk: Skills can bundle arbitrary scripts that execute on the host system.

Current behavior:

• Scripts run with the same permissions as the Ollama process
• No sandboxing or isolation
• Full filesystem access

Mitigations needed:

• Sandbox script execution (containers, seccomp, etc.)
• Resource limits (CPU, memory, time)
• Filesystem isolation (read-only mounts, restricted paths)
• Network policy controls
• Capability dropping

2. Skill Provenance

Risk: Malicious skills could be pushed to the registry.

Current behavior:

• No code signing or verification
• No malware scanning
• Trust based on namespace ownership

Mitigations needed:

• Skill signing with author keys
• Registry-side malware scanning
• Content policy enforcement
• Reputation system for skill authors

3. Namespace Squatting

Risk: Malicious actors could register skill names that impersonate official tools.

Current behavior:

• First-come-first-served namespace registration
• No verification of skill names

Mitigations needed:

• Reserved namespace list (official tools, common names)
• Trademark/name verification for popular skills
• Clear namespacing conventions

4. Supply Chain Attacks

Risk: Compromised skills could inject malicious code into agents.

Current behavior:

• Skills pulled without integrity verification beyond digest
• No dependency tracking

Mitigations needed:

• SBOM (Software Bill of Materials) for skills
• Dependency vulnerability scanning
• Pinned versions in Agentfiles
• Audit logging of skill usage

5. Data Exfiltration

Risk: Skills could exfiltrate sensitive data from conversations or the host.

Current behavior:

• Skills have access to conversation context
• Scripts can make network requests

Mitigations needed:

• Network egress controls
• Sensitive data detection/masking
• Audit logging of script network activity
• User consent for data access

6. Privilege Escalation

Risk: Skills could escalate privileges through script execution.

Current behavior:

• Scripts inherit Ollama process privileges
• No capability restrictions

Mitigations needed:

• Run scripts as unprivileged user
• Drop all capabilities
• Mandatory access controls (SELinux/AppArmor)

Recommended Security Model

Skill Trust Levels

┌─────────────────────────────────────────────────────────────┐
│ Level 0: Untrusted (default)                                │
│ - No script execution                                       │
│ - Instructions only                                         │
│ - Safe for any skill                                        │
├─────────────────────────────────────────────────────────────┤
│ Level 1: Sandboxed                                          │
│ - Scripts run in isolated container                         │
│ - No network access                                         │
│ - Read-only filesystem                                      │
│ - Resource limits enforced                                  │
├─────────────────────────────────────────────────────────────┤
│ Level 2: Trusted                                            │
│ - Scripts run with network access                           │
│ - Can write to designated directories                       │
│ - Requires explicit user approval                           │
├─────────────────────────────────────────────────────────────┤
│ Level 3: Privileged (admin only)                            │
│ - Full host access                                          │
│ - System administration skills                              │
│ - Requires admin approval                                   │
└─────────────────────────────────────────────────────────────┘

Skill Manifest Security Fields (Future)

---
name: my-skill
description: A skill description
security:
  trust_level: sandboxed
  permissions:
    - network:read          # Can make HTTP GET requests
    - filesystem:read:/data # Can read from /data
  resource_limits:
    max_memory: 256MB
    max_cpu_time: 30s
    max_disk: 100MB
  signature: sha256:abc...  # Author signature
---

---

Future Considerations

Feature Roadmap

Phase 1: Foundation (Current)

• Skill bundling with agents
• Local skill development
• Basic CLI commands (push, pull, list, rm, show)
• Registry blob storage
• Registry namespace configuration

Phase 2: Security

• Script sandboxing
• Permission model
• Skill signing
• Audit logging

Phase 3: Discovery

• Skill search on ollama.com
• Skill ratings and reviews
• Usage analytics
• Featured/trending skills

Phase 4: Advanced Features

• Skill dependencies
• Skill versioning constraints
• Skill composition (skills using skills)
• Skill testing framework

Open Questions

1. Skill Execution Model

Question: How should skills execute scripts?

Options:

• A) In-process: Fast but unsafe
• B) Subprocess: Current approach, moderate isolation
• C) Container: Good isolation, requires container runtime
• D) WASM: Portable and safe, limited capabilities
• E) Remote execution: Offload to secure service

2. Skill Versioning

Question: How strict should version pinning be?

Options:

• A) Always latest: Simple but risky
• B) Semantic versioning: ^1.0.0 allows minor updates
• C) Exact pinning: =1.0.0 requires explicit updates
• D) Digest pinning: @sha256:abc immutable reference

3. Skill Permissions

Question: How should users grant permissions to skills?

Options:

• A) All or nothing: Accept all permissions or don't use
• B) Granular consent: Approve each permission individually
• C) Trust levels: Pre-defined permission bundles
• D) Runtime prompts: Ask when permission is first used

4. Skill Discovery

Question: How should users find skills?

Options:

• A) Central registry only: ollama.com/skills
• B) Federated registries: Multiple skill sources
• C) Git repositories: Pull from GitHub, etc.
• D) All of the above: Multiple discovery mechanisms

5. Skill Monetization

Question: Should skill authors be able to monetize?

Options:

• A) Free only: All skills are free and open
• B) Paid skills: Authors can charge for skills
• C) Freemium: Free tier with paid features
• D) Donations: Voluntary support for authors

6. Skill Updates

Question: How should skill updates be handled?

Options:

• A) Manual: User explicitly updates
• B) Auto-update: Always use latest
• C) Notify: Alert user to available updates
• D) Policy-based: Organization controls update policy

API Considerations

Skill Metadata API

GET /api/skills
GET /api/skills/:namespace/:name
GET /api/skills/:namespace/:name/versions
GET /api/skills/:namespace/:name/readme

Skill Execution API

POST /api/skills/:namespace/:name/execute
{
  "command": "python3 scripts/run.py",
  "args": ["--input", "data"],
  "timeout": 30
}

Skill Permissions API

GET /api/skills/:namespace/:name/permissions
POST /api/skills/:namespace/:name/permissions/grant
DELETE /api/skills/:namespace/:name/permissions/revoke

Testing Considerations

Skill Testing Framework

# Run skill tests
ollama skill test ./my-skill

# Test with specific model
ollama skill test ./my-skill --model llama3.2:3b

# Generate test report
ollama skill test ./my-skill --report

Test File Format

# my-skill/tests/test.yaml
tests:
  - name: "basic calculation"
    input: "What is 2 + 2?"
    expect:
      contains: "4"
      tool_called: "run_skill_script"

  - name: "complex expression"
    input: "Calculate 15% of 200"
    expect:
      contains: "30"

Compatibility Considerations

Minimum Ollama Version

Skills should declare minimum Ollama version:

---
name: my-skill
requires:
  ollama: ">=0.4.0"
---

Model Compatibility

Skills may require specific model capabilities:

---
name: vision-skill
requires:
  capabilities:
    - vision
    - tools
---

Migration Path

From Local to Registry

# Develop locally
SKILL ./my-skill

# Push when ready
ollama skill push myname/my-skill:1.0.0 ./my-skill

# Update Agentfile
SKILL skill/myname/my-skill:1.0.0

Version Upgrades

# Check for updates
ollama skill outdated

# Update specific skill
ollama skill update calculator:1.0.0

# Update all skills
ollama skill update --all