Authoring guidance
What decides whether a Cmdop Skill gets used is its description: write it as a trigger naming the situation, not as a summary of the subject. Then keep the Skill to one job, be specific about which commands to run and what not to do, generate the project rather than copying a template, and validate strictly.
A Skill competes for the agent’s attention with everything else it could do. These are the habits that decide whether yours gets picked up and whether it works when it is.
Write the description as a trigger
The description is not a summary — it is how the agent decides when to reach for this Skill. Write the situation, not the subject.
- ✅ “Use before tagging a release, to check that the changelog, version, and open blockers agree.”
- ❌ “Release checking utility.”
A description that names when is the single highest-leverage thing in the project.
Be specific in the instructions
Vague instructions produce vague behavior. Say which commands to run, which files to look at, and what a good answer looks like. State the things the agent should not do just as explicitly — a Skill that reads without changing anything should say so.
Keep the project small
One Skill, one job. A Skill that tries to cover a whole workflow is harder to trigger correctly than three that each do one thing. Keep declared files and dependencies to what the Skill actually needs; every extra one is something the validator has to accept and a reviewer has to read.
Start from the generator
cmdop skill create my-skill --description "..."A generated project matches the validator in your installed version. A project copied from an older template may not, and the failure shows up at pack time.
Validate strictly, early
cmdop skill check ./my-skill --strictPacking requires a warning-free strict check, so run it that way from the beginning rather than discovering the same warnings later.
Do not expect authoring to run anything
create, check, and pack never execute your Skill. If you want to know
whether the instructions work, install it and run it — validation checks the
declared contract, not the behavior.
Related
Common questions
How do I make a Skill more likely to be used?
Write the description as a trigger that names the situation where the Skill should apply. The description is how the agent decides when to reach for it.
How specific should Skill instructions be?
Specific enough that a reviewer can tell what the agent will do: commands to run, files to inspect, expected output, and actions the agent must not take.
Should one Skill cover a whole workflow?
Usually no. Keep one Skill focused on one job. Several narrow Skills are easier to trigger, validate, review, and maintain than one broad workflow Skill.
Cmdop