Skill Authoring

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 infer public CNB / OpenClaw / ClawHub paths from the source tree; verify the actual published structure before writing fallback links or marketplace-facing URLs
• If a skill mentions raw URLs, blob URLs, or marketplace-consumed paths, check live reachability before finalizing the text
• Put standalone-install fallback guidance where the user needs it: keep the top-level note short, and place sibling-skill fallback links next to the actual cross-skill reference

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

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. If the skill text will mention published URLs or fallback paths, verify the public structure and at least one real URL before writing. 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. 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?
• If the skill references public URLs or standalone-install fallback paths, were those URLs verified against the actual published surface instead of guessed from local directories?
• 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?

CloudBase Skill Review

Purpose

Use this reference when auditing or rewriting the CloudBase skill collection under config/source/skills/. It adds CloudBase-specific review rules on top of the general repo-skill review workflow.

Use it as the checklist for frontmatter completeness, examples stay in scope, shared rules should have a single canonical source, and other CloudBase collection-specific review gates.

Core standards

1. Frontmatter completeness

Every repo-managed CloudBase source skill should declare:

• name
• description
• version
• alwaysApply

For version, use a normalized SemVer-like value such as 2.15.4. Do not use v2.15.4, and do not let sibling source skills drift to different release styles without a clear reason.

2. Examples stay in scope

Examples must match the skill's declared platform and boundary:

• Web-only skills should not contain mini program code
• Mini program skills should not drift into Web SDK auth flows
• Platform-overview skills should not expand into full implementation recipes that belong in a specialized sibling

If a section contradicts Do NOT use for, treat it as a priority bug, not a copywriting issue.

3. Shared rules should have a single canonical source

When multiple CloudBase skills need the same operational rule:

• Keep the full rule in one canonical source
• Reference that source from neighboring skills instead of copying large blocks
• Only restate the minimum reminder needed for local context

This is especially important for MCP / mcporter setup, schema-inspection rules, and other control-plane workflows that easily drift across files.

4. Rules must appear in examples, not only prose

If a skill says something is mandatory, recommended, forbidden, or required, at least one example should demonstrate that behavior directly.

Examples:

• If auth flows require error handling, show try/catch
• If a default is recommended to reduce cold starts, show the recommended value in the example payload
• If a platform boundary matters, do not leave a contradictory example elsewhere in the file

5. Explain tradeoffs behind recommended defaults

Do not stop at "use X by default." Also explain the operational tradeoff:

• MinNum: 1 reduces cold start latency but costs more than 0
• A canonical URL path may still need live console verification if the product UI changes
• An alwaysApply setting should only stay enabled if the skill truly needs to win globally

6. Verify published-surface paths instead of inferring them

When a CloudBase skill needs fallback links, marketplace-facing references, or raw-source URLs:

• Treat the local source tree, generated skills repo, all-in-one bundle, and marketplace-consumed layout as separate surfaces until proven otherwise
• Do not assume config/source/skills/<id>/SKILL.md maps to the public CNB raw path
• Verify at least one real target URL before repeating the pattern across the collection
• Distinguish raw-source URLs from page-view URLs such as blob
• If the public surface uses a container entry plus references/..., write fallback rules for that structure, not the local authoring layout

7. Put fallback guidance close to the actual reference

When a skill is published standalone and also references sibling skills:

• Keep the top-of-file standalone note short and focused on the main entry plus the current skill
• Add sibling fallback links next to cross-skill references such as ../auth-tool/SKILL.md
• Keep same-skill references/... paths relative unless the target surface is known to drop those files
• If nested reference files may be opened directly, make sure they still have a recoverable path back to the current skill or main entry

8. Treat auth-nodejs as the quality benchmark

Use config/source/skills/auth-nodejs/SKILL.md as a positive reference when reviewing nearby skills. It is a good benchmark for:

• scenario-based structure
• explicit boundaries
• concrete API signatures
• error handling in examples
• cross-skill routing discipline

CloudBase-specific smell checks

• A code block contains repeated const declarations that make the snippet invalid JavaScript or TypeScript
• A platform-specific skill contains examples from a different platform
• The same mcporter config block appears in multiple sibling skills
• A skill claims a rule is required, but none of its examples actually follow it
• Console URL paths disagree between the CloudBase guideline and the platform overview
• A public fallback URL was inferred from the source tree without a live reachability check
• A long fallback section appears only at the top, but the actual sibling-skill reference gives the user no direct path to follow

Review workflow

1. Check frontmatter and normalize version 2. Check scope boundaries and remove cross-platform examples 3. Check whether any public URL or fallback path was verified against the real published surface 4. Check whether duplicated rules should collapse into one canonical source 5. Check whether recommended defaults explain their tradeoffs 6. Compare the result against auth-nodejs for structure and example quality

Evaluation prompts

Should-trigger

1. Audit config/source/skills and tell me which CloudBase skills have overlapping MCP setup rules. 2. Review this CloudBase skill and tell me whether its examples stay inside the declared platform boundary. 3. Help me standardize version fields and error-handling examples across the CloudBase source skills.

Should-not-trigger

1. Help me polish the marketing copy on this README. 2. Build a new CloudBase function for me. 3. Fix a failing SQL migration in the app runtime.

Evaluation

Purpose

A skill should not only trigger. It should also produce the right behavior after trigger. Use this reference to design evaluation prompts, run review loops, record findings, and decide whether a skill is ready to ship.

Core Method

Following the skill-creator style, evaluate a skill as a closed loop:

1. Draft the skill 2. Design realistic prompts 3. Run those prompts 4. Review both trigger behavior and output quality 5. Revise description, operating rules, routing, or references 6. Test again until boundaries and behavior are stable

Prompt Sets

Each skill should have at least two prompt sets:

• should-trigger
• should-not-trigger

If a skill only tests should-trigger cases, it will hide many false positives.

Prompt Design Rules

Should-Trigger

Cover:

• Core scenarios
• Realistic user phrasing
• Mixed-language or alias phrasing when relevant
• Variations that should still trigger

Should-Not-Trigger

Cover:

• Neighboring skill scenarios
• Requests with similar words but different tasks
• Requests that contain partial keywords but should not match

Minimal Evaluation Set

Each skill should ideally include at least:

• 3 should-trigger prompts
• 3 should-not-trigger prompts
• 1 closest-neighbor comparison

Do not stop at writing prompts. Run them.

Acceptance Dimensions

Review each round along these dimensions:

1. Trigger Precision

• Does the skill stay quiet when it should not trigger?

2. Trigger Recall

• Does it trigger in realistic core scenarios?

3. Behavioral Correctness

• After triggering, does the agent follow the required process?

4. Context Discipline

• Does it load only the references, assets, or scripts it actually needs?

5. Boundary Clarity

• Does it remain distinct from the nearest neighboring skills?

Pass Criteria

A skill is ready to ship only when:

• Core should-trigger prompts consistently activate it
• Obvious should-not-trigger prompts do not activate it
• Post-trigger behavior matches the operating rules in SKILL.md
• It does not load extra references without a reason
• The nearest neighboring scenario can be distinguished clearly

Run and Review

During testing, watch for:

• Whether the skill triggered at all
• Whether it triggered at the right time
• Whether the output reflects the promised capability
• Whether the correct references were loaded
• Whether any required steps were skipped
• Whether nearby scenarios were incorrectly captured

Diagnosis Guide

If the results are weak, trace the problem back:

• Too many false positives: tighten description, remove broad verbs, clarify non-applicable cases
• Weak recall: add aliases, platform terms, and realistic phrasing
• Triggered but behaved incorrectly: rewrite Operating Rules, workflow, or examples
• Too much context loaded: tighten routing and reduce default reads
• Main file too heavy: move detail into references/, assets/, or scripts/

Evaluation Record Template

## Prompt

- Type: should-trigger / should-not-trigger
- Text: ...

## Result

- Triggered: yes / no
- Correct timing: yes / no
- Behavior correct: yes / no
- Extra context loaded: yes / no

## Notes

- What went right:
- What went wrong:
- Rewrite action:

Summary Template

## Evaluation Summary

- Trigger precision:
- Trigger recall:
- Behavioral correctness:
- Context discipline:
- Boundary clarity:

## Most Confusing Neighbor

- Neighbor skill:
- Why confusion happens:
- How this skill stays distinct:

## Decision

- Ready to ship / Needs rewrite

Iteration Loop

1. Draft description and operating rules 2. Design evaluation prompts 3. Run them 4. Review using the acceptance dimensions 5. Revise description, operating rules, routing, references, assets, or scripts 6. Repeat until the skill meets the pass criteria

Examples

Good Frontmatter Example

---
name: cloudbase
description: CloudBase is a full-stack development and deployment toolkit for building and launching websites, web apps, WeChat Mini Programs, and mobile apps. This skill should be used when users ask to develop, deploy, publish, migrate, or optimize apps with CloudBase, Tencent CloudBase, or Tencent Cloud Development, or when they ask to compare CloudBase with Supabase.
---

Why it works:

• The opening phrase clearly defines the product and capability domain
• The trigger sentence states when the skill should activate
• The keyword mix covers product, platform, action, and migration/comparison scenarios

Weak Frontmatter Example

---
name: cloudbase-best-skill-for-all-development-and-deployment
description: A powerful skill for many different development tasks.
---

What is weak about it:

• The name is too long and unstable
• The description is broad and vague
• The trigger boundary is unclear

Better Rewrite

---
name: cloudbase
description: CloudBase is a full-stack development toolkit. This skill should be used when users ask to build, deploy, launch, migrate, or compare CloudBase web apps, mini programs, backend services, or cloud-integrated projects.
---

Good Structure Example

A strong structure for a complex skill usually looks like this:

• SKILL.md for entry point and routing
• references/ for deeper methodology
• assets/ for reusable templates or sample materials
• scripts/ for executable helper capabilities

Bad Structure Example

Common structural problems:

• A single SKILL.md contains everything
• Many files exist but there is no routing
• Rules, examples, templates, and FAQ are mixed together

Example Evaluation Prompts

Should-Trigger

1. Help me write a new skill for guiding agents to document MCP tools. 2. This skill description is not activating reliably. Rewrite it to improve trigger quality. 3. I need to split a large SKILL.md into a main file and references. Design the structure.

Should-Not-Trigger

1. Help me make this README sound more polished and persuasive. 2. Help me implement a new MCP tool. 3. Help me improve the visual design of this React page.

Frontmatter Patterns

Purpose

Use this reference to design or improve SKILL.md frontmatter with better trigger quality, discoverability, and separation from neighboring skills.

Core Pattern

A strong description usually does two things:

1. Introduces the product, domain, or capability 2. States when the skill should be used with realistic trigger language

Recommended pattern:

---
name: skill-name
description: Short domain or capability introduction. This skill should be used when users ask to ...
version: 1.2.3
---

Field Guidance

name

Recommended:

• Short
• Stable
• Focused on the main domain, product, or task

Avoid:

• Putting every keyword into the name
• Using vague labels that overlap many unrelated skills
• Tying the name to changing implementation details

description

Recommended:

• Start with what the skill is about
• Add a clear This skill should be used when... sentence
• Use realistic user phrasing, not only internal terminology

Avoid:

• Generic claims like "a powerful skill"
• Abstract capability words without specific scenarios
• Overly broad phrasing that catches unrelated work

version

Recommended:

• Use a normalized SemVer-like value such as 2.15.4
• Keep the value machine-readable and stable across the skill collection
• Use the same release version across sibling source skills when they ship together

Avoid:

• Prefixes like v2.15.4
• Mixing version styles across one skill collection
• Omitting the field in repo-managed source skills that are expected to ship together

Keyword Buckets

When drafting description, consider these five keyword buckets:

Brand Words

• Official product names
• Common aliases
• Chinese-English variants when relevant
• Migration or comparison neighbors

Platform Words

• website
• web app
• dashboard
• mini program
• mobile app
• backend service

Scenario Words

• build
• deploy
• launch
• migrate
• compare
• debug
• optimize

Action Words

• create
• review
• rewrite
• improve
• evaluate
• structure
• split

Capability Words

• authentication
• database
• storage
• cloud functions
• API
• AI
• routing
• references

Precision vs. Recall

Precision-first

Use this when accuracy matters more than broad matching:

• Focus on the main product and primary scenarios
• Keep only the most useful neighboring terms
• Reduce false positives

Recall-first

Use this when discoverability matters more than precision:

• Add more aliases and common phrasings
• Cover broader task wording
• Accept a higher risk of accidental matches

Rewrite Checklist

Before finalizing frontmatter, verify:

• The name is short and intentional
• The opening phrase clearly defines the domain
• The This skill should be used when... sentence uses realistic trigger wording
• The description balances brand, platform, scenario, action, and capability terms
• The boundary is explicit enough to avoid swallowing neighboring skills
• You can explain why this skill should trigger instead of a nearby alternative

Repo Skill Review

Purpose

Use this reference when the task is to review a repository-managed skill collection such as config/source/skills/ for quality, redundancy, trigger overlap, structure issues, or weak behavioral guidance.

This review mode is based on:

• Claude skill best practices: Skill authoring best practices
• Datawhale skill write-up: 如何写出好的 Skill
• Trae guide: 如何写好一个 Skill：从创建到迭代的最佳实践

When to use this reference

Use it when the user asks to:

• check the quality of config/source/skills
• find redundant or overlapping skills
• review whether skill descriptions are too broad or vague
• inspect whether SKILL.md files are too heavy and should be split
• evaluate whether repo-managed skills follow good authoring practice

Review Scope

Treat the audit as four linked checks:

1. Trigger quality 2. Boundary clarity 3. Structure and progressive disclosure 4. Collection hygiene

Do not stop at "this skill feels weak." The output should identify which dimension failed and what to rewrite.

Core Principles

1. Description is the trigger surface

description should explain both:

• what the skill does
• when it should be used

For collection reviews, this means checking whether neighboring skills use distinguishable trigger language.

Smells:

• descriptions like "helps with X"
• missing task or context cues
• broad verbs shared across too many skills
• synonyms stuffed into one skill without a clear boundary

2. Write for the agent, not for humans

Review SKILL.md for operational behavior, not team-facing prose.

Smells:

• background history
• version history / changelog notes
• README-style onboarding text
• values or principles without actionable behavior

Prefer instructions that change what the agent does after trigger.

3. Keep only high-value context in the main file

The main SKILL.md should stay concise and behavior-first.

Check for:

• repeated explanations the model likely already knows
• long tutorials in the main file
• deep detail that belongs in references/
• repeated manual procedures that should become scripts/

4. Progressive disclosure should be explicit

SKILL.md should route the agent to the right reference file at the right time.

Smells:

• many reference files with no reading order
• nested references that require reading references from references
• no scenario-to-reference routing
• heavy context loading by default

5. Neighboring skills must stay distinct

For repo-level audits, always compare the target skill against its nearest neighbors.

Typical overlap patterns in config/source/skills:

• platform vs domain skill overlap
• auth entry skill vs platform-specific auth skill overlap
• web vs mini program vs nodejs database skill overlap
• "design/spec/review" skills that all claim broad planning or evaluation verbs

If two skills share the same likely prompts, the review should explain whether to:

• tighten one description
• add non-applicable cases
• move shared detail into a reference
• merge the skills
• split one skill by platform or mode

Repo Audit Workflow

Step 1: Build the inventory

1. List all candidate skills under config/source/skills/ 2. Read the target SKILL.md files first 3. Group nearby skills by domain, platform, or user intent

Useful groupings:

• auth
• database
• frontend / UI
• deployment / runtime
• planning / review
• AI model usage

Step 2: Check frontmatter quality

For each skill, ask:

• Is the name short, stable, and specific?
• Does the description describe both capability and trigger condition?
• Would the description still be understandable without reading the body?
• Is the wording in third-person / neutral instruction style rather than "I can help..."?
• Does it overclaim scenarios already covered by a neighbor?

Step 3: Check body quality

Ask:

• Does the main file tell the agent what to do first?
• Are non-applicable scenarios explicit?
• Is the routing table present and useful?
• Is behavior specific enough for fragile tasks?
• Is the file acting like an execution guide rather than a general article?

Step 4: Check structure quality

Ask:

• Should some sections move into references/?
• Are there scripts that would make fragile or repeated operations safer?
• Are references one level deep from SKILL.md?
• Do long reference files need a table of contents?

Step 5: Check overlap and redundancy

Compare neighboring skills for:

• same nouns + same verbs in description
• duplicated workflow steps in SKILL.md
• repeated examples that could live in one place
• multiple skills routing to the same scenario without differentiation

Mark each overlap as one of:

• acceptable overlap
• mild redundancy
• trigger conflict
• merge candidate
• split candidate

Step 6: Design evaluation prompts

For any skill that may be too broad or too narrow, create:

• at least 3 should-trigger prompts
• at least 3 should-not-trigger prompts
• 1 closest-neighbor comparison

Collection audits should include cross-skill prompts such as:

• "Should this trigger auth-tool or auth-web?"
• "Should this trigger web-development or ui-design?"
• "Should this trigger http-api or cloud-functions?"

Findings Format

When reporting the audit, prefer review-style findings ordered by severity.

For each finding, include:

• affected skill file(s)
• issue type: trigger / boundary / structure / redundancy
• why it matters
• the smallest useful rewrite direction

Example labels:

• [P1] Trigger wording overlaps with sibling skill
• [P2] Main SKILL.md contains reference-grade detail
• [P2] Missing non-applicable cases causes false positives
• [P3] Duplicate examples should move to shared reference

Rewrite Guidance

Use these rewrite moves first:

1. Tighten description 2. Add "Do NOT use for" cases 3. Make routing scenario-based 4. Move detail from SKILL.md to references/ 5. Replace repeated manual instructions with scripts/ 6. Split by platform or mode only when boundary tightening is not enough

Collection Pass Criteria

A repo skill collection is in good shape when:

• each skill has a distinct job and nearest-neighbor boundary
• descriptions are specific enough to drive correct triggering
• SKILL.md files are concise and behavior-first
• reference loading is explicit and shallow
• repeated logic is minimized
• audit findings can be explained with concrete file evidence

Structure Patterns

Purpose

Use this reference to design a maintainable, extensible skill structure with progressive disclosure. The goal is not just to make the content tidy, but to ensure the agent knows what to read, in what order, and when to stop loading context.

Skill Anatomy

A mature skill often looks like this:

skill-name/
├── SKILL.md
├── references/
│   ├── topic-a.md
│   └── topic-b.md
├── scripts/
│   └── helper.sh
└── assets/
    └── template.md

Responsibilities:

• SKILL.md
• Entry point for the skill
• Behavioral rules after trigger
• Routing and reading order
• Boundary and non-applicable scenarios
• references/
• Detailed methodology
• Platform, framework, or mode differences
• Long explanations, examples, and checklists
• scripts/
• Helper scripts that reduce repeated manual work
• Good for transformation, checking, or batch generation tasks
• assets/
• Templates, skeleton files, sample inputs, and static support files

Core Rule

The main SKILL.md should not become a complete manual. Its job is to:

• Explain what problem the skill solves
• Tell the agent what to do first after trigger
• Tell the agent when to load which references/
• Tell the agent when not to use the skill

In other words, SKILL.md should control agent behavior, not merely explain a topic.

Recommended Main Sections

Recommended sections for the main SKILL.md:

1. What this skill does 2. When to use this skill 3. Do NOT use for 4. How to use this skill (for a coding agent) 5. Routing 6. Quick workflow 7. Minimum self-check

Behavior First

The structure should answer behavioral questions before documentation questions:

• What is the first action after trigger?
• Under what conditions should the agent load references/?
• When should the agent stop loading more context?
• If a nearby scenario appears, should the agent switch skills or ask for clarification?

If the main file only lists topics but does not enforce behavior, the skill is still immature.

When to Split Files

Split content into references/, scripts/, or assets/ when:

• A topic needs to be read independently
• Different platforms, frameworks, or modes diverge significantly
• A template exceeds roughly 15-20 lines
• Multiple examples are needed to make the point
• Repeated steps could be automated with a script

Practical Thresholds

Useful default heuristics:

• When SKILL.md approaches 200 lines, evaluate whether to split
• When a single topic exceeds roughly 40-60 lines, prefer moving it into references/
• When you need more than two long templates, prefer assets/ or dedicated template files
• When the same action must be repeated, consider scripts/

These are not hard protocol rules, but they are good default thresholds for authoring.

What to Keep in the Main File

Keep in the main file:

• Skill positioning
• Boundary and non-boundary cases
• The action sequence after trigger
• Reading routes
• Minimum self-check

Avoid in the main file:

• Long background explanations
• Full multi-platform detail
• Long template bodies
• Large collections of examples and counterexamples
• Repeated steps that could be scripted

Routing Pattern

Do not just say "see another file." Say which scenario should read which file and why it should be read now.

Recommended pattern:

Progressive Disclosure

Recommended layering:

• Main SKILL.md: entry point, behavior rules, routing
• references/*.md: deep knowledge
• assets/: reusable templates and sample materials
• scripts/: executable helper capabilities

Principles:

• Read SKILL.md by default
• Load a reference file only when routing points to it
• Use scripts instead of writing long repeated instructions
• Use templates instead of regenerating structure from scratch

Smell Checks

These signs usually mean the structure needs to be redesigned:

• The main file reads like a full tutorial
• There are many references but no reading order
• The agent must read everything before it can act
• Rules for different scenarios conflict with one another
• Templates, examples, methodology, and FAQ are mixed together
• Scriptable work is still described as long manual instructions

Templates

New Skill Template

This is not just a document template. It is a template for how the agent should act after the skill triggers.

---
name: your-skill-name
description: Short domain or capability introduction. This skill should be used when users ask to ...
---

# Skill Title

One short paragraph explaining what this skill changes for the agent.

## What this skill does

- Defines the scope of the skill
- Explains the behavior the agent should adopt
- Points to deeper references only when needed

## When to use this skill

- Keep this section short
- Do not repeat the full trigger vocabulary already carried by `description`
- Use it to clarify boundaries, not replace `description`

## Do NOT use for

- Neighbor scenario 1
- Neighbor scenario 2

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

1. Identify whether the request matches the intended task class.
2. Apply the main operating rules from this file first.
3. Load additional references only if the current task requires them.
4. Stop loading more context once you have enough to act.

## Operating Rules

1. First action after trigger:
2. What to inspect before acting:
3. What must never be skipped:
4. When to load references:
5. When to stop and ask for clarification:

## Routing

| Task | Read | Why |
| --- | --- | --- |
| Scenario A | `references/reference-a.md` | Needed for ... |
| Scenario B | `references/reference-b.md` | Needed for ... |

## Quick workflow

1. Trigger recognition
2. Initial action
3. Reference loading if needed
4. Output generation
5. Self-check

## Minimum self-check

- Did the skill actually change agent behavior?
- Did I avoid loading unnecessary references?
- Did I stay within the intended boundary?

Existing Skill Review Template

Use this template to review an existing skill:

## Review Summary

- Current goal:
- Current trigger quality:
- Current behavior after trigger:
- Main overlap risks:
- Main structure issues:

## Frontmatter Findings

- Name issue:
- Description issue:
- Keyword gaps:
- Boundary issue:

## Behavior Findings

- What the agent should do but currently does not:
- What the agent does too early:
- What the agent loads unnecessarily:
- What the skill fails to enforce:

## Structure Findings

- What is too long:
- What should move to references:
- What should become a script or asset:
- What needs routing:

## Rewrite Plan

1. Tighten or broaden description
2. Clarify behavior after trigger
3. Split references or add scripts/assets
4. Add evaluation prompts and acceptance checks

Description Draft Template

<Product / domain intro>. This skill should be used when users ask to <task 1>, <task 2>, <task 3>, or when they need <neighbor phrase> in <platform or scenario>.

Notes:

• Put the main trigger information into description
• Use the body to enforce behavior after trigger
• Do not write the skill as a generic topic overview

Resource Split Template

If the skill becomes complex, split it into these roles:

• SKILL.md: entry point and behavior rules
• references/: deeper methodology
• assets/: templates and sample materials
• scripts/: executable helper capabilities

Authoring Checklist Template

- [ ] Name is short and intentional
- [ ] Description explains both capability and trigger
- [ ] The skill changes agent behavior after trigger
- [ ] The main SKILL.md is concise
- [ ] Routing only loads references when needed
- [ ] Reusable templates live in assets or dedicated files
- [ ] Repeated actions are moved into scripts when appropriate
- [ ] Evaluation prompts and acceptance criteria are present