Writing Skills

Writing skills

Reuse the existing owner

Inspect existing skill catalogs before creating a package. For repository work, search the target catalog and every relevant source catalog in the authorized workspace. For authorized live-library work, use Rundesk's catalog and skill listings; do not open the live library to bypass the task's access boundary. Read the descriptions of plausible matches, then their bodies and relevant references before deciding.

Extend the existing owner when the requested capability shares its user intent, workflow, and authority. Add a supporting script, reference, or test there instead of creating a second routing surface. Create a new skill only when the capability needs distinct routing, judgment, authority, or proof; record that distinction so a nearby name is not treated as justification by itself.

Choose the artifact

• A skill is the instruction boundary: when to act, what judgment to apply, which procedure to follow, and how to prove the outcome.
• A workflow script is the deterministic mechanism for repeated local transformation, validation, or orchestration.
• An integration adds an external-service boundary: credentials, accounts, network failures, permissions, or remote effects.

Keep one-off automation in its project and one agent's private repeated command in that agent's scripts area. Package a script in a skill only when future turns need routing or judgment to use it. Do not replace deterministic code with prose an agent must reinterpret.

Read Reusable workflow scripts before shipping any reusable script. Also read External-service integrations when it uses credentials, profiles, OAuth, a network, or remote effects.

Place it safely

Create a private skill in local only when live creation or installation is authorized. For a draft, review, repository change, or isolated test, stay in the named workspace or temporary directory; do not inspect or change the live library to discover where the result might later go.

For an authorized private skill, ask Rundesk for the library instead of deriving it from RUNDESK_HOME or embedding an absolute path. Replace the example name:

skill_name=release-notes
skill_library=$("$RUNDESK_COMMAND" skills | sed -n '1s/^skills in //p')
test -n "$skill_library" || exit 1
mkdir -p "$skill_library/local/$skill_name"

Write <library>/local/<name>/SKILL.md, then grant it to the named agent:

"$RUNDESK_COMMAND" skills grant "$RUNDESK_AGENT" local/release-notes

The grant becomes discoverable on the agent's next turn, not the current one. Read Publishing a skill catalog before creating a skill for other installs; published skills belong in a catalog repository, not local.

Use only the needed shape

<name>/
├── SKILL.md          required: routing and core procedure
├── rundesk.json      optional: required environment values
├── scripts/          optional: reusable commands
├── tests/            optional: script contracts when no catalog test area owns them
├── references/       optional: conditionally loaded detail
└── assets/           optional: copied or output material

Create optional paths only with content. Omit README, changelog, installation guide, and creation history.

Write routing first

Frontmatter has only name and description.

• Match name to the directory. Use at most 64 lowercase letters, digits, and single hyphens.
• Route by user intent, including indirect requests that may not name the skill. Start with Use when, Apply when, or equivalent applicability language; prompt phrases are not triggers.
• Aim for two short sentences: applicability, then the specialized workflow or knowledge supplied. Add Do not use only for a likely near-miss. Include only concepts needed to route before the body loads. Omit steps, tests, benefit claims, and implementation detail; name a file type, tool, or format only when it determines whether the skill should trigger.
• Use the shortest description that still routes correctly; 1,024 characters is a ceiling, not a target. Put every trigger there because each holder pays for it every turn and the body is unavailable until routing succeeds.

# Bad: embeds implementation and verification that cannot help routing.
description: Use when creating release notes. It reads Git history, writes Markdown, groups commits, checks links, runs validation, and produces concise internal and public versions with accurate formatting.

# Good: states intent, supplied judgment, and the closest boundary only.
description: Use when preparing release notes from shipped repository changes. It supplies an audience-focused workflow grounded in verified history. Do not use for unreleased plans.

Keep only behavioral guidance

Use imperative steps in execution order. Assume the reader can reason, edit, and use ordinary tools. Keep a sentence only when it changes execution, prevents a likely failure, or routes needed detail.

• Keep core procedure, one strong default, and non-obvious gotchas in SKILL.md.
• Use exact commands for fragile operations; use concise judgment where several approaches work.
• Explain the failure a constraint prevents instead of adding unexplained emphasis.
• Introduce each reference with when to read it. Keep one source of truth; link instead of restating.
• Remove background, process history, dated claims, and rules already loaded elsewhere.
• Distinguish observed contracts from recommended defaults. Source technical constraints, and teach real traps as symptom, cause, replacement, and observable proof.

Keep SKILL.md under 500 lines; move conditional detail one level into linked references.

Budget context

Prefer short examples. Bound script output to what the next decision needs.

Prove the whole skill

1. Validate directory name, frontmatter name, description syntax, and limits.

2. When a grant is needed, apply it and verify the next turn:

   "$RUNDESK_COMMAND" skills list "$RUNDESK_AGENT"
   "$RUNDESK_COMMAND" skills doctor "$RUNDESK_AGENT"
   

3. Run each script's reference-owned edge matrix and direct executable entry point.

4. In different fresh turns, try a direct request, an indirect request, and a close near-miss. Confirm the body and required references load before work; fix routing by category, not copied prompt phrases.

5. For a substantial skill, compare the same task with a fresh baseline without the skill. Then have a separate test agent use it without the expected implementation. Review artifacts and commands directly; the agent's summary is not proof. Remove guidance that earns no material improvement.

6. Review generated writing separately from executable correctness: routing precision, execution order, useful judgment, concision, duplication, and reference discipline. Green script tests do not prove writing quality. Source or observe factual promises; test executable claims and narrow partial truths. Challenge semantic claims with an adversarial counterexample that preserves convenient aggregates while changing the real relationship or outcome—mutation checks cannot repair a wrong test oracle. Review the whole interface, including empty success, duplicate evidence, and every data-dependent output section.