# Enhance Repo

> Use when the user asks to "enhance", "polish", "improve", or "level up" a repository. Runs a full repository health check and improves the project across docs, configuration, code quality, security, testing, performance, UI/UX, and developer experience. Triggers on keywords like "enhance repo", "improve repo", "polish", "make this repo production-ready".

- Skill: `xpressabhi/enhance-repo` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xpressabhi/enhance-repo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xpressabhi/enhance-repo/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: xpressabhi (https://skillmd.com/u/xpressabhi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xpressabhi/enhance-repo

---


# Enhance Repo

A systematic workflow for upgrading a repository's quality, professionalism, and developer experience. Run the steps in order, adapting depth to the repo size and the user's goals.

## 1. Analyze the repository

- List the repo root (`.opencode`-style hidden dirs count too).
- Detect the stack: read `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, `Gemfile`, `*.csproj`, etc.
- Read the existing `README`, `LICENSE`, `CONTRIBUTING`, `AGENTS.md`, and CI configs to see what already exists.
- Note anything broken: missing files referenced by config, out-of-date versions, unused dependencies, missing license headers.

## 2. Fix the basics

- Ensure a `.gitignore` exists and covers build outputs, env files, and IDE noise for the detected stack.
- Ensure a `LICENSE` exists if the user wants one (ask which license if unclear — MIT by default).
- Add `README.md` if missing, with: project name, one-line description, badges (build, license, version), features, install/usage, API or examples, contributing link, license section.
- Add `CONTRIBUTING.md` with setup, test, and PR instructions.
- Add a minimal `SECURITY.md` (how to report vulnerabilities) and `CODE_OF_CONDUCT.md` for public repos.

## 3. Harden configuration

- Add or fix the editorconfig (`.editorconfig`) for consistent formatting.
- Add lint/format/tooling configs idiomatic to the stack (e.g. `eslint.config.*`, `.prettierrc`, `rustfmt.toml`, `ruff.toml`, `.golangci.yml`).
- Add `AGENTS.md` if the user wants AI agents to work in the repo; document build, test, and lint commands verbatim from the actual scripts.
- Add or improve CI (`.github/workflows/ci.yml` or equivalent): install deps, run lint, run tests, upload artifacts. Keep matrix small for small repos.

## 4. Improve code quality

- Check for obvious issues: TODO/FIXME markers, commented-out dead code, hardcoded secrets or absolute paths.
- Verify the documented build/test/lint commands actually run. Do NOT claim commands work without running them.
- Suggest dependency updates or replacements only if they are clearly beneficial; never churn dependencies without reason.

## 5. Developer experience

- Add a `Makefile`, `justfile`, or npm scripts for common tasks (`setup`, `dev`, `build`, `test`, `lint`) if missing and the stack supports it.
- Add issue/PR templates (`.github/ISSUE_TEMPLATE/`, `.github/PULL_REQUEST_TEMPLATE.md`) for public repos.
- Add a changelog convention (`CHANGELOG.md` or changelog generator config) for released projects.

## 6. Security checks

- Scan for hardcoded secrets: API keys, tokens, passwords, `AKIA*`/`ghp_*`/`sk-*` patterns, private keys, and connection strings in source, configs, and docs. Report findings (never print the secret value in full; redact it).
- Check `.gitignore` and `.dockerignore` cover env files (`.env`, `.env.*`, `*.pem`, `*.key`, credential stores). Warn if committed env files exist; ask before rewriting history.
- Inspect dependency manifests for known-vulnerable or unmaintained packages where clearly identifiable; suggest pinning or bumping. Do not run external scanners unless available offline.
- Verify authentication patterns: no default/weak credentials, no `Bearer` tokens in client-side code, secrets injected via env vars or secret managers, not config files.
- Check input handling: SQL query construction (flag string interpolation), shell command building (flag shell injection), `eval`/`exec` of user input, unsafe deserialization, missing output escaping (XSS vectors).
- Check the dependency update path exists: renovate/dependabot config or documented manual process.
- If the repo ships a web app: flag missing security headers, `https` enforcement, cookie flags (`HttpOnly`, `Secure`, `SameSite`), and obvious authorization gaps — describe fixes, only apply with user consent.

## 7. Testing & reliability

- Verify the test suite exists and runs; add the test command to the README and CI if missing.
- Flag untested critical paths (auth, payments, parsing, network boundaries) and suggest focused tests — add them only if the user asks.
- Check for a deterministic build: reproducible lockfiles (e.g. `package-lock.json`, `Cargo.lock`, `uv.lock`), pinned versions, no floating `latest` deps.
- Check error handling: swallowed exceptions, empty catch blocks, no logging for failures, missing retries/timeouts for network calls. Suggest improvements, apply minor ones.
- Add/verify structured logging config for services (log levels, no secrets in logs).

## 8. Performance & scalability

- Flag obvious inefficiencies: O(n²) loops over large collections, N+1 queries, blocking calls in async contexts, unbounded caches/queues, missing indexes on hot queries.
- For web assets: unminified bundles, missing cache headers, no pagination on list endpoints, no lazy loading for heavy pages.
- For server code: missing connection pooling, timeouts, or rate limiting.
- Only apply performance fixes when they are low-risk; otherwise report findings with suggested approach.

## 9. UI/UX checks (web/mobile apps)

- Verify the app renders at common viewport sizes (responsive/layout breakpoints); flag fixed widths, missing `viewport` meta, horizontal overflow.
- Check the primary user flows end-to-end (signup, login, main action, error state, empty state, loading state) and flag dead-ends, confusing labels, or missing feedback.
- Check accessibility (a11y): image `alt` text, form `label`/`htmlFor`, button/input semantics (not bare `div`s), keyboard navigation, focus states, color-contrast basics, `aria` attributes where needed. Flag issues; apply simple fixes.
- Check consistency: shared design tokens/theme instead of scattered hardcoded colors/spacing, consistent button/typography styles, consistent iconography.
- Check UX fundamentals: clear error messages with recovery paths, confirmation on destructive actions, empty/loading/error states everywhere, sensible default focus, `prefers-reduced-motion` respect.
- Check i18n readiness if the repo targets multiple locales: no hardcoded user-facing strings without an abstraction layer.
- Report UI findings as a prioritized list (must-fix vs. nice-to-have) rather than changing visual design without user approval.

## 10. Documentation & onboarding

- Verify README claims match reality (commands, screenshots, version numbers).
- Add a "Getting started" quickstart with copy-pasteable commands from first clone to running app.
- Add API documentation for public endpoints (OpenAPI/Swagger or docstrings); document env vars in `.env.example` with comments.
- Add architecture notes (`docs/architecture.md`) for repos past trivial size: main components, data flow, key decisions.
- Document troubleshooting: common errors and fixes, known issues.
- Keep `AGENTS.md` accurate: build/test/lint commands verbatim, repo layout, conventions.

## 11. Verify and report

- Re-run the project's test and lint commands to confirm nothing broke.
- Report a concise summary organized by area: what was added, what was changed, what was intentionally skipped, and follow-ups (e.g. "run `npm test` before pushing", "rotate the leaked key in .env.history").

## Guardrails

- Ask before creating a `LICENSE` (legal choice), before large refactors or dependency upgrades, and before applying security or UI/UX changes that alter behavior or design — those can be risky.
- Never introduce a toolchain the repo doesn't already use (e.g. no Docker for a plain library repo).
- Preserve existing conventions and formatting; match the repo's style.
- Do not generate placeholder content like "TODO: fill this" — write real, accurate content or omit.
- Redact secrets when reporting them (never echo full key values).
- Depth scales with repo size and purpose: a tiny library gets the core checks; a production web service gets the full pass. Say explicitly which checks you skipped and why.