project-setup
Skill0 starsChanged 3 days agoMITView on GitHub
One-time setup of a repository for Claude Code and OpenCode (V2) and these skills: inspect what exists, propose the committed .claude/settings.json and opencode.jsonc (schema, allow rules for its checks, deny rules for pkill, killall, force push, secret files), AGENTS.md as the one instruction file with CLAUDE.md importing it, the four project facts, official stack skills, this repo's skills kept installed and current for both tools, then optionally Matt Pocock's skills, shipped as a chore PR. Differs from matt-bridge (how his skills run), setup-matt-pocock-skills (tracker, labels), the Vercel bootstrap skill (env pulls), /init (a starting CLAUDE.md) and claude-automation-recommender (suggests, writes nothing). Use when setting up or auditing a repository for Claude Code or OpenCode, 'configura il progetto', 'configura il progetto per OpenCode', 'setup del progetto', 'prepara il repo per Claude', in any project.
55 other projects use a version of this.
Adopted by
Most recently taken up by
- Michael-cmd-sys/claude-skillstheir own version, first seen Nov 16, 2026
- cloudcart/ai-toolkittheir own version, first seen Nov 16, 2026
- gabimoncha/skillstheir own version, first seen Nov 15, 2026
- mikejhill/agent-skillstheir own version, first seen Nov 15, 2026
- GravionLabs/skillstheir own version, first seen Nov 15, 2026
- dvy1987/agent-loomtheir own version, first seen Nov 15, 2026
Used with
Projects with it also use creative-writing-craft, creative-writing-muse and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
Abdullokh-NSkillcreative-writing-craft
Справочник ремесла: проза, сцена, стиль, голос. Загружать, когда нужно знание "как писать", а не режим производства.
Also in 3 projects that use this
Abdullokh-NSkillcreative-writing-muse
Точка входа в набор скилов для длинной прозы. Включается, когда автор просит спланировать, написать, продолжить, переписать или разобрать художественный текст — роман, повесть, цикл рассказов. Ведёт маршрут от замысла к готовому куску и держит базу знаний проекта.
Also in 3 projects that use this
badgidsSkillcharacter-sim
Pressure-test a character by speaking or reasoning strictly from that character's current voice, goals, relationships, emotional pressure, and knowledge boundary without creating canon by accident.
Also in 3 projects that use this
jpsweeney97Skillwriting-principles
Enforces writing principles for instruction documents (SKILL.md, skill supporting files, subagents, CLAUDE.md). Use when writing, reviewing, or editing any file in **/skills/**/*.md, **/agents/*.md, or **/CLAUDE.md. Triggers on skill creation, skill file updates, CLAUDE.md changes, subagent authoring, or instruction document review.
Also in 3 projects that use this
ItsSidharthaSkillstory-planning
Collaborative planning skill for a GitHub issue. Takes issue content and codebase context as input. Runs an iterative clarification loop until the user explicitly agrees to a plan, then saves it to docs/<story_number>/plan.md. Used by the user-story-implementation skill — load this skill at the start of Phase 1 and follow it completely before returning to the orchestrator.
Also in 3 projects that use this
badgidsSkillstory-review
Diagnose existing prose at a chosen editorial level, from whole-story and developmental problems through scene, line, copy, and proof passes, without rewriting until the diagnosis is accepted.
Also in 3 projects that use this
- +4 more from Abdullokh-N
Other versions55 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 55
- codewithmukesh/dotnet-claude-kit★ 808same name
- karrioapi/karrio★ 799same name
- haowjy/creative-writing-skills★ 590same name
- Resgrid/Core★ 238same name
- sd0xdev/sd0x-dev-flow★ 192same name
- sd0xdev/sd0x-harness★ 192same name
- fltman/project-scaffolder★ 88same name
- markshust/hcf★ 79same name
- vaayne/agent-kit★ 54same name
- dleerdefi/claude-code-construction★ 53same name
45 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- adhd-repliesSkill
- assertions-go-redSkill
- clean-codeSkill
- cloud-workerSkill
- context-hygieneSkill
- coordinator-methodSkill
- git-conventionsSkill
- matt-bridgeSkill
- merge-gateSkill
- model-mixSkill
- mod-uiSkill
- overnightSkill
- release-watchSkill
- roadmap-trackerSkill
- screen-mapSkill
- shared-machine-checksSkill
- skill-auditSkill
- smart-modsSkill
- smart-ultracodeSkill
- verified-researchSkill
- windows-opsSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 48 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Run the inspect commands in reference.md from the repo root.
- Distinctive: line 23
Stop and ask if the working tree has changes that are not setup work.
- Distinctive: line 32
Never narrow, loosen or remove an existing deny or ask rule, and never add an allow that overlaps one.
- Very specific: line 53
Ask only for the Claude plan: line if absent (model-mix needs it): one question, with a recommendation.
“Common” is measured: kept by at least 6 in 10 of the 48 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Project setup
Sets one repository up for Claude Code, OpenCode V2 and the skills in this repo, then checks it again on later runs. It writes project facts into the project and never into a skill. The project's own AGENTS.md, CONTRIBUTING.md and branch protection win over everything here.
Doc facts, templates, scripts and inspect commands are in reference.md (read it before step 1). Its date checked covers both tools; read the live page when it is old. OpenCode: V2 names only (permissions, shell), never V1 permission or bash.
1. Inspect, change nothing
Run the inspect commands in reference.md from the repo root. Report one short table of what exists and what is missing:
- git: clean or dirty, default branch, remote, and the rules on the default branch (
gh api repos/{owner}/{repo}/rules/branches/<default>, no admin needed). AGENTS.md,CLAUDE.md,CLAUDE.local.md.- Claude Code:
.claude/(settings.json with env values redacted, settings.local.json, skills, agents, commands; hooks live in settings.json) and.mcp.jsonserver names only. - OpenCode:
opencode.jsonc(or.opencode/), itspoliciesandpermissions,mcp.serversnames only,opencode --version. - Installed mods that handle
tool.check(see step 2). .gitignoreand the stack: package manager, check, test, lint and build commands, docker compose files, CI config, and the frameworks and vendors in use.
Stop and ask if the working tree has changes that are not setup work.
2. Project config for both tools
Propose each file, show the exact diff, write after the person's ok. Permission rules are the person's call. Same deny set in both tools: pkill, killall, force push, and the secret files the project really has.
- Claude Code:
.claude/settings.json, committed, strict JSON, with$schema. Deny rules go inpermissions.deny. - OpenCode:
opencode.jsonc, with$schema. Deny rules go inpolicies(tool.use), so a later rule or a saved approval cannot lift them. - Allow exact script names only, never
npm run *ormake *; an allowed script runs whatever it contains. In OpenCode the default policy already allows everything, so allow rules mean something only after ashellaskrule: offer the pair, never one half. - Never narrow, loosen or remove an existing deny or ask rule, and never add an allow that overlaps one. A rule that looks wrong is reported and left alone.
- Say once, when you show the diff, how far a deny reaches. A Bash or shell deny matches the command text, so
git -C . pushand/bin/rmget past it. A read deny covers the read tools, not a script orcatthat opens the file. Only the sandbox enforces at OS level; a PreToolUse hook is the next best guard in Claude Code. Offer either; add neither unasked. - Mods: on a personal login with no managed settings, a Claude Code mod that handles
tool.checkcan approve a call a deny rule refuses. List the installed ones with the loop inreference.mdand name them in the diff message. - Force pushes are stopped on the remote, not by a local rule. If step 1 found no rule on the default branch, tell the person to add a ruleset (block force pushes, restrict deletions, require a pull request). Show the ruleset JSON and the
gh apicall fromreference.md; change the repo only on their explicit ok. .gitignore: add.claude/settings.local.jsonandCLAUDE.local.mdif missing.- Project skills go in
.claude/skills/<name>/SKILL.md: OpenCode reads that folder too. Create it only when there is a skill for it. In OpenCode a skill with the same ID in~/.agents/skillsor~/.config/opencode/skillsbeats the project one, so check the ID against both before adding it. - MCP:
.mcp.jsonis Claude Code's,mcp.serversinopencode.jsoncis OpenCode's. Report both. Add no server.
3. Instruction files
OpenCode reads AGENTS.md only; Claude Code reads CLAUDE.md. So AGENTS.md is required and holds the project text; CLAUDE.md is @AGENTS.md plus Claude-only lines. Cases (only CLAUDE.md, both, neither) are in reference.md; the move from CLAUDE.md is one commit and shown as a diff first. Like every project write, it waits for the person's ok.
AGENTS.mdgets the "Checks and queue" block from the README ("In a new project"). Fill the check command from step 1, the lock file fromshared-machine-checksif the project runs heavy checks, hot files fromgit log(the files most PRs touch), and label strings fromdocs/agents/triage-labels.mdorgh label list. Ask one question at a time, with a recommendation, for what is still blank.
4. These skills, global
This repo is public, so the automatic part is opt-in. The script in reference.md ("These skills") writes without asking only when ~/.claude/CLAUDE.md has the line claude-skills: auto-sync. Without it the script is a dry run: show its would: lines, ask once, rerun with APPLY=1 after the ok, and offer to add the line so later runs need no question. Never overwrite a real directory.
- The script clones this repo if absent (reusing a clone found by
git remote), links every missing skill into~/.agents/skillsand~/.claude/skills, and updates every copy that differs from the repo's default branch in~/.config/opencode/skills,~/.claude/skills,~/.agents/skillsand plugin marketplace clones. A clone is fast-forwarded only when clean and on its default branch; otherwise it prints areport:line, because it may be the person's working copy. - OpenCode ranks
~/.config/opencode/skillsfirst, so a stale copy there hides the current one without a warning. - Routing block: the same script makes sure
~/.claude/CLAUDE.mdhas the README's routing block, and that~/.config/opencode/AGENTS.mdreaches the same text (a link to the first file; a different file gets the block appended, never replaced). - Ask only for the
Claude plan:line if absent (model-mixneeds it): one question, with a recommendation. - Point, do not repeat:
git-conventions(offer its commit-msg hook only when the project has no CI of its own),roadmap-tracker,shared-machine-checksandmodel-mix.
5. Stack skills
From the stack of step 1, suggest skills from the stack's own vendor and nobody else (supabase/agent-skills for Supabase). Table, duplicate check and install command are in reference.md.
- First list what is installed in
~/.claude/skills,~/.agents/skills,~/.config/opencode/skillsand the plugins. A skill that is there, under any name, is not suggested again. - Vet each one with
skill-auditon a fresh clone before the install. Show the verdict and the exact command; run it only after the person's ok. - Install at user level only: the directory in
~/.agents/skills/<id>and a symlink in~/.claude/skills/<id>. Never into the project.
6. Matt Pocock's skills
An ## Agent skills block in CLAUDE.md or AGENTS.md, or a docs/agents/ folder, counts as yes (matt-bridge §2). Otherwise ask once: "Use Matt Pocock's skills in this project?" Recommend yes for a repo that builds features from issues, no for a script or a single-owner experiment. After a no, ask again only if the person brings it up.
Find his skills before anything else, in this order, and report the source of each: project .claude/skills/<name>/SKILL.md, ~/.claude/skills/<name>/SKILL.md, ~/.agents/skills/<name>/SKILL.md, the lock file ~/.agents/.skill-lock.json (source mattpocock/skills), then claude plugin list. Commands are in reference.md.
- Found as directories (the
npx skillsCLI): OpenCode sees them too. Compare the names withmatt-bridge/flow.md, report missing or renamed ones, and propose that tool's own update command. Run it only after the ok. Never install the plugin over directory copies and never delete a copy without the person's ok. - Found as the plugin: compare
claude plugin list(version) andclaude plugin details mattpocock-skills(skills) with that file. If it is behind, showclaude plugin update mattpocock-skills@mattpocockand run it after the ok. OpenCode has no plugin command and does not read plugin folders: if the person uses OpenCode, say that the skills reach it only as directories and offer the directory install. - Not found, and the person said yes: the yes does not cover adding a third-party source. For Claude Code show both commands from
matt-bridge§1 with their scope (--scope userunless the person picks project, and then the change goes in the PR); for OpenCode or both, the directory installnpx skills add mattpocock/skills -g. Say that either adds code that updates on its own, and vet it first (smart-modsfor the marketplace,skill-auditfor the directories). Run only after the ok on those exact commands. Then confirm the skills:claude plugin details mattpocock-skills, or the directories. - Then tell the person to type
/setup-matt-pocock-skills. It is theirs to start. Its files land by PR, undermatt-bridge§2 androadmap-tracker§5 for the labels.
7. Ship it
Branch chore/issue-<n>-agent-setup from the default branch (<n> is the issue number; without an issue use chore/agent-setup). One commit per topic, written by git-conventions. Open a PR. Never push to the default branch. Steps 4 and 5 change the home folder, not the repo: they are not in the PR.
8. Run it again
On a project that is already set up, change nothing in the repo on the first pass. Report drift only: a missing $schema, an allow rule for a command that no longer exists, a template deny rule missing from either tool's file or present in only one, a project with CLAUDE.md and no AGENTS.md, a missing ignore line, an AGENTS.md block with a blank fact, no rule on the default branch, Matt's skills behind. Propose each fix as in step 2. The sync script of step 4 runs every time.
Done when
.claude/settings.jsonis valid JSON with$schema, andclaude doctorrun in the repo reports no settings error.- The person confirms
claudestarts in the repo with no Settings Error dialog;/statuslists the project file underSetting sources. - OpenCode: the config load check in
reference.mdlistsopencode.jsoncand prints no diagnostic for it. A rejected file is left out of the list with exit code 0, so read the list, not the exit code. - AGENTS.md has the four facts, none left as
<...>; a project withCLAUDE.mdhas it importAGENTS.md. - The sync script ends with no
still differsline, or each one is explained to the person. - His skills are found by the step 6 check, from whichever source, if the person chose them.
- The PR is open and the default branch is untouched.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

