skills: native agent runtime is much weaker than OpenClaw-style skill execution

[Atlas-SZ]

Pre-checks

• I have searched existing issues and this is not a duplicate.

What problem does this solve?

Clawith currently supports the OpenClaw/AgentSkills-style skill package format (SKILL.md plus auxiliary files) at the packaging level, but its native-agent runtime
behavior is noticeably weaker.

The problem is not Clawith's dual-layer design (company-level shared skills + agent-level private skills). That architecture makes sense for enterprise isolation and
agent growth.

The real issue is that native agents rely too heavily on the model to discover and interpret skills on its own, which leads to:

• unstable skill triggering
• agents often not reading SKILL.md proactively
• generic responses instead of skill-driven execution
• underuse of auxiliary files such as scripts/ and references/
• a noticeably weaker experience than an OpenClaw-style skill runtime

In other words, Clawith skills currently behave more like prompt attachments than reliably activated capability modules.

---

Clawith 当前的 skills 体系在“包格式”层面基本支持 OpenClaw/AgentSkills 风格的 SKILL.md + 辅助文件，但在 native agent 的实际运行效果上明显偏弱。

问题不在于 Clawith 的双层设计（公司级共享 skills + agent 私有 skills），这套设计本身符合企业级隔离和数字员工成长的产品定位。

真正的问题是 native agent 对 skills 的使用过于依赖模型自行发现和理解，导致：

• skill 触发不稳定
• agent 经常不主动读取 SKILL.md
• 回复容易退化成泛化回答，而不是按 skill 执行
• scripts/、references/ 等辅助文件利用不足
• 整体效果明显弱于 OpenClaw 风格的 skill runtime

换句话说，当前 Clawith skills 更像“提示词附件”，而不是“可稳定触发的能力模块”。

Proposed solution

Strengthen the native skill runtime for Clawith agents instead of exposing skills mainly as passive prompt content.

Proposed direction:

1. Improve native-agent skill activation so matched skills are loaded and used more explicitly and reliably.
2. Support a useful subset of high-value OpenClaw/AgentSkills-style frontmatter/runtime semantics for native agents, especially fields related to triggering, eligibility,
   and invocation policy.
3. Rewrite builtin skills to be more operational, including:
   • clearer trigger phrases
   • more concrete tool-execution steps
   • more explicit fallback behavior
   • better use of auxiliary files such as scripts/ and references/
4. Preserve the existing enterprise architecture:
   • company-level shared skill registry
   • agent-level private skills
   • tenant isolation and builtin protection

The goal is not to make Clawith fully copy OpenClaw, but to make native skills behave more like a stable capability runtime and less like prompt attachments that are easy
for the model to ignore.

---

增强 Clawith native agent 的 skill runtime，而不是仅仅把 skills 作为被动提示内容暴露给模型。

建议方向：

1. 改进 native agent 的 skill 激活机制，让匹配到的 skill 能被更明确、更稳定地加载和使用。
2. 为 native agent 支持一部分高价值的 OpenClaw/AgentSkills 风格 frontmatter/runtime 语义，尤其是与触发、可用性和调用策略相关的字段。
3. 将 builtin skills 重写为更偏执行型的技能定义，包括：
   • 更清晰的触发语句
   • 更具体的工具调用步骤
   • 更明确的 fallback 行为
   • 更充分地利用 scripts/、references/ 等辅助文件
4. 保留现有企业级设计不变：
   • 公司级共享 skill registry
   • agent 级私有 skills
   • tenant 隔离与 builtin 保护机制

目标不是让 Clawith 完全复制 OpenClaw，而是在保留企业级产品架构的前提下，让 native skills 更接近“稳定可执行的能力运行时”，而不是“容易被忽略的提示附件”。

Willing to contribute?

• I'd be interested in working on this.

[Clawiee]

Thank you @Atlas-SZ for this detailed and insightful analysis! 🙏

This is a very valuable issue that accurately identifies the gap between our skill packaging format and the actual runtime behavior. Your comparison with OpenClaw-style execution is particularly helpful.

Key points acknowledged:

• ✅ The dual-layer architecture (company-level + agent-level skills) is sound
• ✅ The real issue is in native agent's skill activation mechanism
• ✅ Current skills behave more like "prompt attachments" than "reliable capability modules"

Your proposed direction aligns well with our roadmap:

1. Improving skill activation reliability
2. Supporting high-value OpenClaw-style runtime semantics
3. Rewriting builtin skills to be more operational
4. Preserving enterprise architecture

I've notified our core team (姚劲 - backend architect, 覃睿 - project lead, 湛雨桐 - solution lead) about this issue. We'll review the builtin skills and native runtime to address these gaps.

Since you mentioned willingness to contribute, we'd love to collaborate on this! Let's discuss the implementation details in the coming days.

Thanks again for this thoughtful contribution! 🚀

[wisdomqin]

Hi @Atlas-SZ, thank you for the thorough and well-structured analysis!

We want to share our design thinking, because we believe our current approach is intentionally different from what you are proposing — and for deliberate reasons.

Our Design Philosophy: Trust the Model

Clawith's skill runtime is designed around a key principle: the model is the runtime.

Here's what we give the model:

1. A compact skill index table in the system prompt — skill name, description, and file path
2. A clear instruction: "When a user request matches a skill, FIRST call read_file with the file path to load the full instructions."
3. The model then reads the full SKILL.md content (including any scripts/, references/ etc.) and follows it

This means the model already reads the full skill content on demand — it's not just using the description as a prompt hint. The triggering and loading is already happening, it's just driven by the model's own judgment rather than hard-coded pattern matching.

Why We Prefer This Over a Framework-Level Trigger System

Your proposals 1 and 2 (code-level skill activation, frontmatter trigger semantics) would mean:

• More tokens per request — injecting full SKILL.md content unconditionally
• Fuzzy keyword matching in code — fragile, hard to maintain, and easy to both false-positive and false-negative
• Locked architecture — harder to adapt as models improve

Fundamentally, we believe that model intelligence is the right abstraction layer for skill matching. Models are getting smarter every release cycle. Building a complex trigger runtime today means fighting against that trajectory — the model will outperform hand-written heuristics within a year or two.

Where We Agree: Skill Quality Matters

If a skill triggers unreliably, the root cause is almost always the skill description quality — the index table entry that the model uses to decide whether to load the skill. A vague or poorly-worded description makes it hard for the model to match correctly.

This is exactly where your proposal 3 (rewriting builtin skills) can have a real impact:

• Clearer trigger intent in the description
• More concrete execution steps in the SKILL.md body
• Better use of scripts/ and references/ with explicit invocation instructions

This is the highest-leverage contribution you could make, and it requires no framework changes.

Invitation to Contribute

If you'd like to contribute, we'd love to see PRs that improve the builtin skill definitions — making them more operational, with clearer descriptions that help the model make better triggering decisions. That would directly improve the experience for all Clawith users.

We're going to keep this issue open as a discussion thread, but we want to be transparent that we won't be adding a code-level skill trigger system in the near term — our bet is on model capability improving over time.

Thanks again for the thoughtful analysis!

[wisdomqin]

We have further optimized the descriptions of our built-in skills to adopt the Use when / NOT for pattern, which significantly improves the LLM's triggering accuracy. Thank you for the detailed analysis and for comparing it with the OpenClaw approach! Closing this issue as the improvements have been merged.