Imported from pixeloven/crew (skills/onboarding/SKILL.md). Install upstream with npx skills add pixeloven/crew --skill onboarding. Copyright stays with the author.

Onboarding

harmony-crew is an opinionated foundation — like the Karpathy guidelines, it takes a stance on how agents should work, and this skill shapes a project to match it. It generates an AGENTS.md for a new project, audits and refactors an existing one, and is meant to be re-run as the project grows so the entry files don't drift back toward fact-stuffing.

The foundation publishes to three harnesses (Claude Code, pi.dev, OpenAI Codex). Onboarding is mainly about the harnesses driven by an AGENTS.md — Claude Code and pi.dev (crew roles + skills) and Codex (same AGENTS.md read natively, full skill catalog, and its own subagent dispatch — it delegates when the routing table instructs it to). If the project also runs OpenClaw agents, they consume a skill slice (not roles, not AGENTS.md); onboarding's job there is narrower — flag that the gateway must wire the consumption-slice install (see step 5).

The stance (what "good" looks like)

1. Entry files drive behavior; skills carry facts. AGENTS.md / CLAUDE.md hold behavior — delegation, routing, posture, planning, memory, the platform↔local bridge, tripwires, fallback. Infrastructure facts, conventions, credentials, and command catalogs belong in local skills (.agents/skills/). A fact sitting in the entry file is a bug to fix.
2. Delegate by default to the foundation's roles — lead, triage, investigator, researcher, implementer, reviewer, responder. The entry file's routing table is what makes delegation automatic instead of an afterthought.
3. Merge-don't-replace. The foundation supplies the behavioral spine; the project fills only its specifics (ask-list, tripwires, local-skills map, verification commands, repo). The canonical shape is templates/AGENTS.md.
4. Trigger vs detail. A silent landmine's trigger lives always-on (a Tripwire line + an imperative skill description); its detail lives in the skill, loaded on demand. Never duplicate the detail into the entry file.
5. Reach for the platform first; degrade only on a real failure. Agents use the corpus / gateway / cluster as the default path and fall back gracefully once a call actually fails (the Fallback section). Onboarding delivers value before the platform is wired, and never assumes a capability is absent without checking.

Procedure

1. Assess — run the doctor

• Is the foundation installed? (.claude/settings.json plugin entry / .pi/settings.json package / Codex's .agents/skills or ~/.agents/skills catalog copy.) If not, point the operator at the per-harness quickstart (docs/quickstart-claude-code.md / docs/quickstart-pi.md / docs/quickstart-codex.md) first.
• Run the doctor skill's checks — installation, entry file, capability probe, local slots. Its closing profile (portable / platform / personas) drives the rest of this procedure.
• Inventory the entry files: is there an AGENTS.md? a CLAUDE.md? Read what's in them.
• Note what the foundation offers that the project isn't using yet — the 7 shared roles, the platform skills.

2a. New project (no AGENTS.md) → generate

• Start from templates/AGENTS.md.

• Fill what you can infer from the repo: verification commands (package.json / pyproject.toml / Makefile), the remote URL (git remote), the stack. Leave the judgment slots (ask-list, tripwires, local-skills map) marked for the operator with concrete suggestions, not blanks.

• Do not write a skills index. The harness lists every installed skill with its description before the first turn — that listing is how agents discover skills, and a hand-written catalogue in AGENTS.md only adds a copy that goes stale. Write the concern → local-skill mapping instead: which local skill owns topology, conventions, seams, access. That encodes a judgement the descriptions can't make.

• Decide scope before installing anything. A capability applied to THE WORK (agent methodology, a memory substrate, a design language) goes to USER scope — it is wanted in every repo and knows nothing about any of them. Knowledge about a SPECIFIC ARTIFACT FORMAT goes to the project. A project settings file should name only what is specific to that project; restating a universal is how one stale version ends up registered three times. Do not declare the same plugin at both.

• Lay every local skill out once, in .agents/skills/<name>/SKILL.md. pi and Codex read that natively; Claude Code needs ln -s ../../.agents/skills/<name> .claude/skills/<name>, and requires the directory form — a flat .claude/skills/<name>.md is invisible to it with no error. Confirm by starting the harness (claude -p in a separate process; codex debug prompt-input), never by looking at the tree: the tree looks right in exactly the case that fails.

• Let the doctor's profile shape what you recommend, not what you index. For a portable project don't propose capability skills whose tools the probe couldn't reach — that's an instruction the agent can't follow. If a probe fails, confirm the capability is genuinely ungranted rather than transiently down, and re-run onboarding when a new one is granted.

• Add a one-line CLAUDE.md (@AGENTS.md) if this is a Claude Code project (pi reads AGENTS.md directly).

2b. Existing entry files → audit + refactor

Walk every section of AGENTS.md (and CLAUDE.md) and classify it:

• Behavior (delegation, posture, planning, memory, the bridge, tripwires, fallback) → keep; add any of these that are missing, from the scaffold.

• Audit every behaviour-bearing file, not just the entry file. CONTRIBUTING.md, README.md and per-directory guides carry rules agents and humans both follow, and nothing reconciles them against the entry file or the skills. A fact stated in two places has two sources of truth and will diverge — this foundation's own README once stated the correct skill-layout rule while four other files stated the opposite, and every syntactic gate passed. Where such a file restates a skill-owned fact, replace the copy with a pointer.

• Facts / conventions (infra tables, IPs, domains, credential paths, command catalogs, service/app inventories, named conventions) → propose moving each into a local skill — a new .agents/skills/<name>/SKILL.md, or an existing one — leaving only a behavioral pointer in the entry file. When a fact fills one of the declared local-skill slots (per the doctor's slot check), start from the matching stub in templates/local-skills/.

• Accretion (changelogs, "recent changes", duplicated conventions) → propose removal; git history is the record.

• Landmines → for every convention that fails silently when violated, ensure (a) a Tripwire line in AGENTS.md, and (b) the owning skill's description names the trap + its consequence imperatively, so the skill loads reliably.

3. Recommend, then apply

Present a short plan first — what moves to skills, what's added, what's removed — then apply it. Moving content into skills is a real edit; confirm destructive removals with the operator. The entry file should come out shorter than it went in.

4. Re-run as the project evolves

This skill is idempotent. Run it again whenever the entry files have grown — a convention crept in, a new landmine appeared, a new local skill is warranted. Each pass nudges the project back to the rule: behavior in the entry file, facts in skills.

5. If the project runs OpenClaw

OpenClaw agents are personas, not crew roles — they don't load AGENTS.md or the plugin/package. They consume a skill slice installed into the gateway's managed skills dir. If the project runs OpenClaw, check (and flag to the operator if missing):

• The gateway's init-skills step clones the foundation at its pinned tag and installs the slice from a checked-in list in the consumer's own repo — never a hand-typed list, and never a list this foundation maintains, since which skills a persona should see is a deployment decision. A private foundation repo needs an init-only GH token.
• Each agent's agents.list[].skills allowlist exposes only the slice entries that match its LiteLLM VK grants (web search / image gen / KB) — don't hand an agent a skill for a capability its VK can't reach.
• Operator skills stay operator-only — the skills for building and tuning a gateway live in the consumer's own overlay, never installed into persona agents. This is a wiring check, not an AGENTS.md edit — record the specifics (slice list, tag, allowlists) in the project's local infra manifests, not here.

Done when (measure the outcome; don't gate it)

• AGENTS.md is short and behavioral; the facts are in skills.
• doctor reports OK (or a deliberate N/A) on every check for the chosen profile.
• Delegation routes to the foundation's roles.
• Every silent landmine has a Tripwire + an imperative skill description.
• Re-running the skill surfaces fewer and fewer changes over time.

Worked example: Harmony's filled AGENTS.md — the foundation's first consumer.