studio-assistant-skill-creator-guide

name	studio-assistant-skill-creator-guide
description	Helps the APM Studio Assistant create or extend Skills in an app-safe way. Use when the user wants a new Skill, a better SKILL.md, extra references or scripts, tighter trigger wording, or agents/openai.yaml metadata inside a Skill draft folder.
compatibility	Designed for the APM Studio built-in assistant projection.

APM Studio Skill Creator

Use this skill when the user wants to build a Skill through APM Assistant.

Studio-safe authoring model

• Use createSkillDraft or updateSkillDraft only for SKILL.md.
• Use upsertSkillBundleFile for sibling files such as references/*.md, scripts/*, assets/*, and agents/openai.yaml.
• Use deleteSkillBundleEntry only for non-core bundle entries.
• Never target SKILL.md or draft.json with bundle file actions.
• Bundle file actions only work on saved Skill drafts.
• Use stable, human-readable bundle paths. Do not add random, hash, timestamp, or cache-busting suffixes to assets/*, references/*, or scripts/* filenames unless the user explicitly asks for versioned files.

Recommended Skill Shape

• Keep SKILL.md concise and procedural.
• Put detailed examples or schemas in references/.
• Put deterministic helpers in scripts/ only when they meaningfully reduce ambiguity or repetition.
• Create agents/openai.yaml only when the user wants the Skill to expose polished UI metadata.
• For non-trivial Studio mutations, keep dependent actions in one dependency-ordered apply_studio_actions call.
• Do not create clutter files such as README.md, CHANGELOG.md, or QUICK_REFERENCE.md unless the user explicitly asked for them.

Skill-writing heuristics

• The frontmatter name should stay stable and slug-like.
• The frontmatter description should say what the skill helps with and when it should be used. That text strongly affects whether the skill triggers.
• Keep the body focused on workflow and decision rules, not general motivation.
• If the skill supports multiple variants, keep selection guidance in SKILL.md and move variant details into separate references/ files.
• Prefer a few high-signal files over a wide scaffold.
• When improving an existing Skill, update the same stable bundle files instead of creating suffixed variants.
• Read references/bundle-authoring.md when you need a quick reminder of what belongs in SKILL.md vs sibling files.

Assistant behavior

• If the user wants a new Skill, prefer createSkillDraft first and give it a same-call ref.
• When you need extra bundle files in the same reply, reuse that draftRef.
• If the correct bundle path is unclear, ask a short clarifying question instead of guessing.
• Treat invalid mutation payloads as blockers. Fix ref ordering, draft-ref kind mismatches, and disconnected multi-participant createTeam payloads before calling the tool.
• If the user wants to improve an existing Skill, prefer updating the current draft and bundle files instead of creating a second overlapping Skill.
• When the user asks for an "enhanced" Skill, improve both triggerability and authoring quality: frontmatter, workflow instructions, and the right supporting files.

Example

{"version":1,"actions":[{"type":"createSkillDraft","ref":"research-skill","name":"Research Skill","content":"---\nname: research-skill\ndescription: Research workflow helpers.\n---\n\n# Research Skill\n\nUse this skill for focused research tasks."},{"type":"upsertSkillBundleFile","draftRef":"research-skill","path":"references/sources.md","content":"# Sources\n\nList trusted source types here."},{"type":"upsertSkillBundleFile","draftRef":"research-skill","path":"agents/openai.yaml",