setup-agent-harness

name	setup-agent-harness
description	Creates a generic agent-harness folder with repository-context hooks, starter config files, and manifest-driven skill installation. Use when creating or bootstrapping a local agent harness, or when the user needs confirmation-driven prerequisite checks for Python, PyYAML, and GitHub CLI before running the setup script.

Setup Agent Harness

Quick start

1. Ask the user for the target directory.
2. Tell the user the setup uses the bundled starter-skills.yaml manifest by default.
3. Tell the user the generated .agents/harness/config/repositories.yaml is pre-populated from the bundled starter-repositories.yaml template.
4. Instruct them to fix local paths in that template and add any extra repositories after setup.
5. Run a preflight check for Python, PyYAML, and gh skill.
6. If a prerequisite is missing, explain why it is required and ask before installing or updating anything.
7. After prerequisites pass, ask whether to install skills now or scaffold only.
8. Ask for --repo values only if the user explicitly wants to override template paths or append extra repositories during setup.

Run the setup script from the agent-harness root with the interpreter that passed preflight:

python skills/setup-agent-harness/scripts/setup_agent_harness.py \
  --target-dir C:/repos/my-agent-harness \
  --skip-install

Workflow

1. Collect the target directory before running the script.
2. Default to the bundled starter-skills.yaml manifest. Do not ask the user to choose a manifest unless they explicitly ask to start from a custom YAML file.
3. Default to the bundled starter-repositories.yaml template for .agents/harness/config/repositories.yaml.
4. Do not ask the user to enumerate every local repository by default.
5. After generation, tell the user to fix local paths in .agents/harness/config/repositories.yaml and add extra repositories as needed.
6. If the user provides --repo values, treat them as overrides for matching template ids and append new ids that are not in the bundled template.
7. Check py -3, python3, or python for the current OS before invoking the setup script.
8. If Python is missing, tell the user both the setup script and the generated SessionStart hook depend on Python, then ask before attempting installation.
9. If Python exists but import yaml fails, ask before installing PyYAML through the interpreter that passed preflight.
10. If the user wants immediate skill installation, verify gh skill --help first. If it is unavailable, ask before installing or updating GitHub CLI.
11. Prefer the platform package manager already present on the machine, and stop if installation needs privileges or policy exceptions the user has not approved.
12. Each skills[] entry must declare its own repository.
13. Skill repositories accept OWNER/REPO, HOST/OWNER/REPO, and repository URLs like https://github.com/microsoft/agent-skills or https://git.example.com/platform/agent-skills.
14. GitHub Enterprise URLs are normalized to HOST/OWNER/REPO, and installs from those hosts run with GH_HOST set automatically.
15. Use repeated --repo ID=ABSOLUTE_PATH arguments only when the user explicitly wants to patch bundled repository paths or append more repositories during setup.
16. Use --manifest-file <path> only when the user explicitly asks to start from a custom YAML manifest.
17. Use --skip-install when prerequisites are not ready or the user wants scaffold-only setup.
18. Use --force only when intentionally overwriting managed files.

What it creates

• AGENTS.md
• .gitignore
• .github/hooks/repository-context.json
• .agents/harness/tools/inject-repository-context.py
• .agents/harness/config/repositories.yaml
• .agents/harness/config/skills.yaml
• .agents/harness/runtime/
• .agents/skills/

Notes

• The generated hook injects only repository ids and absolute local paths.
• The generated harness does not assume an active project or default repository.
• The generated .agents/harness/config/repositories.yaml starts from the bundled starter-repositories.yaml template.
• --repo values override matching template ids and append extra repositories.
• The generated SessionStart hook depends on Python and PyYAML, not just the initial setup script.
• The bundled starter manifest is the default initial skill list. Edit .agents/harness/config/skills.yaml later if the team uses a different catalog.
• Skill repositories can be written as OWNER/REPO, HOST/OWNER/REPO, or as a GitHub repository URL. The setup script stores the normalized [HOST/]OWNER/REPO form.
• Shared defaults.repository is intentionally not supported. Keep the source repository next to each skill entry.
• When a skill comes from GitHub Enterprise Server, authenticate gh to that host first. The setup script sets GH_HOST automatically during installation.
• .agents/harness/config/repositories.yaml is ignored by default because it stores machine-local absolute paths.

See REFERENCE.md for config schema, preflight command suggestions, and command examples.