| name | repo-agent-bootstrap |
| description | Bootstrap or maintain a repo-specific Copilot, Codex, and Claude agent stack by inventorying docs, commands, workflows, and existing AI assets before scaffolding managed guidance. |
Repo Agent Bootstrap
Use this skill when setting up or refreshing agentic coding support for a repository. It is for plan-first scaffolding and maintenance of:
AGENTS.md and CLAUDE.md.github/copilot-instructions.md and .github/instructions/*.instructions.md.github/agents/*.agent.md- selected
.github/skills/*
memory-bank/, plans/, ADRs, and architecture docs- safe workflow and hook stubs when the repo justifies them
When To Use This Skill
Use this skill when the task is to:
- bootstrap AI agent support for a new repo
- standardize a messy or inconsistent existing agent stack
- refresh repo guidance after architecture or workflow drift
- create a reusable Copilot/Codex/Claude setup tied to the repo's real purpose
Do not use this skill when the task is only:
- writing one standalone
AGENTS.md
- adding a single custom agent to an otherwise healthy stack
- making a small documentation tweak unrelated to repo-wide agent workflows
- importing unvetted third-party assets without pinned provenance
What This Skill Produces
This skill is designed to create or maintain a hybrid stack that works across GitHub Copilot, Codex, and Claude. It always:
- inventories the repo first
- derives major workflows from real docs and manifests
- proposes or generates an orchestrator agent plus focused specialists
- writes managed sections so later maintenance runs preserve human edits outside them
- records provenance for any imported third-party assets
Workflow
1. Inventory first
Run the inventory helper before generating files. Because this is installed as a global skill, invoke the bundled script from the global skill folder:
python "$HOME/.agents/skills/repo-agent-bootstrap/scripts/inventory_repo.py" --repo-root .
Review the JSON output for:
- repo purpose
- stack and commands
- repo map and high-signal files
- existing AI assets
- risky boundaries
- major workflows worth dedicated agents or instructions
If the repo already has AGENTS.md, .github/agents/, .github/instructions/, or memory-bank/, treat those as existing product context, not noise.
2. Plan the stack
Before writing files, decide:
- which workflows deserve custom agents
- which guidance belongs in always-on root files versus on-demand skills
- which path-specific instruction files are justified
- whether workflow or hook stubs are appropriate
- whether any third-party asset is clearly worth importing
Always include at least one orchestrator/planning agent.
Use these decision rules instead of guessing:
- Generate exactly one orchestrator/planning agent by default.
- Add a specialist agent only when a workflow is both repo-specific and recurring enough to justify a dedicated role.
- Prefer 2-5 total generated agents. Go above that only when the repo has clearly separate subsystems with different commands, risks, or contributor audiences.
- Add a path-specific instruction file only when a directory or file family has stable rules that differ from root guidance and are likely to matter repeatedly.
- Add a skill instead of more root guidance when the instructions are detailed, procedural, and only relevant sometimes.
- Add a hook or workflow stub only when the repo already has CI/automation patterns or a repeated validation routine that benefits from explicit automation guidance.
- If a candidate automation would be noisy, destructive, or hard to validate, skip it and record the skip in the final summary.
- Vendor a third-party asset only if it is pinned, attributable, licensed clearly enough to reuse, and materially better than a repo-specific original. Otherwise recommend it without copying it.
3. Scaffold the stack
Use the scaffolder to render managed content:
python "$HOME/.agents/skills/repo-agent-bootstrap/scripts/scaffold_agent_stack.py" --repo-root . --generated-on YYYY-MM-DD
The scaffolder writes managed sections for:
- root guidance files
- memory-bank files
- plans and ADRs
- path-specific instructions
- custom agents
- selected repo skills
- a provenance manifest
4. Maintain instead of replacing
When rerunning on an existing repo, preserve human edits outside managed blocks. Use:
python "$HOME/.agents/skills/repo-agent-bootstrap/scripts/merge_managed_file.py" --target AGENTS.md --source-file draft-managed.md
Use maintenance mode when:
- the repo architecture changed
- the command surface changed
- contributor guidance drifted
- the major workflows changed enough that the agent roster is now wrong
5. Validate before handoff
Always validate the generated stack:
python "$HOME/.agents/skills/repo-agent-bootstrap/scripts/validate_agent_stack.py" --repo-root .
On Windows PowerShell, the same commands can use ${HOME}:
python "${HOME}\.agents\skills\repo-agent-bootstrap\scripts\inventory_repo.py" --repo-root .
python "${HOME}\.agents\skills\repo-agent-bootstrap\scripts\scaffold_agent_stack.py" --repo-root . --generated-on YYYY-MM-DD
python "${HOME}\.agents\skills\repo-agent-bootstrap\scripts\validate_agent_stack.py" --repo-root .
The validator checks for:
- required bootstrap files
- custom agent frontmatter
- delegation-tool presence (
custom-agent, compatible with Task)
- provenance structure for imported assets
External Source Policy
Only vendor third-party prompts, skills, hooks, or workflows when all of the following are true:
- the source is pinned to a commit SHA or version tag
- the original path is recorded
- license/provenance is recorded
- the asset is clearly better than a repo-specific original
If licensing, provenance, or revision pinning is unclear:
- do not vendor the asset
- mention it only as a recommendation
- record exactly why it was not imported
Read these references before importing anything:
Reference Pack
Load these on demand, not all at once:
Bundled Templates
Template skeletons live under assets/templates/stack/. Use them when you need a concrete file shape quickly, but prefer tailoring the rendered content to the actual repo inventory instead of copying placeholders blindly.
Required Output Contract
When you use this skill, the final handoff should include all of the following:
- A short repo profile summary:
- purpose
- stack
- commands
- major workflows
- risky boundaries
- The planned or generated agent roster:
- orchestrator agent
- specialist agents
- any path-specific instruction files
- any selected repo skills
- A concrete file summary:
- files created
- files updated
- files intentionally skipped
- Validation results:
- which validation command ran
- whether it passed
- unresolved warnings or drift
- External-source provenance:
- imported items and pinned revisions
- or explicit note that no third-party assets were vendored
Do not end with only “done” or a raw diff summary. The output should make it obvious what was discovered, what was generated, what was skipped, and why.
Scripts
scripts/inventory_repo.py: emit a structured repo profile as JSONscripts/scaffold_agent_stack.py: render and write the managed bootstrap stackscripts/merge_managed_file.py: replace only the managed section in an existing filescripts/validate_agent_stack.py: validate the generated stacklib/repo_agent_bootstrap/: bundled portable Python library so the global skill works even when the source repo is not installed locally
Optional installer
If you are working from the source repository and want to publish this repo-local skill into your global shared skills folder, use the repository helper:
.\scripts\install-global-skill.ps1 -SkillName repo-agent-bootstrap
Preview without changing anything:
.\scripts\install-global-skill.ps1 -SkillName repo-agent-bootstrap -WhatIf
If you are reading this skill from an already-installed global location, you can ignore this installer section.
