Ynh Create Harness

Create a Harness

You are guiding a user through creating their first ynh harness. Follow this workflow step by step, asking one question at a time.

Before you start

Read these references to understand the current formats and conventions:

1. Read references/harness-format.md for manifest syntax, directory structure, and install/run commands
2. Read references/artifact-formats.md for skill, agent, rule, and command formats
3. Read references/example-harness.md for a complete worked harness — manifest, skill, agent, rule, command and AGENTS.md, with notes on what makes each one good rather than generic

All three ship with this skill, so they are readable wherever it is installed. Do not go looking for examples in the ynh repository: a user's project does not contain it.

Step 1: Harness name

Ask the user what they want to name their harness. Explain that this becomes the command they type to launch it (e.g., if they name it david, they'll run david to start a session).

The name should be lowercase, short, and memorable. It becomes a shell command.

Step 2: Output directory

Ask where to create the harness directory. Suggest a sensible default like ~/harnesses/<name> or a sibling directory to wherever they're working. Let them choose.

Step 3: Default vendor

Ask which AI vendor they want as the default. Run ynh vendors to show what's available — that command is the authority, not this page. Today it lists claude, codex, cursor, and copilot.

ynh vendors answers "is this CLI installed", not "what does this vendor support". Those differ, and the difference only bites when the harness is distributed — see the artifact-support table in references/artifact-formats.md. Ask whether they intend to publish this harness as a native plugin; if so, raise it now rather than at export.

Explain they can always override with -v at runtime.

Step 4: Starter artifacts

Ask which artifact types they want scaffolded. Offer these options:

• Skills - Reusable capabilities (e.g., code review, commit messages)
• Agents - Specialists Claude can delegate to (e.g., security reviewer)
• Rules - Persistent context loaded every session (e.g., "always write tests")
• Commands - Reusable actions (e.g., "run CI checks")

They can pick any combination, or start with none and add later.

If they plan to publish this as a native plugin, say what each vendor carries before they choose. Every vendor receives all four types through ynh run, but ynd export drops what a vendor's plugin format cannot hold: Codex takes skills only, and Copilot takes no rules or commands. references/artifact-formats.md has the table. Load-bearing content belongs in skills, which every vendor carries.

Step 5: Generate the harness

Create the directory structure based on their choices:

<output-dir>/
├── .ynh-plugin/
│   └── plugin.json
├── AGENTS.md            (optional - read natively by most vendors; ynh shims Claude via @-import)
├── skills/              (if selected)
│   └── <example>/
│       └── SKILL.md
├── agents/              (if selected)
│   └── <example>.md
├── rules/               (if selected)
│   └── <example>.md
└── commands/            (if selected)
    └── <example>.md

For .ynh-plugin/plugin.json:

{
  "$schema": "https://eyelock.github.io/ynh/schema/plugin.schema.json",
  "name": "<their-name>",
  "version": "0.1.0",
  "description": "<their description>",
  "default_vendor": "<their-vendor>"
}

For each artifact type selected, generate a starter example with realistic content (not lorem ipsum). Use references/example-harness.md as the model for format and depth, and make the content relevant to what the user told you they work on.

Important: Follow the exact formats from references/artifact-formats.md:

• Skills: directory with SKILL.md containing YAML frontmatter (name, description)
• Agents: markdown file with YAML frontmatter (name, description, tools)
• Rules: plain markdown file
• Commands: markdown file with instructions

Step 6: Install and test

Show them how to install:

ynh install <output-dir>

If the harness lives inside a monorepo, use --path:

ynh install <repo-url> --path <subdir>

Offer to run this command for them. Then show how to use it:

<name>                          # interactive session
<name> "hello, introduce yourself"   # quick test

If ynh isn't on their PATH, remind them about the build step (make build) and PATH setup from references/harness-format.md.

Step 7: Next steps

After the harness is working, mention:

1. Add external skills - They can pull skills from any Git repo by adding includes to .ynh-plugin/plugin.json. See references/harness-format.md for the syntax.
2. Team setup - When ready, they can use /ynh-team-setup to create a team harness with delegation.
3. Private repos - If they need private Git repos, SSH URLs (git@github.com:...) are recommended. ynh delegates to the local git binary - if git clone works, ynh works.