playbooks

home / skills / tencentcloudbase / cloudbase-mcp / skill-authoring

skill-authoring skill

/skills/skill-authoring

This skill helps you create, rewrite, and evaluate SKILL.md files with clear triggers, structure, and testable behavior for reliable agent skills.

npx playbooks add skill tencentcloudbase/cloudbase-mcp --skill skill-authoring

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
3.4 KB
---
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, 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
- Split a large skill into `SKILL.md` plus `references/`, `assets/`, or `scripts/`
- Design evaluation prompts and review whether a skill triggers and behaves correctly

**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. **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` |
| 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. Write the main `SKILL.md` so it changes agent behavior after trigger.
4. Move deep detail into `references/`, `assets/`, or `scripts/` as needed.
5. 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?
- 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?

Overview

This skill helps design, improve, and evaluate reusable agent skills with clear triggers, progressive disclosure, and testable behavior. It focuses on producing a concise main skill document, precise trigger descriptions, and reference files that guide agent behavior after a trigger. Use it to ensure skills trigger correctly and behave reliably in real interactions.

How this skill works

I inspect the requested change class (create, rewrite, review, or evaluate) and optimize the trigger surface first by drafting name and description with realistic trigger phrases. I then shape the main skill document so it prescribes agent behavior after activating, and I organize deep details into referenced files to be loaded only when needed. Finally, I produce evaluation prompts and run should-trigger and should-not-trigger checks to iterate until trigger quality and behavior are stable.

When to use it

  • When creating a new skill document and defining its activation language
  • When improving a skill’s name, short description, or trigger precision
  • When reviewing a skill that is too broad, too narrow, or poorly structured
  • When splitting a large skill into a main file plus references, assets, or scripts
  • When designing evaluation prompts and verifying trigger behavior

Best practices

  • Start by identifying the skill’s job, boundaries, and nearest neighbors
  • Draft a short, intentional name and put realistic trigger language in the short description
  • Make the main skill file specify what the agent must do immediately after triggering
  • Move deep guidance into reference files and load them only when relevant
  • Create explicit should-trigger and should-not-trigger prompts and iterate on failures

Example use cases

  • Rewrite a skill’s description so the agent only activates on specific user intents
  • Split a monolithic skill into a concise main file and separate reference examples
  • Design evaluation tests to catch false positives and false negatives before release
  • Review an existing skill to ensure it changes agent behavior rather than only documenting
  • Improve trigger wording so downstream routing loads only required reference files

FAQ

How do I know if a skill is too broad?

Check whether the name and short description overlap multiple distinct jobs; if so, narrow the trigger language and define explicit exclusions.

What belongs in the main skill file versus a reference file?

Put behavior rules and immediate actions in the main file; move long examples, datasets, or implementation scripts to reference files loaded on demand.