Skill authoring
Create or improve a reusable agent skill that activates for the right requests and reliably produces the intended result. Use this for SKILL.md packages and ChiefOS library skills. Start with the user's real outcome, not the source repository's folder structure. Do the work with available evidence; ask only for a decision-critical missing fact.
Activation and boundary
Use this method when creating, importing, rewriting, evaluating, or revising a skill, its description, resources, or behavior. Do not use it for a one-off answer that will not become reusable. First compare nearby library skills and their descriptions. Prefer improving a close existing skill over adding a near duplicate. Identify 2–3 requests that should activate it and at least one plausible near miss that should not.
Before writing, decide the right surface: - A skill holds task-specific reusable judgment and workflow. - Global instructions hold behavior that must apply to nearly every task. - An MCP connection or other integration supplies live data, permissions, and executable operations. - A script supplies deterministic repeated computation; an agent or managed workflow owns long-running state and external side effects. A skill cannot grant a tool, API key, authorization, browser, or live data merely by naming one.
First move
Write a one-sentence outcome and a trigger contract: what the skill does, when it activates, and its closest boundary. State the required input, intended output, and how success will be checked. If the request is a generic starter, give a minimal copy-ready SKILL.md and optional eval examples immediately; do not force a domain interview.
Build the package
- Inspect the current skill and adjacent skills. For an upstream import, inspect its SKILL.md, referenced files, scripts, license, and actual tool/API dependencies. Preserve useful source behavior and provenance; never silently drop a dependency or claim a vendor integration works after only copying instructions. Check rights before copying text. If verbatim reuse has licensing obligations, keep that source and license explicit; otherwise write an original adaptation.
- Draft the description for discovery: name the outcome and concrete use cases in the words a person would ask. Add a disambiguator when neighboring skills overlap. Avoid a long step list or generic claims in the description. Test it against both an in-scope prompt and a near miss.
- Put the operational path in SKILL.md: first action, necessary inputs, ordered decisions, evidence rules, output contract, validation, failure recovery, and permission boundaries. Make the next action obvious. Use supplied context before asking for missing facts; do not make routine clarification a blocker.
- Keep the main skill focused. Put deep reference material, schemas, worked examples, and templates in purpose-named resource files with explicit load conditions. Add scripts only when they remove repeated fragile work and the runtime can execute them. Every referenced path must exist and be retrievable. Do not create placeholder or orphan files.
- Declare each actual tool/API capability and whether it is required. Specify an honest useful fallback where possible. If the primary promised outcome is impossible without that capability, say so and do not label the package ready for that outcome. Separate local host operations from ChiefOS-managed operations.
- Preserve existing version, aliases, relationships, and valid behavior when updating. Link a neighboring skill only when composition has a concrete condition. Do not force every skill through a fixed graph path.
- Write a compact quality plan before submission. Include normal, ambiguous or missing-input, near-miss/false-trigger, unavailable-tool, and high-risk boundary cases when applicable. Expected behavior must be observable. Do not weaken a failing case to get a pass.
Pressure-test before submission
Challenge the proposed skill as if a skeptical user and a limited host will use it. Check: Can the description select it without reading the body? Does it overlap another skill? Does any step assume access, credentials, files, or current facts that are absent? Would it overclaim completion? Are approval boundaries explicit? Can a nontechnical user complete the intended workflow? Repair those gaps before submission.
Use the ChiefOS pressure-test skill for an interactive one-question-at-a-time challenge when the user asks to be grilled or a material product decision remains unresolved. Do not start that interview merely because a skill is being authored; it would interrupt an authorized create or update. For routine authoring, apply the same adversarial thinking internally and continue.
Validate and publish
Run available mechanical checks for metadata, resource paths, and schema. Exercise trigger and near-miss prompts, then inspect the output against the success criteria. For ChiefOS contributions, call get_execution_capabilities, then create_skill or update_skill with the full package, real tool requirements, resources, and evaluation scenarios. Submission starts an automatic read-only behavioral evaluation; it is not publication. Wait for the contribution result. On a blocked result, inspect failed checks and revise the same draft without weakening scenarios. Retrieve the published revision before claiming the skill is live.
The automatic evaluator can test reasoning and honesty using supplied evidence. It cannot perform live searches, execute scripts, render files, or prove an integration works. Run those checks in a capable host before claiming production readiness. When an external service is required, test the real connection and user journey separately.
Final review
Confirm the trigger, route-away, first move, resources, dependencies, output, safety boundary, and tests all agree. Report what was actually created or revised, what evaluation passed, and any untested live capability. Never present authored scenarios as executed tests or a draft as a published skill.