Maintain Orbyn skills

Read the consuming project's instructions and relevant guides in place. Use the portable policy and routing defaults only where guidance is missing. Inspect nearby skills before editing. Prefer improving the existing owner over creating a second skill that attracts the same requests.

Route from the user's natural-language request. Complete authorized ownership, authoring, migration, registration and validation steps without asking the user to invoke separate skills. Helper flags are an execution contract for the agent.

Choose the owner before authoring

Classify the request using the company/repository skill boundary. Consumer conventions and local adaptations stay in that consuming checkout's established paths under its own ownership and discovery rules, outside the shared catalog, public manifest and upstream lock. A library improvement must be explicitly in public contribution scope; never infer permission from generic wording or copy company material into the shared skill tree. For local skills, follow the consumer's authoring/discovery checks and the consumer notes. The steps below apply to library-owned skills.

Define a useful contract

Write the trigger, expected input, result and boundaries. Identify the applicable stack and role, the skills this one genuinely depends on, and its handoff. Use orbyn-research for unknown host/specification behavior, and confirm a tool exists here before relying on it. Make examples realistic to Orbyn's architecture.

Keep essential choices in SKILL.md; put conditional templates or deep guidance in linked references. Keep model/session/permission policy with its owner rather than repeating it in every skill. Name Orbyn-specific entrypoints orbyn-*. A decision principle normally belongs in an existing owner's entrypoint and conditional reference; a separate skill needs a distinct task trigger and useful result. Keep third-party attribution in source/provenance records, never as an inherited active agent identity. Keep essential instructions and required references usable from disk under the offline contract.

Author and integrate

Follow the authoring standard for the description, entrypoint order, prose, helper code and required cases. Its checked limits fail python3 scripts/check-library.py.

Use a matching folder/name with lowercase letters, digits and hyphens (under 64 characters), and concise name/description frontmatter. Keep the description on one line for the repository catalog generator. Describe actual routing, not a catchall. Include only resources needed to perform the task. Add no placeholder folders, mandatory panels or new approval flow without a reason.

Register the skill in skills/catalog.json with its category and maintainer-facing routing relationship. Update the owning task route in the workflow/system guide when needed. Use python3 scripts/sync-agent-skills.py --write to refresh the catalog index and host links; review its diff. Never overwrite unrelated host settings or install global skills/MCP providers as part of repository authoring.

For a rename or retirement, migrate incoming links and discovery paths first. Keep source-to-local attribution maps correct, and keep the provenance of every import. Update affected documentation and remove obsolete competing guidance.

Validate the whole path

Run python3 scripts/check-agent-assets.py and python3 scripts/sync-agent-skills.py --check. Check a few realistic routing cases: expected trigger, adjacent task that should not trigger, missing tools/evidence, and the downstream handoff. Check references and role/stack boundaries. Report metadata and routing inspection as static evidence, separate from live model behavior.

Use an available host skill validator for frontmatter when present. Execute new helper scripts in disposable scope and inspect their outputs. A live skill trial, external effect or product test still needs applicable authorization. Skip paid model panels for documentation validation.

Update an evaluation case when its contract changes, and never change frozen criteria after observing a held-out result. python3 skills/orbyn-skill-creator/scripts/evaluate.py validate checks the suite. Report checks actually performed, remaining behavior gaps, changed files and local/committed delivery state.

Read when the task needs it

• Offering a demonstrated reusable gap back to the library: contribution feedback.
• A selected remembered lesson: memory-to-skill handoff.
• A durable project check of a critical behavioral property: project verification.
• Positive, adjacent, no-skill and outcome cases, or a claimed improvement: evaluation guide.
• An explicitly requested reproduce/fix/PR-feedback execution trial: disposable contribution lab.
• Explicitly requested multi-suite CI or release/capacity exercises: disposable pipeline method.
• External skill freshness and source comparisons: upstream review.
• A full sweep, SOURCE.md text, a rewritten derived skill, consolidation or the public contract: library maintenance.
• A shared edit before release: release handoff.