Add @openagt/init: one command gives a project its skills

[suleimansh]

The fourth step of #2023: the command itself. npx @openagt/init shows the skills as a list with ticks and writes the ticked ones into the project.

👤

• npx @openagt/init is the one front door. It adds the skills, and ends by asking "Open the dashboard?".
• Init writes the skills as tracked files. The person commits them.
• Init shows a list with ticks. Everything is ticked except the skills that need a setup of their own (browser, discord).
• To add or remove a skill later, run init again: it shows the same list. add and remove by name also work, for scripts.
• When a skill has a newer text, the person is told. It updates only on their word.
• After writing the files, init asks "Commit these files now?" and makes one commit. It never pushes.
• The scheduler is one more tick in the list. It is ticked, and its rows start switched off.

🤖 automated · Opus 5.5, effort high

What a person sees

$ npx @openagt/init
OpenAgent skills for my-project
Every agent already gets the basic skills with nothing written here: branches, logs, question, and github on a GitHub project.

  Tickets and queue
> [x] tickets                     Where the project's tickets live, how to read and change them, …
  [x] queue                       Where the project's agent queue lives, how to read it and change it, …
  …
  Needs its own setup
  [ ] browser                     A real browser you drive from the shell, …
  [ ] discord                     Post a message to the team's Discord channel from the shell, …
  The scheduler
  [x] scheduler                   Starts the automations you switch on, while the dashboard is open. …

↑↓ move · space tick · a all · n none · enter write · q leave as it is

Wrote 19 skills in .agents/skills, each linked in .claude/skills: tickets, queue, …
The scheduler starts with the dashboard, on this machine. Every automation starts switched off.
Commit these files now? (Y/n) yes
Committed as b70d7e6, these files alone. Nothing was pushed: push it, or open a pull request where the default branch is protected.
Your agents get these skills once they are on the branch agents start from.
Open the dashboard? (Y/n)

The new package, packages/init (@openagt/init)

• A skill is one file, .agents/skills/<name>/SKILL.md, and one link, .claude/skills/<name>. Nothing else is written: no package.json, no install.
• The list holds 21 skills in five groups, and the scheduler. The four basic skills are not in it: they come with every run.
• Run again, the ticks show what the project has. A tick added writes a skill, a tick removed deletes it.
• For scripts: add <name>…, remove <name>…, update [<name>…], list, and --commit. They ask nothing and print JSON, like the skills' own commands.
• The commit holds only the skill files. A file the person had staged stays staged.
• Off GitHub, with a remote on another host, init says in one line that agents push their branch and the person opens the request.
• applyChange is the one place every change goes through. The dashboard's "Add skills" screen will use it too, in the next pull request.

What moved

• What "Add project" does to a folder (installProject) moves from the dashboard to @openagt/agent-data, so init and the dashboard share it.
• The scheduler learns to say whether a project's start lines run it, to add no second line beside an older one (npx agent-scheduler start), and to take its lines back.
• This repository's own 21 skill texts are now written by the command. Each gained two lines (see the first pick below).

Picks of mine

• A written text carries its version. Init adds metadata.version to the text's front matter. This answers two open questions of the issue. A later init, or the dashboard, can tell three cases apart when a project's text is not the one it carries: the project's is older ("a newer text is there"), it was changed by hand (named, and left; only update <name> writes over it), or the reader itself is the older one (it says nothing).
• Switching the scheduler on in a folder no dashboard knows yet makes the folder a project first, exactly as "Add project" does: a git repository when it is none, an empty first commit, the hidden .openagent/. The scheduler's lines live there.
• Switching the scheduler off also stops one that is running. The line that stops it when the dashboard closes has just been removed.
• add leaves a skill the project already holds as it is. Only update <name> writes over a text.
• Ctrl-C at a question ends the run there. At the list it changes nothing. After the files are written it leaves them uncommitted.
• Init carries the texts through the 21 skill packages as its dependencies. They are small; the only outside package is yaml.
• The command's program is named openagent-init. The commit says "Add OpenAgent skills" (or Remove, or Update).
• A project with no remote is told nothing about a git host. GitHub is counted among a project's skills only on GitHub ("3 of 25" otherwise).

The issue's open questions, answered

• Newer than what? and Update overwrites a text changed by hand: the version in the text, above.
• Does a skill break when another one is unticked? No. Each text ends its own way: "If this project has no ticketing system or no AI queue, show an error to the user saying which and stop." The commands are fetched by full name whether or not the other skill is ticked.
• What do the texts that name pull requests do off GitHub? Read, not yet run: they tell the agent to end with an error where a pull request cannot be opened. The scheduled rows of update-tickets and post-merge-cleanup call gh in their shell line, which fails there, so those two rows never start.
• With no network: a full-name call waits 70 seconds, then runs from npm's cache. Agents need the network anyway.
• Not done: folders of other coding tools, a list of default skills as its own package, picking by use case.

Known

• A project whose ignore rules cover .claude/ or .agents/ cannot commit the files. Init says which path git ignores and leaves the files.
• On Windows the link needs a real symbolic link. Where it cannot be made, init says Claude Code does not have the skill.
• A text of the person's own that already ends its front matter with metadata.version reads as written by init.
• The root README still says npx @openagt/dashboard. It changes when this is on npm.

To publish (never by an agent): @openagt/init at 0.1.0, with the 26 at 0.1.0. @openagt/agent-data, @openagt/agent-runner and @openagt/dashboard have changed since their published versions and need a new number first; the next pull request bumps them.

Checked

• Full root CI alone. The new package's tests once more without my git settings, and as a machine with no git identity at all.
• In a real terminal, on a rig: an empty folder (init makes it a repository, writes 19 skills, commits them alone), a second run (the ticks show what it has; one unticked, one ticked, the scheduler off), a Node project, a terminal of 80 by 24.
• End to end as a person runs it: npx @openagt/init in a fresh folder, with the packages served by a throwaway registry on this Mac (never npm). Then a skill's command by its full name from that registry, in the project init had set up.
• Broken on purpose five ways (the commit takes everything staged; a text changed by hand counts as newer; removing deletes the whole folder; browser ticked by default; Enter means yes to an update): the tests caught each.
• One fresh reviewer: seven defects (the scheduler left running, Ctrl-C read as "no", a failed commit where git ignores the folders, a list that scrolled a short terminal, a commit edge case, a project whose .claude/skills is itself a link, Windows) and a list of smaller things. All acted on, each with a test.

DECISIONS.md

packages/init/DECISIONS.md is new. Its eight bullets write down the picks under 👤 and nothing of mine:

npx @openagt/init is the one front door: it gives a project its skills, and ends by asking "Open the dashboard?". "Add project" in the dashboard stays small and offers the same list with a button, so a person can use either. Picked over "Add project" writing the skills itself, which put files into every project a person adds, also one they only wanted to try, and over the dashboard only pointing to the terminal.

A project has a skill when the skill's text is in the project: one tracked file, .agents/skills/<name>/SKILL.md, where Codex reads it, and one tracked link at .claude/skills/<name>, where Claude Code reads it. Init writes nothing else: no package.json, no install, so a Node project, a PHP project and an empty folder get exactly the same. Picked over files hidden from git and linked into each checkout, which a teammate, another machine and a cloud agent would not have, and over installing the skills' packages into the project.

Four basic skills are not in the list: branches, logs and question, and github on a GitHub project, come with every run, with nothing written in the project. Picked over branches alone coming that way, where a person who cannot change the default branch got agents that could not ask a question.

In a terminal init shows the skills as a list with ticks, in groups. Everything is ticked except the skills that need a setup of their own (browser, discord). Picked over writing every skill unasked, and over writing only the basic ones.

To add or remove a skill later, run init again: the ticks show what the project has now, a tick added writes a skill, a tick removed deletes it. add and remove by name do the same without the list, for scripts, and ask nothing. Picked over separate commands only, which need every skill's name known.

The scheduler is one more tick in the list, ticked by default. It is no skill: ticking it writes its two lines into the project's hooks file, which is this machine's and outside git, so this one tick is per person and per machine. Every automation starts switched off, so a ticked scheduler starts no agent by itself. Picked over a scheduler that comes with the dashboard for every project.

After writing, init asks "Commit these files now?". On a yes it makes one commit on the branch the person is on, holding the skill files it wrote or deleted and nothing else they have open. It never pushes. Picked over leaving the commit to the person with a line of advice, and over committing and pushing unasked.

When a skill in the project has a newer text, the person is told, and it is written only on their word. Picked over saying nothing until asked, and over every run of init writing every text again, which wrote over a text changed by hand.