agentleFS
farukzahrafarukzahra/agent-skills/skills/project-init/SKILL.md

project-init

Skill0 starsChanged 2 months agoMITView on GitHub

Bootstrap Superpowers agent workflow in a project — docs/superpowers folders, mandatory skills (brainstorming, writing-plans, semantic-version, caveman-commit, dont-forget, recap, automate-before-manual, dont-be-lazy, validate-before-share, finish-with-dev-server, ask-before-architecture, diagrams-mermaid, ui-change-e2e), slash commands, AGENTS.md gates. Use when user invokes /init or asks to initialize agent conventions in a new or legacy repo.

43 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use harness-audit, workflow and 3 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.
  • sattva2020Skill

    harness-audit

    Audits a codebase for "AI-agent harness" maturity across six layers (context engineering, tools & MCP, memory & state, tests & evals, observability, guardrails & approvals). Scores each layer, flags AGENTS.md/CLAUDE.md drift, gives prioritized fixes. Use for "audit harness", "оцени харнес", "check agent readiness", "is this project agent-ready", "проверь готовность к AI-агентам".

    Also in 3 projects that use this

  • VercelSkill

    workflow

    Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.

    Also in 3 projects that use this

  • MicrosoftSkill

    release

    Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).

    Also in 4 projects that use this

  • MicrosoftSkill

    handoff

    Compact the current conversation into a handoff document for another agent to pick up.

    Also in 3 projects that use this

  • GoogleSkill

    code-review

    Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 1 is distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 22 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read README.md, AGENTS.md, package.json, docs/stack.md.

    line 64
  2. Distinctive:

    Create if missing (never delete existing specs/plans):

    line 68
  3. Very specific:

    Run the sync script (installs all current farukzahra/agent-skills packages, including any newly added skills):

    line 80
  4. Very specific:

    Create docs/release-history.json at 0.1.0 if missing.

    line 125
  5. Very specific:

    Run without user invoking /init

    line 137
  6. Very specific:

    Commit or push (/commit-push handles ship)

    line 139

“Common” is measured: kept by at least 6 in 10 of the 22 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Project init — bootstrap agent workflow

Only when the user invokes /init or asks to initialize this repo — never automatic.

Sets up Superpowers + Faruk mandatory skills in the current project. Does not scaffold apps, commit, or push.

Summary (what init does)

#Action
1Create docs/superpowers/specs/ and plans/ (+ README)
2Install mandatory skills at project scope
3Ensure /commit-push, /init, and /recap in .cursor/commands/
4Optional: Cursor rules + docs/release-history.json for web apps
5Merge AGENTS.md workflow table (never replace a rich file)

Mandatory skills to install

Superpowers (obra/superpowers via skills-lock.json)

SkillGate
brainstormingNo feature code before approved spec
writing-plansPlan → docs/superpowers/plans/
systematic-debuggingRoot cause before bug fixes
verification-before-completionEvidence before "done"

Faruk (farukzahra/agent-skills)

SkillGate
semantic-versionVersion bump only on /commit-push → /sobre
caveman-commitCommit messages on /commit-push
dont-forgetRecurring rules → CI/hooks/codegen, not prose
recapSession handoff → HTML recap (/recap)
automate-before-manualTry PAT/SSH/API before manual steps (../secrets/)
dont-be-lazyUser lazy → API/MCP, vault, Cursor browser — agent finishes
validate-before-shareVerify URLs before sending to user
finish-with-dev-serverDev server up, port conflict rules, test URLs
ask-before-architectureAsk before stack/architecture choices
diagrams-mermaidMermaid only; validate syntax before show
ui-change-e2eE2E on UI create/change/bugfix

Optional after init

  • skills-sh-maintainer — only agent-skills repo

Workflow

1. Inspect

Read README.md, AGENTS.md, package.json, docs/stack.md. Note stack only.

2. Superpowers folders

Create if missing (never delete existing specs/plans):

docs/superpowers/specs/
docs/superpowers/plans/
docs/superpowers/README.md

Template README: farukzahra/agent-skills → reference/superpowers/docs-README.md (or local clone path).

3. Install skills

Run the sync script (installs all current farukzahra/agent-skills packages, including any newly added skills):

# From any machine with agent-skills cloned — relative to repo parent:
../agent-skills/scripts/sync-faruk-skills.ps1

Or manually:

npx skills experimental_install
npx skills add farukzahra/agent-skills -a cursor -y

(-y installs every skill in the package; omit skills-sh-maintainer outside agent-skills repo — the script handles that.)

  • No skills-lock.json → copy skills-lock.core.json from agent-skills, then experimental_install
  • Existing full lock → experimental_install only; do not overwrite

Stack skills (if missing from lock):

SignalAdd
Next.jsvercel-react-best-practices, frontend-design
Vuevue-best-practices, frontend-design
Prismaprisma-cli, prisma-client-api, prisma-database-setup, prisma-postgres
Playwrightplaywright-best-practices
Fastifynodejs-backend-patterns

4. Slash commands

Copy from agent-skills repo if missing:

  • reference/commands/commit-push.md → .cursor/commands/commit-push.md
  • reference/commands/init.md → .cursor/commands/init.md
  • reference/commands/recap.md → .cursor/commands/recap.md

Deploy config: docs/commit-push.json (see reference/commands/deploy-manifest.json).

5. Cursor rules (if .cursor/rules/ empty)

From Faruk Base: automate-before-manual.mdc, finish-task-dev-server.mdc.

6. Release history (web apps)

Create docs/release-history.json at 0.1.0 if missing. Bump only via /commit-push.

7. AGENTS.md

Append workflow table if missing — see reference/agents-snippet.md.

8. Report

List: folders created, skills installed, commands ready (/init, /commit-push, /recap), next step = brainstorming.

Do not

  • Run without user invoking /init
  • Overwrite lock, specs, or plans without permission
  • Commit or push (/commit-push handles ship)
  • Install skills-sh-maintainer outside agent-skills

Paths (Faruk local)

ItemPath
Agent-skills repo../agent-skills (sibling of project repos)
Secrets vault../secrets/ (never absolute paths in skills)
Sync all Faruk skills../agent-skills/scripts/sync-faruk-skills.ps1

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.