# Portfolio Project Initializer

> Initialize or normalize a long-term personal portfolio website engineering baseline. Use when Codex is asked to prepare an existing or empty portfolio repository before feature work by inspecting current files and Git state, preserving existing code, ensuring a Vite + React + JavaScript + pnpm + Tailwind CSS setup, creating missing standard directories, enforcing public resource path rules, maintaining README/.gitignore, and validating with pnpm install/build/dev. Do not use for building pages, UI, animation, business logic, portfolio content, commits, pushes, or remote repository changes.

- Skill: `ybfq678-ui/portfolio-project-initializer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ybfq678-ui/portfolio-project-initializer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ybfq678-ui/portfolio-project-initializer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ybfq678-ui (https://skillmd.com/u/ybfq678-ui)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ybfq678-ui/portfolio-project-initializer

---


# Portfolio Project Initializer V2

## Scope

Prepare a personal portfolio website repository for long-term maintenance. This skill only handles engineering foundation: project inspection, standard directories, dependency/configuration completion, resource-path rules, maintenance files, validation, and Git readiness.

Do not create portfolio content, pages, UI design, animation, business logic, complex components, commits, pushes, remote changes, credentials, or repository ownership changes.

## Safety Rules

Inspect before editing. Never delete existing files. Never overwrite existing configuration or code. Preserve existing directories and structure; create only missing standard directories and append only clearly missing maintenance rules.

Stop and report before editing when any of these are present:

- Unknown user changes that could be overwritten
- Conflicting or partial frontend setup whose intent is unclear
- Existing files that scaffolding would need to replace
- A package-manager lockfile other than `pnpm-lock.yaml`
- Missing or suspicious Git user identity
- Any prompt for GitHub username, password, token, permissions, or remote changes

If the repository is dirty but changes are understandable and edits can be limited to new files or safe appends, proceed carefully and describe what will be touched before editing.

## Required Initial Inspection

Run targeted checks from the project root before making changes:

```bash
pwd
ls
find . -maxdepth 3 -type f -not -path './node_modules/*' -not -path './dist/*' -not -path './.git/*' | sort
find . -maxdepth 3 -type d -not -path './node_modules/*' -not -path './dist/*' -not -path './.git/*' | sort
test -f package.json && cat package.json
test -f vite.config.js && sed -n '1,220p' vite.config.js
test -d src && find src -maxdepth 3 -type f | sort
git status --short --branch
git config user.name || git config --global user.name
git config user.email || git config --global user.email
git remote -v
```

Classify the project:

- Empty or near-empty portfolio project
- Existing non-React project
- Partial Vite/React project
- Complete Vite/React project
- Unknown or unsafe project requiring confirmation

If the project is not empty, summarize what exists and what can be safely added before editing.

## Standard Portfolio Structure

Ensure these directories exist. Keep all existing directories and do not restructure:

```text
src/
  components/
  pages/
  layouts/
  styles/
  utils/
  assets/
public/
  images/
  videos/
  pdf/
projects/
```

Add `.gitkeep` only to empty standard directories that must be tracked. Do not add placeholder UI, pages, animations, business logic, or portfolio content.

## Technical Stack Standard

Default portfolio stack:

- Vite
- React
- JavaScript
- pnpm
- Tailwind CSS

Check these files:

- `package.json`
- `vite.config.js`
- `tailwind.config.js`
- `postcss.config.js`

When missing and safe, add minimal baseline files. When present, preserve existing settings and only add missing compatible pieces.

`package.json` should contain compatible scripts and dependencies:

```json
{
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "latest",
    "react-dom": "latest"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "latest",
    "vite": "latest",
    "tailwindcss": "latest",
    "postcss": "latest",
    "autoprefixer": "latest"
  }
}
```

Minimal Vite config:

```js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
});
```

Minimal Tailwind config:

```js
export default {
  content: ["./index.html", "./src/**/*.{js,jsx}"],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

Minimal PostCSS config:

```js
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};
```

If a minimal `src/styles/main.css` or equivalent global stylesheet already exists, preserve it. If adding Tailwind to a new stylesheet, include only:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

If no Vite/React entry exists and the project is empty or clearly incomplete, create only the minimum `index.html`, `src/main.jsx`, and neutral `src/App.jsx` needed for React to mount. Keep text generic and avoid portfolio sections or visual design.

Prefer pnpm. If `package-lock.json`, `yarn.lock`, or `bun.lockb` exists, stop and ask before switching package managers.

## Resource Rules

Keep resources separated:

- Images: `public/images/`
- Videos: `public/videos/`
- PDFs: `public/pdf/`
- Project materials or notes: `projects/`
- Bundled source assets: `src/assets/`

Public resource references must use project-relative public paths:

```text
/images/example.png
/videos/demo.mp4
/pdf/project.pdf
```

Forbidden in project code and documentation:

- `file:///`
- `C:\`, `D:\`, `E:\`, or other Windows drive paths
- `/Users/`
- Desktop-local absolute paths

Scan before finishing:

```bash
rg -n "file:///|[A-Z]:\\\\|/Users/|Desktop/" . -g '!node_modules' -g '!dist' -g '!pnpm-lock.yaml'
```

Replace unsafe resource references only when the correct project-relative public path is clear. Otherwise report the finding.

## Maintenance Files

Check `README.md` and `.gitignore`.

Ensure `.gitignore` exists and contains at least:

```gitignore
node_modules/
dist/
.env
.DS_Store
.vscode/
```

Append only missing ignore rules. Preserve existing project-specific rules.

Create a concise `README.md` only when absent. If one exists, do not rewrite it without explicit confirmation. A new README should state the project purpose, stack, and directory structure.

## pnpm Validation

Run validation after edits:

```bash
pnpm install
pnpm build
pnpm dev
```

Confirm:

- Dependencies install with pnpm
- Vite production build succeeds
- Vite dev server starts
- React entry renders
- Browser can access localhost

Stop the dev server before finalizing unless the user asks to leave it running. If network access, local port binding, or browser access is blocked by the environment, request approval when appropriate; otherwise report the exact command and limitation.

## Git Rules

Check:

```bash
git status --short --branch
git config user.name || git config --global user.name
git config user.email || git config --global user.email
git remote -v
```

Do not automatically commit, push, force push, add or change remotes, rename branches, or modify repository credentials. Do not stage files unless the user explicitly asks.

If Git is missing and the user clearly asked for repository initialization, run `git init` only after confirming the directory is the intended project root.

## Final Report

End with a concise report containing:

1. Current technical stack
2. Current project structure
3. Directories created
4. Files modified or created
5. Git status and identity check
6. Whether the project meets the long-term personal portfolio engineering standard
7. Recommended next development step

Mention explicitly that no page development, UI, animation, business logic, portfolio content, commit, push, or remote change was performed.