xonika9/agent-skills / skills/x9-onboarding
x9-onboarding
VerifiedUse after installing or updating `x9-*` skills to check their readiness and compare the current harness with the bundled x9 configuration profile — «проверь готовность x9-скиллов», «настрой Codex как у автора», "check installed x9 skills", "apply the recommended harness settings". Do not use for general environment diagnosis, account authorization, or unrelated configuration editing.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
| profiles/claude.json | config | 496 B |
| profiles/codex.toml | config | 627 B |
| profiles/opencode.json | config | 3.5 KB |
| references/claude-code.md | markdown | 1.3 KB |
| references/codex.md | markdown | 1.1 KB |
| references/configuration.md | markdown | 5.6 KB |
| references/declarations.md | markdown | 8.0 KB |
| references/onboarding.json | config | 367 B |
| references/opencode.md | markdown | 1.4 KB |
| scripts/aggregate_status.py | script | 7.7 KB |
| scripts/test_aggregate_status.py | script | 10.2 KB |
| scripts/test_validate_onboarding.py | script | 21.3 KB |
| scripts/test_validate_profiles.py | script | 6.5 KB |
| scripts/validate_onboarding.py | script | 19.2 KB |
| scripts/validate_profiles.py | script | 11.6 KB |
references/declarations.md
View on GitHub# Onboarding Declarations
## Contents
- [Version 1 Shape](#version-1-shape)
- [Alternative Routes](#alternative-routes)
- [Typed Checks](#typed-checks)
- [Runtime Checks and Guidance](#runtime-checks-and-guidance)
- [Safety Boundary](#safety-boundary)
`references/onboarding.json` is a version 1, read-only declaration of external
requirements for its owning skill. It is data, not an instruction: the
declaration cannot contain commands to run, arguments, URLs, paths, secrets, or
free-form setup steps. A skill runs in every runtime unless its declaration
restricts it, so a skill without external requirements or a runtime
restriction has no declaration.
Resolve the loaded `x9-onboarding` directory from its loaded `SKILL.md`. The `skills`
root to validate is the loaded skill's package root; use another package's root only when
the user explicitly asks to validate that package. Neither path depends on the current
working directory. Then run:
```bash
python3 <resolved-x9-onboarding-directory>/scripts/validate_onboarding.py \
<absolute-target-package-skills-root>
```
The validator reads only immediate `skills/*/references/onboarding.json` files.
It reports every violation as `skill/references/onboarding.json: field.path:`
and exits nonzero. A successful check prints `PASS` and the declaration-file
count.
## Version 1 Shape
The top-level object has `version` and `requirements`, plus optional
`supported_runtimes`:
```json
{
"version": 1,
"requirements": [
{
"id": "command-line-tool",
"runtimes": ["opencode"],
"kind": "command",
"level": "required",
"needed_for": "Checking the local command line tool.",
"check": {"type": "command-present", "command": "toolctl"},
"guidance_id": "install-command"
}
]
}
```
`supported_runtimes` appears only when the owning skill is restricted by design
to a subset of runtimes. It is a non-empty, proper subset of `opencode`,
`claude`, and `codex`; listing all three is an error because omission already
means every runtime. A restriction is also stated in the skill's `description`,
because runtimes decide whether to load a skill from its metadata.
`requirements` is an array. It may be empty only when `supported_runtimes` is
present; never invent a requirement to fill it. Each requirement has `id`,
`kind`, `level`, `needed_for`, `check`, and `guidance_id`, plus optional
`runtimes` and `group`. Omit `runtimes` when the requirement applies in every
runtime the skill supports; list them only when it applies in fewer.
Requirement IDs are unique inside their declaration.
- `id` and `guidance_id` use lowercase hyphen-case: a letter followed by
lowercase letters, digits, and single hyphen-separated segments.
- `runtimes`, when present, is a non-empty array drawn from the skill's
supported runtimes and is smaller than that set.
- `kind` is one of `skill`, `command`, `agent`, `mcp`, `runtime-feature`, or
`user-action`.
- `level` is `required` or `optional`.
- `needed_for` is one non-empty, trimmed display string of at most 160
characters. It permits letters, digits, spaces, and only `, . : ! ? ( ) '
-` punctuation. It does not control behavior.
Every object is closed. Unknown fields and wrong JSON types are errors.
## Alternative Routes
Use the same lowercase hyphen-case `group` on two or more requirements when
any one route satisfies one required capability. Every member is `required`
and uses the same `runtimes`; individual rows stay visible, but readiness is
computed once for the group. The exhaustive group and skill aggregation rules,
including the ready-route short circuit and optional-row coverage, are owned by
`scripts/aggregate_status.py` and its regression tests.
## Typed Checks
`check` is a closed discriminated object with a `type` field. It has no optional
or shared extra fields.
| Requirement kind | Check object | Required guidance |
| --- | --- | --- |
| `skill` | `{"type":"skill-present","target_skill":"x9-example"}` | `install-skill` |
| `command` | `{"type":"command-present","command":"toolctl"}` | `install-command` |
| `command` | `{"type":"command-version","command":"python3","min_version":"3.11"}` | `install-command` |
| `agent` | `{"type":"runtime-component","component_id":"codex:codex-rescue"}` | `create-agent` |
| `mcp` | `{"type":"runtime-component","component_id":"chrome-devtools"}` | `configure-mcp` |
| `runtime-feature` | `{"type":"runtime-feature","feature_id":"active-skill-catalog"}` | `enable-runtime-feature` |
| `user-action` | `{"type":"manual"}` | `complete-user-action` |
`target_skill` must be an `x9-` lowercase hyphen-case name and must name an
existing directory immediately below the supplied `skills` root. `command` is
one executable name only, without a path, whitespace, or arguments.
`command-version` sets a minimum version for a command from the validator's
allowlist, currently `python3` only, and `min_version` is a dotted numeric
version such as `3.11`. After `command -v` finds the command, the adapter may
run exactly `<command> --version` and retain only the parsed version and
whether it meets the minimum. A missing command or an older version is an
absent fact; output that does not parse is unavailable evidence.
`component_id` names the exact entry expected in the runtime's live catalog. It
uses lowercase letters and digits separated by `.`, `:`, or `-`; `kind`
determines whether that entry is an agent or MCP component. The runtime-feature
allowlist is `active-skill-catalog`, `browser-control`, `native-subagents`.
The table above is also the complete `guidance_id` allowlist. New identifiers
require an explicit contract update to this document and the validator; a local
declaration cannot invent them.
## Runtime Checks and Guidance
Every runtime adapter applies these rules; an adapter states only what differs in its
runtime.
For `skill-present`, accept only a live catalog entry whose resolved physical path
remains under the package `skills` root. For `command-present`, a safe shell discovery
such as `command -v` may establish presence without launching the command; retain only
its name and present/absent result. For `command-version`, follow
[Typed Checks](#typed-checks). Check `agent`, `mcp`, `active-skill-catalog`, and
`native-subagents` only through a live catalog or schema. Classify unavailable
interfaces, private-data boundaries, and restart evidence with the
[core status model](../SKILL.md#status-model). Dependency checks do not inspect raw
configuration.
Each row that needs guidance shows the step for its `guidance_id`, with `<runtime>`
replaced by the current runtime's name:
| `guidance_id` | Manual step | Expected safe evidence |
| --- | --- | --- |
| `install-skill` | Install or update the named skill using `<runtime>`'s current documented flow. | Live skill catalog lists the named skill. |
| `install-command` | Install the named command using its vendor documentation. | Safe command discovery reports the command present. |
| `create-agent` | Create or enable the required agent through `<runtime>`'s current interface. | Live agent catalog lists the declared component. |
| `configure-mcp` | Configure the required MCP component manually through `<runtime>`'s documented interface. | Live component catalog lists MCP without exposing configuration. |
| `enable-runtime-feature` | Enable the declared `<runtime>` feature through its current documented interface. | Live catalog or schema exposes the feature. |
| `complete-user-action` | Complete the declared authorization, profile, provider, or other human-only action outside this skill. | User confirms completion, then a safe follow-up fact is available. |
## Safety Boundary
The validator rejects URLs, absolute and relative paths, shell syntax,
control characters, secret-like field names, and secret-like values everywhere
in a declaration. Skill directories, `references` directories, declaration files,
and referenced companion skills must not be symbolic links; the validator never
reads a declaration through one. It also rejects an unsafe value even when it appears in an
otherwise known field. No code in this format executes declarations or treats
their display text as an action.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |