Skill Design

Communication kernel

Number ordered actions; group long lists without hiding required items. After interruption or task change, restore relevant completed/current/pending state, not repetitive status each turn. Preserve language, exact tokens, formats, permissions and evidence. Never invent estimates or diagnose readers. Show verified outcomes and factual errors; give a concrete next action only if work remains. Use ASD-STE100-inspired short, active technical sentences. Use ISO 704-inspired stable concepts and terminology. Use Diátaxis to separate how-to, reference, and explanation when useful. These are communication guides, not claims of formal standards conformance. If trusted root AGENTS.md is loaded, its policy governs. Otherwise apply this standalone kernel. Do not claim root activation without evidence.

Import

1. Inspect source, revision, license, trigger, files, tool assumptions, network use, state mutation, executable code, hooks, installers, automatic updates, permissions, and actual behavior. For tool selection, apply ISO/IEC 20741-inspired tool selection. Start with requirements and measured trials, not reputation or feature count.
2. Distinguish a skill, which changes agent behavior, from a runtime, which adds execution capability. Adopt a runtime separately only when the capability is real, needed, pinned, reviewable, and cannot be reproduced safely with existing host tools.
3. Prefer a disposable project-local prompt, script, checker, or simulator to a global skill when the need is task-specific.
4. Adopt a separate skill only when it has a distinct leading action and independent trigger.
5. Absorb useful precise rules into an existing skill or conditional reference when workflows overlap.
6. Reject provider wrappers, session-start routers, automatic trusted-file mutation, duplicate doctrine, promotion, arbitrary gates, unreviewed dynamic code execution, and infrastructure whose risk and cost exceed its behavioral value.

Stack and route

1. Choose one primary task skill. Add support only for a distinct scope, execution, context or assurance responsibility. Resolve lifecycle ownership by explicit user designation, otherwise selected get-it-done, otherwise the unique substantive task skill. Stop affected actions if ownership remains ambiguous or the owner is not available, selected and loaded. Do not preload or chain a catalog by default. Alone, the selected skill retains its normal ownership.
   • Scope modifiers cannot weaken mandatory safety, trusted policy, authorization or acceptance. Capability executors own their evidence; assurance retains independent failed verdicts. Supporters do not issue final task status. The owner reports evidence and failures once; failed or missing required evidence prevents accepted completion. Presentation changes no facts, permissions or verdicts.
   • Standalone folders must carry these fallbacks without sibling or root dependencies. Unavailable required support blocks dependent acceptance; do not silently skip it.
2. For a stack or runtime, record exact IDs, source revision or digest, host and scope, purpose, overlap decision, permissions, executable surfaces, update behavior, and rollback.
   • For a standard, record version, status, official source, review date, Lean home, and next review trigger.
   • Preview before you apply changes.
   • Structural validity does not prove semantic fit, safety, or conformance.
   • Read PLAYBOOKS.md when needed.

Write or refactor

1. Inspect existing formats, names, references and host constraints. Name the result, next consumer, observable completion and non-obvious intent. Write short, active decisions. Important requirements name one actor and verifiable action. Distinguish invariants, defaults and heuristics; do not make every preference mandatory.
2. Treat skill merges as behavioural changes.
   • Before merging skills that co-activate or differ mainly by tone, depth, style, checklist, standard or orchestration branding, compare their contracts. Check triggers, mandates, references, standalone entry points, authority and completion rules.
   • Merge only within authorised scope after required preservation checks pass.
3. Treat descriptions as routing interfaces and permanent context costs. State action, trigger and expensive anti-trigger, not the whole workflow.
4. Keep SKILL.md complete and easy to execute.
   • Reduce avoidable wording, not required decisions.
   • Move conditional detail to a local reference only when the task trigger reliably loads it before it is needed. Measure claimed context savings in the actual loaded task.
   • Include every required reference inside a standalone skill's directory. Do not make root doctrine a hidden dependency.
5. A cross-cutting mandate that must survive explicit skill selection MUST NOT depend only on another skill loading with it. Put the smallest sufficient fallback in the selected skill or a trusted host-level policy.
6. Describe capabilities in the neutral skill. Put thin host adapters beside it.
7. Include completion, permission, and failure rules only when they change execution. Map every MUST to observable behavior, a check, a tool affordance, or an explicit decision rule. Remove motivational rules that the environment cannot evaluate.
8. Remove promotional filler, fake-tool claims, and facts that the environment can reveal directly.
   • Before removing a wrapper, alias, or reading-list entry, establish its purpose and dependencies.
   • Retain every entry that carries a required rule, supported capability, source reference, or standalone loading path. Propose any behavioral removal separately.

Evaluate and package

Use PLAYBOOKS.md for structural, routing, behavioral, workflow-topology, trusted-refinement, and runtime-safety tests; objective assertions; cost measurement; adapters; manifests; path checks; and clean extraction.

• For user-facing skills, include short-answer, procedure, error/recovery, interruption/reorientation, target-user, and over-simplification cases. Readability alone does not provide task evidence.
• Trusted doctrine MUST NOT self-modify during ordinary task execution.
• A proposed refinement needs a baseline, held-out or adversarial cases, a reviewed diff, explicit authorization, and rollback.
• Add words or infrastructure only when observed behavior justifies them. Use the fewest durable words that preserve the skill's complete behavioral contract. Keep triggers, required actions, exceptions, evidence, and recovery.
• Make workflow mechanics deterministic. Do not hide cost, failure, or permission.
• Neither a skill nor a workflow should simulate authority or promise capabilities that the host lacks.

Preservation-first instruction editing

Before rewriting agent-facing rules or user-facing delivery guidance, read INSTRUCTION-EDITING.md. Preserve the task contract and loading paths before reducing wording. A compact replacement must still name the applicable trigger, action, exception, evidence, and failure response. Compare old and proposed instructions in both directions. Keep standards-register decisions, source links, named resources, and local fallbacks available at entry points that need them. Treat changes to descriptions, aliases, controller topology, invocation policy, and completion criteria as separate behavioral changes. Do not treat them as automatic results of a prose edit. User-facing:

• Lead with the supported result, action or blocker. Report fresh verification, material uncertainty and remaining user action. Omit routine tool narration and praise.
• Apply the communication kernel and familiar words. State verified failure and evidenced responsibility directly. Correct actual agent errors or give the next safe action.
• Preserve facts, negation, uncertainty, evidence limits, permissions, quotations, requested voice and exact artefact formats. Style does not prove formal conformance.
• Use BCP 14 only for normative force. Important requirements name one actor, action and observable check; do not turn advice into mandates.
• Before risky or failure-prone work, warn, add any needed hold point and verify the safe state. State the expected result, failure sign and recovery. Explain difficult mechanisms simply; use compliant/noncompliant contrasts only when useful.
• For measurable multi-step work with a defensible total, show named 20-cell ASCII progress, rounded down from processed items, separately from the verdict. Processed does not mean passed. Otherwise report phase and evidence.
• Avoid surprise scope; leave results usable or resumable. Keep simple replies short without truncating needed detail. Omit routine Summary headings and closing recaps. Use TL;DR only when helpful for a complex response, and place it first.