Feature Request: Add Skill Priority Configuration

📋 Summary

Add support for skill priority configuration to enable intelligent skill selection when multiple skills can perform the same task.

🐛 Problem Statement

OpenClaw currently has overlapping skills without clear selection rules, leading to inconsistent behavior:

Impact:

• ❌ Inconsistent behavior - same task may use different skills randomly
• ❌ Suboptimal choices - may use paid tools when free alternatives exist
• ❌ Poor localization - may use English humanizer for Chinese text
• ❌ Performance issues - may use heavy tools for simple tasks

✅ Proposed Solution

1. Configuration File

Add ~/.openclaw/skills-config/priority.json:

{
  "multi-search-engine": {"priority": 1, "description": "优先使用：无需 API key，多引擎并行，适合中文环境"},
  "humanize-zh": {"priority": 1, "description": "优先使用：中文场景的首选 humanize 技能"},
  "humanize-ai-text": {"priority": 2, "description": "备用：英文场景使用，中文优先用 humanize-zh"},
  "agent-browser": {"priority": 2, "description": "简单任务优先：轻量级，Rust 原生，适合快速导航/提取"},
  "playwright": {"priority": 1, "description": "复杂任务优先：完整浏览器控制，支持截图/PDF/下载"},
  "openclaw-tavily-search": {"priority": 2, "description": "备用：Brave 不可用时使用"}
}

Priority Rules:

• priority: 1 - Preferred (use when available)
• priority: 2 - Fallback (use only when priority 1 is unavailable)
• Default: Skills without priority config get priority 99 (lowest)

2. Implementation Changes

A. Skill Discovery Sorting

When searching for skills, sort results by priority:

function sortSkillsByPriority(skills: Skill[], priorityConfig: PriorityConfig): Skill[] {
  return skills.sort((a, b) => {
    const pa = getPriority(a.name, priorityConfig);
    const pb = getPriority(b.name, priorityConfig);
    return pa - pb; // Lower number = higher priority
  });
}

function getPriority(skillName: string, config: PriorityConfig): number {
  return (config[skillName]?.priority ?? 99); // Default: lowest priority
}

B. Skill Selection Logic

When multiple eligible skills are found for a task, select the highest-priority one:

function selectSkill(task: Task, eligibleSkills: Skill[], priorityConfig: PriorityConfig): Skill | null {
  if (eligibleSkills.length <= 1) {
    return eligibleSkills[0] ?? null;
  }
  
  // Sort by priority (lower number = higher priority)
  eligibleSkills.sort((a, b) => {
    const pa = getPriority(a.name, priorityConfig);
    const pb = getPriority(b.name, priorityConfig);
    return pa - pb;
  });
  
  return eligibleSkills[0]; // Highest priority (lowest number)
}

C. CLI Commands

Add new subcommand for managing priorities:

# View current priorities
openclaw skills priority list

# Set priority for a skill
openclaw skills priority set <skill-name> --level 1|2

# Reset to default
openclaw skills priority reset

3. File Structure

~/.openclaw/
├── skills-config/          # NEW: User-managed configuration
│   └── priority.json       # Skill priority settings (NOT in skills/)
└── workspace/
    └── skills/             # Installed skills (managed by clawdhub)

Important: The config file is OUTSIDE the skills directory to avoid being overwritten by clawdhub update.

🎯 Benefits

1. ✅ Consistent Behavior - Users get predictable skill selection based on their preferences
2. ✅ Performance Optimization - Can prioritize lighter tools for simple tasks
3. ✅ Cost Control - Can prioritize free tools over paid APIs when possible
4. ✅ Localization - Can prioritize language-appropriate skills (e.g., humanize-zh for Chinese)
5. ✅ User Control - Easy to customize priorities via CLI

💡 Example Use Cases

Use Case 1: Prefer Free Search Engine

openclaw skills priority set multi-search-engine --level 1
openclaw skills priority set openclaw-tavily-search --level 2

Result: Searching will prefer multi-search-engine (free, no API key) over tavily-search (paid, requires API key).

Use Case 2: Language-Aware Humanization

openclaw skills priority set humanize-zh --level 1
openclaw skills priority set humanize-ai-text --level 2

Result: Chinese text will automatically use humanize-zh, English text will use humanize-ai-text.

Use Case 3: Performance Optimization

openclaw skills priority set agent-browser --level 1
openclaw skills priority set playwright --level 2

Result: Simple tasks will use lightweight Rust browser, complex tasks will use full Playwright.

🔄 Backward Compatibility

• ✅ Skills without priority config default to priority 99 (lowest)
• ✅ Existing behavior preserved for skills without explicit priority
• ✅ Config file is optional, not required for basic functionality
• ✅ No breaking changes to existing commands

📝 Migration Path

Phase 1: Configuration Support (v2026.x.x)

• Add priority.json parsing
• Implement priority-based sorting in skill discovery
• Update skill selection to prefer higher priority
• Add CLI commands for managing priorities

Phase 2: Skill Metadata (v2026.y.y - Optional)

• Allow skills to declare their own priority in _meta.json

Phase 3: CLI Management (v2026.z.z - Optional)

• Add openclaw skills priority subcommands
• Add documentation in docs/skills/priority.md

🧪 Testing

# Set priority for a skill
openclaw skills priority set multi-search-engine --level 1

# Verify priorities
openclaw skills priority list

# Test skill selection - should use multi-search-engine
echo "search something" | openclaw --model test

# Verify config is not overwritten by update
clawdhub update --all
cat ~/.openclaw/skills-config/priority.json  # Should remain unchanged

🏷️ Labels

• enhancement
• skills
• priority
• feature-request

📚 Related Documentation

• Skill Discovery
• Skill Vetting
• CLI Reference

Author: Jimmy (OpenClaw User)
Date: 2026-03-19
Priority: Medium (nice-to-have, not critical but would improve user experience)