| name | setup-repo |
| description | Fully configure this repo for a specific project. Asks 3 targeted questions, reads the codebase, then writes all agent instruction files in place — replacing every [FILL:] marker across all 32 files. Run immediately after cloning the template. |
Setup Repo
Overview
This skill produces a fully configured repo with zero remaining [FILL:] markers. It covers all 32 files that contain markers — not just the primary instruction files — and writes them directly when run in Claude Code.
Announce at start: "I'm using the setup-repo skill. I'll ask you 3 quick questions, then read the codebase and write all instruction files."
When to Use
- Immediately after cloning this template into a new project
- When basic fills were done manually but deeper fills remain
- When onboarding an existing codebase onto this template
When NOT to Use
- Repo already fully set up (verify:
grep -rn "\[FILL:" . --include="*.md" returns nothing outside docs)
- You only need to update one specific file — edit it directly instead
Execution Modes
Mode A — Claude Code (preferred)
Claude Code has direct file access. The skill reads files, gathers facts, writes every file in place, activates git hooks, and validates. No copy-pasting required.
Mode B — Other agents
Generate a repo bundle first:
npx repomix
Attach repomix-output.xml to your chat. The skill outputs filled content tiered by priority — paste and apply Tier 1 before proceeding to Tier 2.
Phase 0 — Ask 3 Questions
Before reading a single file, ask the user these questions. Their answers fill things no codebase analysis can determine:
Question 1 — Users & deployment context:
"Who are the primary users of this project and what is the deployment environment?"
(e.g. "Internal logistics staff via a React dashboard", "Public API consumers", "iOS/Android WebView")
Question 2 — Immutable contract:
"Are there any externally-bound IDs, stored data schemas, or API versions that MUST NEVER change — even across refactors?"
(If yes, list them. If no, answer "none" — the Immutable Contract section will be deleted.)
Question 3 — Extra prohibitions:
"Is there anything agents should never do that won't be obvious from reading the code?"
(e.g. "Never modify the payments module without a second review", "Never add browser APIs — this runs in a Node.js CLI")
Wait for all three answers before proceeding.
Phase 1 — Gather Project Facts
Read the codebase to establish these values:
| Fact | Where to look |
|---|
| Project name | package.json name, directory name, README.md H1 |
| Description | package.json description, README.md intro paragraph |
| Tech stack | package.json dependencies/devDependencies, file extensions, import patterns |
| Test command | package.json scripts.test, Makefile, pyproject.toml, Cargo.toml |
| Lint command | package.json scripts.lint, .eslintrc*, .pre-commit-config.yaml |
| Build command | package.json scripts.build, Makefile, Dockerfile |
| Architectural constraints | .githooks/, CI workflows, patterns repeated across source files |
| Prohibitions | ESLint/linter rules, code comments flagging bad patterns |
| File structure | Top-level dirs, entry points, key config files agents need to navigate |
| Primary source file | Entry point (used in qa-audit and doc-audit skills) |
| Immutable IDs | Cross-referenced values, stored schemas (supplement with Question 2 answer) |
Also run:
grep -rn "\[FILL:" . --include="*.md" --include="*.yaml" --include="*.yml" --include="*.cursorrules" | grep -v ".git/"
This gives you the exact list of files and line numbers to process.
Phase 2 — Generate and Write (Tiered)
Process files in tier order. In Mode A, write each file in place using Edit/Write tools. In Mode B, output each tier's content before starting the next.
Fill quality rules — apply to every marker
| Rule | Pass condition |
|---|
| Specific | Includes file paths, function names, or exact patterns — never vague intent |
| Evidence-based | Only write what you found in the repo or user answers — never guess |
| Actionable | An agent can follow this rule without further clarification |
| Not code-inferable | Only constraints that agents cannot figure out by reading source |
Good: "No ORM — all DB queries in src/db/query.ts via raw SQL"
Bad: "Use the database correctly"
Section deletion rule: If a section has no applicable content, delete it entirely. Key conditional sections:
## Immutable Contract → delete if Question 2 answer was "none"## Layout Constraints → delete if not a UI/mobile project## [FILL: Language/Framework-Specific Rules] → replace heading + add stack-specific rules, or delete section if none apply
Tier 1 — Essential (agents read these every session)
These 5 files are loaded on every agent conversation. Fill them first.
1. CLAUDE.md
Fill: project name + description + tech stack (one line), 2 constraints, 2 prohibitions, test/lint/build commands, after-every-change steps.
2. AGENTS.md
Fill: project overview, 3 architectural constraints, file structure block (generate from actual top-level dirs and entry points — use text code block), 2 coding rules, immutable contract (or delete section), test command, verification steps, any project-specific doc links.
3. GEMINI.md
Same structure as CLAUDE.md — fill identically.
4. .github/copilot-instructions.md
Fill: project name + description + tech stack + deployment context (from Question 1), 2 always-do rules, 3 never-do prohibitions (include user answer from Question 3), key files table (3–5 rows: entry point, main config, test entry, key utility), any doc links.
5. .cursorrules
Fill: test command (one line).
Tier 2 — Important (quality gates, PR reviews, prompts)
6. .claude/agents/qa-reviewer.md
Fill: 2 project-specific review rules (derive from linting config, architectural constraints, or user answers).
7. .claude/rules/coding-standards.md
Fill: 3 architectural constraints, language/framework-specific rules section heading + 2–4 rules derived from stack, 2 project rules, immutable contract reference (or delete).
Then copy this file's content verbatim to:
.agent/rules/coding-standards.md (change frontmatter trigger: always — keep it).kilocode/rules/coding-standards.md
8–9. .agent/rules/coding-standards.md and .kilocode/rules/coding-standards.md
Apply the copy from step 7.
10. .github/pull_request_template.md
Fill: doc paths section (list the 2–3 key docs agents should verify are up to date after every change).
11. .github/prompts/new-feature.prompt.md
Fill: 2 planning constraints (derive from tech stack constraints — e.g. "This is achievable with [stack] — no [forbidden pattern]").
12. .github/prompts/review-changes.prompt.md
Fill: 2 project-specific review checks (derive from linting rules, architectural constraints).
13. .github/instructions/docs.instructions.md
Fill: additional doc paths relevant to the project (entry point docs, API docs, engineering playbook if present).
14. .github/instructions/qa-audit.instructions.md
Fill: main source file path (entry point), 3 project-specific audit checks (security, rule compliance, robustness — derive from codebase patterns).
Tier 3 — Skill files (fill once, sync to 3 directories)
Generate filled content for .claude/skills/qa-audit/SKILL.md and .claude/skills/doc-audit/SKILL.md, then copy each to the parallel directories.
15. .claude/skills/qa-audit/SKILL.md
Fill: main source file name, 1 project-specific security check, 2 rule compliance checks (from linting/architecture), 1 race condition check, 1 error propagation check, 1 key value that must match across rule files, any additional rule files beyond the defaults.
Then copy to:
.agents/skills/qa-audit/SKILL.md.agent/skills/qa-audit/SKILL.md
16. .claude/skills/doc-audit/SKILL.md
Fill: project-specific doc references, key values to verify for drift, any custom audit scripts.
Then copy to:
.agents/skills/doc-audit/SKILL.md.agent/skills/doc-audit/SKILL.md
Tier 4 — Workflows (complex — fill best-effort, flag unclear markers)
These workflows have deep project-specific content. Fill what can be determined from the codebase; flag any marker you cannot fill confidently with [REVIEW: <reason>] instead of leaving [FILL:].
17. .agent/workflows/qa-audit.md (35 markers)
Fill: test command, main source file, zone definitions (derive from file structure), rule checks (from architecture), config file list, security checks, robustness checks, drift checks.
18. .agent/workflows/pr-analysis.md (17 markers)
Fill: project-specific PR checks, rule file references, security patterns to scan for.
19. .agent/workflows/feature-delivery.md (7 markers)
Fill: implementation rules, platform constraints, docs to update after every feature.
20. .agent/workflows/doc-audit.md (6 markers)
Fill: doc structure, content descriptions, key drift points, any custom audit scripts.
21. .agent/workflows/architecture-change.md (6 markers)
Fill: runtime baseline, environment checks, docs affected by architecture changes.
22. .agent/workflows/release-readiness.md (5 markers)
Fill: baseline validation steps, compatibility checks, docs to verify before release.
23. .agent/workflows/post-merge-analysis.md (3 markers)
Fill: syntax checks, config reference doc path.
Phase 3 — Activate Git Hooks (Mode A only)
git config core.hooksPath .githooks
chmod +x .githooks/pre-commit .githooks/commit-msg
Phase 4 — Validate
Run:
grep -rn "\[FILL:" . --include="*.md" --include="*.yaml" --include="*.yml" --include="*.cursorrules" \
| grep -v ".git/" \
| grep -v "README.md" \
| grep -v "CHANGELOG.md" \
| grep -v "docs/CUSTOMIZATION-GUIDE.md" \
| grep -v "docs/SKILLS-CATALOG.md"
If output is empty — setup is complete. Commit with:
git add -A && git commit -m "chore: configure repo from template via /setup-repo"
If markers remain — list each with file + line. For each:
- If it can be filled from codebase facts: fill it now
- If it requires user input: ask the user directly
- If it is in a section that doesn't apply: delete the section
Repeat validation until clean.
Summary Output
After completing all phases, output:
## Setup Complete
- Files written: <count>
- [FILL:] markers resolved: <count>
- [REVIEW:] markers flagged for manual review: <count> (list them)
- Sections deleted (not applicable): <list>
- Git hooks: activated ✓ / skipped (Mode B — activate manually)
