Agent Skill authoring guide

Use this guide when you are a CLI or MCP agent asked to create, import, or revise a Skill.

First, check what already exists

Do not create a duplicate procedure. Before authoring:

1. Read agent-reference-map. 2. Run skill.list / rost_list_skills and search by the job words. 3. If the procedure may be first-party, run skill.catalog / rost_list_rost_skill_catalog. 4. Read matching descriptors with skill.get and the full file with skill.file.get.

If an existing Skill is close, propose an update draft or assignment instead of a new Skill.

Decide whether a Skill is appropriate

Create a Skill for repeatable procedures, domain-specific output contracts, local/client setup patterns, reusable examples, and company operating standards.

Do not create a Skill for:

• Authorization or tool access.
• Secrets, credentials, API keys, or vault refs.
• One-off evidence that belongs on the task.
• Temporary style preferences.
• Charter rules, escalation boundaries, or human decision policy.

If the user asks for authority, update the Charter path. If the user gives one-off evidence, keep it in the task context.

Authoring checklist

The SKILL.md body should be short, procedural, and testable. Include:

• A clear title.
• An application.summary that says when to use it.
• application.not_for for risky or out-of-scope cases.
• Required and optional tools only when the procedure genuinely needs them.
• An output contract when consistency matters.
• Missing-evidence behavior: state what is missing instead of guessing.

Use tool.catalog before naming a tool. Required tool scope tiers must be the minimum useful scope. Optional tools are for improved delivery, not hidden blockers.

Safe command path

• Draft: skill.create or skill.update_draft.
• Public GitHub import: skill.import_github with the URL, ref, and package path.
• Uploaded text import: skill.import_upload.
• Publish: skill.publish returns a human confirmation. Stop and ask the human to approve or reject.

Never approve your own publication. Never paste secrets into SKILL.md, support files, command JSON, issue comments, or logs.

Quality bar

Before handing off, say what the Skill is for, why it is reusable, what tools it depends on, and what human gate remains. If validation warnings exist, fix them or call them out as blockers.