Skills Plugin

Pre-packaged workflows with snapshot/restore permission management

Quick Start

main.py

from connectonion import Agent
from connectonion.useful_tools import FileTools
from connectonion.useful_plugins import skills, tool_approval

file_tools = FileTools()
agent = Agent(
    "assistant",
    tools=[file_tools],
    plugins=[skills, tool_approval]  # skills must come before tool_approval
)

# User types: /commit
# → Skills plugin loads commit skill
# → Takes snapshot of current permissions
# → Grants temporary git permissions
# → Agent executes with auto-approved tools
# → Restores snapshot when turn ends

What Skills Do

Instant Invocation

/command detected in @after_user_input, no LLM overhead

Snapshot/Restore

Preserves user approvals while granting temporary permissions

Security

Permissions auto-clear after turn completes

Unified Permission Structure

Skills use the same 4-field permission structure as all other permission sources:

allowed

True - Tool is permitted

source

"skill" - From skill invocation

reason

"commit skill (turn 5)"

expires

{"type": "turn_end"}

main.py

# Skills grant permissions like this:
session['permissions']['Bash(git status)'] = {
    'allowed': True,
    'source': 'skill',
    'reason': 'commit skill (turn 5)',
    'expires': {'type': 'turn_end'}
}

Snapshot/Restore Flow

Skills preserve user approvals using a snapshot → grant → restore pattern:

📸 Snapshot

Before granting skill permissions, save current state:

snapshot = deepcopy(session['permissions'])

➕ Grant

Add skill permissions to existing permissions:

session['permissions']['Bash(git *)'] = {...}

⚡ Execute

Agent runs with both user and skill permissions active

🔄 Restore

When turn ends, restore the snapshot:

session['permissions'] = snapshot

Result: User Approvals Never Lost

✅ User's session approvals preserved across skill invocations
✅ Skill permissions cleanly added and removed
✅ No permission contamination between turns
✅ Predictable, testable permission lifecycle

Example Skill

code

---
name: commit
description: Create git commits with good messages
tools:
  - Bash(git status)
  - Bash(git diff *)
  - Bash(git commit *)
  - Bash(git add *)
  - read_file
  - glob
---

Create a well-formatted git commit for staged changes.

1. Check status: `git status`
2. Review changes: `git diff --staged`
3. Create commit with descriptive message

User types: /commit → git commands auto-approved → commit created → permissions restored

Permission Patterns

Skills support flexible pattern matching for tool permissions:

Exact Match

Bash(git status)

Only matches "git status"

Wildcard Args

Bash(git diff *)

Any git diff command

Command Prefix

Bash(git *)

All git commands

Tool Name

read_file

Any read_file call

code

tools:
  - Bash(git status)         # Exact: only "git status"
  - Bash(git diff *)         # Wildcard: any git diff command
  - Bash(git *)              # Prefix: all git commands
  - read_file                # Tool name (any arguments)
  - glob                     # Tool name
  - grep                     # Tool name

Security Model - One Turn Only

Turn-Based Expiration

Turn 3: User approves bash:pytest for session

permissions['bash:pytest'] = {source: 'user', expires: 'session_end'}

Turn 5: /commit skill invoked

→ Snapshot taken (bash:pytest saved)

→ Grant: permissions['Bash(git *)'] = {source: 'skill', expires: 'turn_end'}

During turn 5:

→ git status ✓ (skill permission)

→ bash:pytest ✓ (user permission)

Turn 5 ends (@on_complete):

→ Restore snapshot

→ git permissions cleared ✓

→ bash:pytest preserved ✓

Turn 6: Normal operation

→ git commands require approval ✗

→ bash:pytest still works ✓

Creating Skills

Project-Level (.co/skills/)

code

mkdir -p .co/skills/deploy
cat > .co/skills/deploy/SKILL.md <<'EOF'
---
name: deploy
description: Deploy to PyPI
tools:
  - Bash(pytest *)
  - Bash(python -m build)
  - Bash(python -m twine *)
---

Deploy package to PyPI after running tests.

1. Run tests to ensure quality
2. Build the package
3. Upload to PyPI
EOF

User-Level (~/.co/skills/)

code

mkdir -p ~/.co/skills/review
cat > ~/.co/skills/review/SKILL.md <<'EOF'
---
name: review
description: Code review workflow
tools:
  - Bash(git diff *)
  - Bash(git log *)
  - read_file
  - glob
  - grep
---

Review recent code changes and provide feedback.

1. Check recent commits
2. Review diffs
3. Identify issues and suggestions
EOF

Permissions

Complete permission system overview

Skills Concepts

Detailed skills documentation

prefer_write_tool

tool_approval

Skills Plugin

Quick Start

What Skills Do

Instant Invocation

Snapshot/Restore

Security

Unified Permission Structure

Snapshot/Restore Flow

📸 Snapshot

➕ Grant

⚡ Execute

🔄 Restore

Result: User Approvals Never Lost

Example Skill

Permission Patterns

Exact Match

Wildcard Args

Command Prefix

Tool Name

Security Model - One Turn Only

Turn-Based Expiration

Creating Skills

Project-Level (.co/skills/)

User-Level (~/.co/skills/)

Related

Permissions

Skills Concepts

Enjoying ConnectOnion?