orbyn-skill-creator

Files (7)

• LICENSE
• SKILL.md
• 2026-10-24-55-skills.json · evals/baselines/
• cases.json · evals/
• evaluations.md · references/
• check_sources.py · scripts/
• evaluate.py · scripts/

SKILL.md (first lines)

# Maintain Orbyn skills

Read the consuming project's instructions and relevant guides in place. Use the
[portable policy and routing defaults](../orbyn-workflow/references/project-policy.md)
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;
they are not mandatory manual homework for the user.

## Choose the owner before authoring

Classify the request using the [company/repository skill boundary](../orbyn-setup/references/project-skills.md).
Consumer conventions and local adaptations stay in that consuming checkout's
established paths under its own ownership and discovery rules. Inspect existing
local skills and preserve credits/assets. Setup does not move, namespace, register
or synchronize target guidance. Creating a local skill is separate authorized
project work; do not invent a shared registration or migration helper. Keep it out of
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.

The shared authoring steps below apply to library-owned skills. For local skills,
follow the consumer's authoring/discovery checks and the ownership guide.

For a durable project check of a critical behavioral property, use the
[project verification method](references/project-verification.md). Keep its
models, coverage record and rerun instructions with the target owner, outside
the shared catalog. A generic prototype request does not require a new skill.

## 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; do not assume tools from
another product exist here. Make examples realistic to Orbyn's architecture.

Keep essential choices in `SKILL.md`; put conditional templates or deep guidance
in linked references. Do not duplicate model/session/permission policy 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](../orbyn-setup/references/offline.md). Bundle licensed, pinned
source text when it is needed; keep attribution/update URLs and source hashes.
For sources without redistribution permission, author the needed explanation
independently and label the remaining evidence limits.

## Author and integrate

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. Do not add
placeholder folders, mandatory panels or a 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; do not delete provenance to hide
an 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. Metadata
and routing inspection are static evidence, not proof of 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. Avoid a
paid model panel just to validate documentation. Report checks actually performed,
remaining behavior gaps, changed files and local/committed delivery state.

## Maintain the public contract

When current work demonstrates a meaningful reusable gap, use the
[contribution feedback policy](references/contribution-feedback.md). Prepare a
concrete, sanitized proposal and offer it once at a natural checkpoint. The user
can approve a public PR, request a local draft or decline. Existing exact-scope
authority carries through. Silence and local improvement permission do not
authorize publication. Keep company-only lessons local and continue the main task.

Treat the shared library as an upstream dependency of consuming projects. Keep private product policy and source outside public contributions. A useful skill change alters a decision or supplies a reusable artifact, not just vocabulary. Check expected and adjacent routing cases, then reconcile the catalog and library release through the documented contribution path.

For external skill freshness and source comparisons, use
[upstream review](../orbyn-upstream-review/SKILL.md). Keep downloaded research in
ignored `orbyn-references/`, preserve existing local references and adopt selected
improvements into the owning skill. Do not replace our adaptations with an
upstream collection or advance an import pin after a review-only change.

## Evaluate a change

For an explicitly selected remembered lesson, use the
[memory-to-skill handoff](references/memory-learning.md): freeze source revisions,
write the general correction and synthetic counterexample, and prepare only the
reviewed owner patch. Keep private records outside Git. Manual/local and optional
fork-branch delivery reuse the same checks and authorization; neither implies
automatic learning, acceptance or an upstream PR.

Use the [evaluation guide](references/evaluations.md) and its versioned suite for
positive, adjacent, no-skill and outcome cases. Update a case when its contract
changes; do not change frozen criteria after observing a held-out result.
`python3 skills/orbyn-skill-creator/scripts/evaluate.py validate` checks the suite.
Prepared or incomplete trials remain unverified. Helper fixtures test the tooling;
only captured, reviewed host trials provide evidence of skill behavior. Record
baseline and candidate results separately before claiming an improvement.
For an explicitly requested reproduce/fix/PR-feedback execution trial, use the

From kinqsradio/orbyn-fullstack-skills, MIT.

More from kinqsradio/orbyn-fullstack-skills