Clawhub Skill Optimizer

Publish Skill Optimizer

Optimize SKILL.md-based skills for public distribution across ClawHub, Claude, Hermes, GitHub, and related runtimes, while preserving the original runtime behavior.

When to use

• When packaging or refining a skill for public distribution on ClawHub, Claude, Hermes, or GitHub
• When optimizing skill naming, frontmatter, and body structure for better search discoverability and agent invocation
• When generating bilingual English and Chinese variants
• When deciding how a mother skill should differ from a platform-specific publish bundle
• When improving first-turn clarity, task framing, and "爆款化" positioning without rewriting runtime logic

When NOT to use

• When the task is primarily about plugin manifests or marketplace wrappers; use clawhub-plugin-packager
• When the main task is auditing security or Suspicious/upload risk; use clawhub-security-auditor
• When editing business logic, API behavior, or runtime code beyond what is needed for publish-surface alignment

Scope boundary

This skill owns:

• skill naming and bilingual naming
• YAML frontmatter quality
• SKILL.md structure
• publish-mode wording and section layout
• search discoverability and invocation wording
• deciding between source-skill and platform-release variants

This skill does not own:

• plugin manifest generation
• release zip assembly rules
• deep security/risk auditing
• broad runtime refactors

Release Modes

Choose the target mode before editing copy:

• source mode
  • canonical mother skill in targetSkills/
  • keep cross-platform structure
  • prefer metadata.aisa as the source of truth
• clawhub publish mode
  • optimize for ClawHub search, parser compatibility, and low-risk upload wording
  • prefer short high-intent descriptions and conservative publish surfaces
• claude publish mode
  • optimize for Claude Code / skills.sh readability and direct invocation
  • remove references to files or commands not shipped in the release bundle
• hermes publish mode
  • optimize for Hermes category/tag discovery, runtime-only packaging, and community-safe wording

If one SKILL.md cannot satisfy all targets cleanly, generate separate publish variants rather than forcing a single noisy compromise.

Core principles

1. Selection happens on the description first

Agents usually see name and description before they read the full body. The description must therefore:

• say what the skill does in plain language
• contain the trigger phrase Use when: or 触发条件：
• include the exact task words a user would actually search for
• state the first useful outcome, not generic marketing

2. "爆款化" means clearer task framing, not hype

When improving a public skill, prefer:

• title = user task, not internal project codename
• first line = immediate user value
• examples = concrete, high-intent requests
• family positioning = each sibling skill owns a distinct job instead of keyword overlap

Avoid:

• generic adjectives like powerful, best, advanced
• vague platform bragging
• making multiple sibling skills compete for the same exact positioning

3. Mother skill and publish bundle can differ

The source skill can stay richer and more portable. The publish bundle should only describe the shipped runtime and shipped files.

Hard repository conventions

When optimizing a published repo skill, enforce these before polishing copy:

• Use minimal frontmatter with name, description, and canonical metadata.aisa.
• Prefer metadata.aisa.emoji, metadata.aisa.requires, metadata.aisa.primaryEnv, and metadata.aisa.compatibility.
• Do not leave legacy fields like argument-hint, allowed-tools, user-invocable, homepage, or repository in a published skill unless the target platform truly requires them.
• Every command example must use {baseDir} when a runtime placeholder is needed.
• Keep SKILL.md aligned to the shipped runtime only. If compare/test/sync/dev scripts are not in the publish artifact, do not mention them.
• For Python skills, prefer stdlib-first runtime bundles. Do not describe requests, httpx, uv, or pyproject.toml as required unless the shipped runtime truly depends on them.
• If the repo contains a richer mother skill plus slimmer publish bundles, optimize the publish bundles and do not strip the mother skill's developer workflows.
• In stateless publish bundles, remove references to watchlists, recurring briefings, SQLite accumulation, or long-lived schedulers unless they intentionally ship.
• If a feature depends on side-channel auth such as direct GitHub tokens and is not core to the publish runtime, remove it from publish copy instead of advertising split-auth behavior.
• If EN and ZH variants exist, keep the same runtime surface area, safety trimming, command layout, and section structure across both.

Recommended body structure

Choose only the modules that help the shipped runtime:

• When to use
  • always include
• When NOT to use
  • include when nearby sibling skills exist
• Quick Reference
  • include for CLI-first skills
• Capabilities
  • include for multi-function skills
• High-Intent Workflows
  • include when the skill has multiple high-value user jobs
• Inputs and Outputs
  • include when the interface is structured
• Example Requests
  • include when search/discovery matters
• Setup
  • include only what the published runtime actually needs

Description rules

Preferred English pattern:

[Core task]. Use when: [trigger]. Supports [important outcomes].

Preferred Chinese pattern:

[核心任务]。触发条件：当用户需要[场景]时使用。支持[关键结果]。

Description quality checklist:

• 50-200 characters when possible
• no angle brackets <>
• exact task keywords present
• no marketing fluff
• no undocumented dependencies

Validation checklist

Before publishing, verify:

1. Frontmatter is valid and machine-readable.
2. name is short, keyword-rich, and appropriate for the platform.
3. description contains Use when: or 触发条件：.
4. The skill body matches the shipped runtime and shipped files.
5. Required env vars and binaries are declared in metadata.aisa.
6. EN and ZH variants have parallel runtime scope.
7. The optimization changed wording and packaging clarity, not core runtime semantics.
8. Sibling skills do not compete for the same exact positioning.

Lightweight publish-risk reminders

While this skill is not a full auditor, always avoid obvious publish regressions:

• do not advertise password, cookie, or browser-credential flows
• do not describe non-runtime helper scripts as part of normal usage
• do not default to home-directory persistence in public bundles
• do not claim functionality that only exists in source/dev tooling

Example requests

• Optimize this skill for ClawHub search and upload
• Turn this mother skill into source mode plus Hermes publish mode
• Rewrite the SKILL.md so Claude and Hermes versions each read cleanly
• Make these EN/ZH variants consistent and more high-intent without changing runtime behavior