skill-authoring

---
name: skill-authoring
description: Design, improve, and evaluate reusable agent skills with high-quality SKILL.md files, precise trigger descriptions, progressive disclosure, and testable behavior. This skill should be used when users ask to create a new skill, rewrite or review an existing skill, audit a skill collection such as `config/source/skills` for redundancy or overlap, improve skill trigger quality, organize skill references, or evaluate whether a skill should trigger and behave correctly.
alwaysApply: false
---

# Skill Authoring

Create and refine reusable agent skills with better trigger quality, cleaner structure, stronger behavioral guidance, and more reliable evaluation.

## When to use this skill

Use this skill when you need to:

- Create a new `SKILL.md`
- Improve an existing skill's `name` or `description`
- Review whether a skill is too broad, too narrow, or poorly structured
- Audit a local skill collection such as `config/source/skills` for redundancy, trigger overlap, or weak boundaries
- Split a large skill into `SKILL.md` plus `references/`, `assets/`, or `scripts/`
- Design evaluation prompts and review whether a skill triggers and behaves correctly

## Repo-managed CloudBase skill review

When the task targets `config/source/skills`, apply these guardrails in addition to the normal skill-authoring workflow:

This section is the repo-managed CloudBase skill review baseline for this repository.

- Keep frontmatter complete and normalized, including `version`
- Keep examples inside the skill's declared platform and scope
- Keep shared operational rules in one canonical source instead of copying large blocks across neighboring skills
- If the skill claims a rule is mandatory, show that rule in at least one example
- When giving a recommended default, also explain the tradeoff behind it
- Do not add agent-directed remote skill-fetch URLs (for example `cnb.cool/.../git/raw/...` skill bodies or `(standalone fallback: ...)` raw links). Marketplace reviewers treat those as injection / session-hijack risk.
- Prefer local relative sibling paths (`../other-skill/SKILL.md`). If a sibling is missing, tell the agent to ask the user to install the full CloudBase plugin or skills pack — never to HTTP-fetch remote skill markdown into context.
- Human documentation URLs (`docs.cloudbase.net`, console pages) remain allowed when they are not skill-body fetch instructions.
- Do not infer public CNB / OpenClaw / ClawHub paths from the source tree when writing marketplace-facing install docs; verify the actual published structure first.

**Do NOT use for:**
- General documentation writing that is not about skills
- README polish or marketing copy
- Prompt tweaks that do not affect skill structure or behavior
- Rule files unrelated to `SKILL.md`

## How to use this skill (for a coding agent)

1. **Identify the task class first**
   - Determine whether the request is about creating a new skill, reviewing an existing skill, or improving trigger quality, structure, or evaluation

2. **Optimize the trigger surface early**
   - Draft `name` and especially `description` before expanding the body
   - Put realistic trigger language into `description`, not only into the body

3. **Design behavior, not just documentation**
   - Make the main `SKILL.md` tell the agent what to do after the skill triggers
   - Use references for deeper guidance, not as a substitute for behavioral rules

4. **Load supporting materials only when needed**
   - Use the routing table to decide which reference file to read
   - Avoid loading every reference file by default

5. **Use collection-level review when the request is about many skills**
   - When reviewing `config/source/skills`, check overlap, duplication, trigger boundaries, and progressive disclosure across neighboring skills
   - Prefer evidence-based findings with concrete file references and rewrite guidance
   - Treat source layout, published skills-repo layout, and marketplace-consumed layout as different surfaces until you verify they are the same

6. **Evaluate before considering the skill complete**
   - Create should-trigger and should-not-trigger prompts
   - Run them, review the results, and iterate on the skill

## Routing

| Task | Read |
| --- | --- |
| Write or improve `name` and `description` | `references/frontmatter-patterns.md` |
| Design skill anatomy and progressive disclosure | `references/structure-patterns.md` |
| Draft a new skill or review an existing one | `references/templates.md` |
| Audit `config/source/skills` for quality, redundancy, and overlap | `references/repo-skill-review.md` |
| Review repo-managed CloudBase source skills | `references/cloudbase-skill-review.md` |
| Build evaluation prompts and review outcomes | `references/evaluation.md` |
| Compare good examples, weak examples, and rewrites | `references/examples.md` |

## Quick workflow

1. Identify the skill's job, boundary, and closest neighboring skills.
2. Draft `name` and `description` with realistic trigger language.
3. If the task targets `config/source/skills`, read `references/repo-skill-review.md`, then load `references/cloudbase-skill-review.md` for CloudBase-specific standards before proposing rewrites.
4. Keep sibling routing local-only; do not add remote skill-fetch URLs.
5. Write the main `SKILL.md` so it changes agent behavior after trigger.
6. Move deep detail into `references/`, `assets/`, or `scripts/` as needed.
7. If the skill ships in `plugin/cloudbase`, also write `plugin/cloudbase/skill-metadata.json` (see `references/templates.md` landing checklist) and run `npm run build:skill-manifest`.
8. Run evaluation prompts and revise until trigger quality and behavior are stable.

## Minimum self-check

- Is the `name` short, intentional, and stable?
- Does the `description` explain both capability and trigger conditions?
- Does the main `SKILL.md` change agent behavior after trigger?
- Are non-applicable scenarios explicit?
- Does routing point to the right reference file for each task?
- Does the skill avoid agent-directed remote skill-fetch URLs and keep sibling routing local-only?
- Are evaluation prompts present for both should-trigger and should-not-trigger cases?
- Can you explain why this skill stays distinct from its nearest neighbors?
- If reviewing a skill collection, can you point to redundancy, overlap, and missing boundaries with concrete evidence?
- If this is a plugin skill, does `plugin/cloudbase/skill-metadata.json` include the new dir with non-empty `promptSignals.phrases`?

• SKILL.md 6 KB
• references/cloudbase-skill-review.md 6 KB
• references/evaluation.md 4 KB
• references/examples.md 2 KB
• references/frontmatter-patterns.md 3 KB
• references/repo-skill-review.md 7 KB
• references/structure-patterns.md 5 KB
• references/templates.md 5 KB