agent-essentials（Agent 要领）

Agent Essentials

This skill has two jobs:

1. Expand capabilities — discover better capability paths before declaring failure.
2. Self-improve — capture important lessons and route them to the right durable layer.

Capability Expansion

Rule: never stop at "I can't" or "no built-in way" without checking for a better capability path.

Triggers — request implies external platform / workflow automation / system integration / repeatable ops / capability gap. Common phrasing: *"automate X" / "integrate with X" / "support X platform" / "help me do this in X"*.

Workflow

1. Detect the gap

- Input: the user's request. - Test: would solving this same request appear ≥2 times across this user's work? OR does it require a tool/platform not in the loaded skill list? - Output: a 1-line verdict — gap: <yes/no> — <which capability is missing>. If no, exit this workflow and answer normally. - If ambiguous: count yes on {*reusable later? / specific platform? / >1 step?*}; ≥2 yes → treat as gap.

1. Search

- Input: gap verdict + missing-capability keywords from step 1. - Where: (a) loaded skill list — match name/description/triggers; (b) ClawHub via https://clawhub.ai/search?q=<keyword>, try 1–3 variants. - Stop: strong match found OR 3 variants returned nothing. - Output: 1–3 candidates as <name> — <one-line value> — <fit: strong/moderate/weak>.

1. Act — pause for user confirmation before any of these:

- Installing a skill → show name, source, one-line value, and ask "install? [y/N]" before downloading. - Creating a new custom skill → show the proposed name + 3-line description and ask before scaffolding. - Doing the task directly → only this branch may proceed without confirmation, and only if no fallback above is viable.

Self-Improvement

Rule: when something meaningful is learned, preserve the minimum useful lesson.

Triggers — meaningful failure / user correction / recurring mistake / discovery of a better workflow. Do not log trivial failures or one-off noise.

Workflow

1. Capture

- Input: the trigger event (failure / correction / insight). - Output: a 3-line lesson:

     What: <what went wrong or was discovered>
     Correct: <the actually correct behavior>
     Next time: <concrete trigger → action>

- Reject: can't fit in 3 lines → lesson too vague, sharpen first.

1. Route

- Store the learning in the right place:

- For any ✓ row: show the diff and ask "append to <file>? [y/N]" before writing. Never silently mutate durable files.

1. Promote to durable file only if all hold:

- Recurring — ≥2 occurrences (user saying "Nth time" / "又错了" is proof) - High-value — non-trivial consequence (broken CI, lost work, wrong user output), not style nits - Broadly reusable — class of situations, not one specific file/PR - Rule-preventable — a future-you reading the rule would avoid it - If any fails, keep in daily memory only.

File Locations

Resolve durable files in this order — first hit wins:

If none exists and a write is approved, create at the project-root path (or ~/.claude/ for USER.md) and tell the user "creating new file <path>."

Decision Tree

Something notable happened
├─ Capability gap?
│  └─ Search → Recommend → Install or fallback
├─ Lesson worth keeping?
│  └─ Capture → Route → Promote if recurring
└─ Neither
   └─ Continue normally

Edge Cases

• User declines install → fall to "do directly" or "create custom"; do not re-pitch in this session.
• ClawHub unreachable → state failure; rely on local list only; offer retry.
• 2+ candidates tie "strong" → show all + 1-line differentiator and let user pick; never silently choose.

Principles

• Search before saying "nothing exists." Prefer short learnings over elaborate templates.
• Do not promote one-off lessons. Do not install weak-matching skills just to reduce uncertainty. Do not rewrite major workspace files casually.