<p align="center">
<img src="docs/assets/logo/logo-icon.svg" alt="Agent Skills" width="120">
</p>
<p align="center">
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
<a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
<a href="https://github.com/luongnv89/skills/releases"><img src="https://img.shields.io/github/v/release/luongnv89/skills?label=version" alt="Latest Release"></a>
<a href="https://github.com/luongnv89/skills"><img src="https://img.shields.io/github/stars/luongnv89/skills?style=social" alt="GitHub Stars"></a>
</p>
# Install expert workflows for AI coding agents
One command drops a tested, versioned skill into your agent. No more ad-hoc prompts. The same rigorous steps run every time.
Skills are independent files. Works with Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, OpenCode, Google Antigravity (`install.sh:23`).
[**Browse catalog**](#skill-catalog) | [**Install**](#install)
---
## What's New in 4.2.0
This catalog release adds [github-pages-publish](skills/github-pages-publish/), which publishes or updates a static site on GitHub Pages through GitHub Actions in any repo, asks before creating a public repo, publishing from a private one or enabling Actions, and reports the URL only after the live site serves the committed files. Before release, its 1.0.2 stopped deleting just-published pages when a moved site overlaps the old one, learned to rewrite unquoted root-absolute links that minifiers emit, and gained a unit test suite that runs in CI. [lstack](packages/lstack/README.md) 0.6.0 adds it for 43 skills and gives the plugin an icon for its Claude Code plugin directory listing. Eval fixtures move to `eval-fixtures/<skill>/` at the repository root, which keeps the `skills/` plugin folder under the directory's 512-file limit. Individual skills keep their own versions; the catalog release does not reset them to 4.2.0.
**Upgrading from 4.1.0:**
- Add the new skill: `npx skills@1.7.0 add https://github.com/luongnv89/skills --skill github-pages-publish`. Skills you already installed are unchanged.
- If you installed lstack from this repository's marketplace, run `claude plugin marketplace update lstack`, then `claude plugin update lstack@lstack --scope user`, and restart Claude Code to get 0.6.0. ZIP users download `lstack-0.6.0.zip`, `lstack-claude-0.6.0.zip` or `lstack-codex-0.6.0.zip` from the [v4.2.0 release](https://github.com/luongnv89/skills/releases/tag/v4.2.0) and install them as before.
- Contributors: put eval input fixtures in `eval-fixtures/<skill>/`, never under `skills/`, and point `evals/evals.json` `files` entries at `../../eval-fixtures/<skill>/` (see [CONTRIBUTING.md](CONTRIBUTING.md)).
**Earlier upgrade guidance (from 4.0.0):**
- If you load lstack from a clone with `--plugin-dir`, point it at the clone's `skills/` folder instead of the repository root: `claude --plugin-dir /absolute/path/to/checkout/skills`. ZIP downloads install as before.
- If you installed lstack from this repository's marketplace, run `claude plugin marketplace update lstack`, then `claude plugin update lstack@lstack --scope user`, and restart Claude Code.
**Earlier upgrade guidance (from 3.0.0):**
- Install [**ship**](skills/ship/docs/README.md): `npx skills@1.7.0 add https://github.com/luongnv89/skills --skill ship`, then replace `/release-manager` invocations with `/ship`.
- Review and remove the obsolete installed `release-manager` copy yourself; reinstalling does not remove it automatically, and both names can compete for triggers.
- `/ship [X.Y.Z|major|minor|patch]` runs autonomously by default. Use `/ship --no-auto` to keep step-by-step confirmations.
**Earlier upgrade guidance (from 2.0.0):**
- `herdr-agent-comms` is now [**herdr-agent**](skills/herdr-agent/). Reinstall under the new name and update prompts; installers do not automatically remove the old installed copy, which can still trigger.
- `plan-to-issues` moved to [luongnv89/idd](https://github.com/luongnv89/idd); see the [installation note](#product-planning). Its epic output is now a static plan map with status maintained through native GitHub sub-issues. Update parsers expecting `- [x] #N — <id>` to accept `- #N — <id>`.
- [**cleanup-project**](skills/cleanup-project/docs/README.md#migrating-from-branch-inspector) replaces `branch-inspector`. `convert-documents-to-markdown`, `fork-upstream-sync`, `opencode-sandbox`, `opencode-handoff`, `subagent-creator`, and the `website-cloner` suite are retired from this catalog. Existing installed copies are not automatically removed.
See [CHANGELOG.md](CHANGELOG.md) for the full release history.
---
## Install
> Validate this runbook: `./scripts/validate-install.sh --check`
### lstack: direct Claude Code plugin
[lstack 0.6.0](packages/lstack/README.md) packages the canonical `skills/` tree as one
Claude Code plugin: 43 top-level definitions plus the two nested diagram-generator
children, **45** namespaced skills in total. `skills/` is the plugin folder; the root
marketplace points at it.
```bash
claude plugin marketplace add luongnv89/skills
claude plugin install lstack@lstack --scope user
```
For one session from a trusted local checkout, run
`claude --plugin-dir /absolute/path/to/checkout/skills`. Skills appear as
`/lstack:code-review`, `/lstack:drawio-generator`, and so on. Upgrading from lstack
0.4.0 or earlier: `--plugin-dir` now takes the checkout's `skills/` folder, not the
repository root.
Some members edit files, commit and push, install tools, call APIs or open GitHub
issues and PRs, each behind its own approval gates.
[skills/README.md](skills/README.md#what-each-skill-runs-sends-or-fetches) lists what
each skill runs, sends or fetches.
Updates, Codex builds, ZIP exports, external prerequisites and directory-portal caveats
are in the [lstack runbook](packages/lstack/README.md). Maintainers regenerate and check
the plugin metadata from `packages/lstack/manifest.json` with:
```bash
python3 scripts/build-lstack.py --write-plugin-metadata
python3 scripts/build-lstack.py --check-plugin-metadata
```
### Standalone skills (other agents or selected members)
Pick one, several, or the whole catalog:
```bash
npx skills@1.7.0 add https://github.com/luongnv89/skills --skill code-review
npx skills@1.7.0 add https://github.com/luongnv89/skills --skill code-review --skill auto-push --skill test-coverage
npx skills@1.7.0 add https://github.com/luongnv89/skills
```
### agent-skill-manager
Use [agent-skill-manager](https://github.com/luongnv89/agent-skill-manager) (`asm`) for a single TUI/CLI across agents:
```bash
npm install -g agent-skill-manager
asm install github:luongnv89/skills
```
```bash
asm search # find by name or description
asm list # show installed skills
```
<details>
<summary>Other install methods</summary>
**Remote (no clone)**
```bash
curl -sSL https://raw.githubusercontent.com/luongnv89/skills/main/remote-install.sh | bash
```
Non-interactive:
```bash
curl -sSL https://raw.githubusercontent.com/luongnv89/skills/main/remote-install.sh | bash -s -- \
--skills "code-review,auto-push" --tools "Claude Code" --scope global
```
**Clone + local**
```bash
git clone https://github.com/luongnv89/skills.git
cd skills && bash install.sh
```
</details>
---
## How It Works
```mermaid
graph TD
A[User request or trigger phrase] --> B[Agent matches skill name]
B --> C[Loads SKILL.md + references/]
C --> D[Follows exact steps + templates]
D --> E[Quality gates + artifacts]
E --> F[Report / plan / files / PR links]
```
A skill is a self-contained playbook: frontmatter metadata, instructions, optional scripts, and reference docs. The installer copies it to the right path for your agent.
---
## Key Features
| Feature | What you get |
|---|---|
| Standalone | Any mix installs cleanly; zero shared runtime |
| Versioned | Per-skill semver + catalog release history |
| Structured | Steps, templates, checklists, self-validation |
| Tool-agnostic | Same skill works in Claude Code, Cursor, Windsurf, Codex, Copilot |
| Scannable | Tables, diagrams, short outputs |
| Suite support | Multi-phase products (e.g. diagram-generator) with independent phases |
---
## Skill Catalog
Every skill is standalone. Install one or many.
Use:
```bash
npx skills@1.7.0 add https://github.com/luongnv89/skills --skill <name>
```
### Find by Task
One skill to invoke per task. The task skills call the related skills for you. In the two
web task skills, evidence is captured once, the live scan runs at most once, overlapping checks
are skipped where the member supports skip-checks, and remaining overlaps are merged into one
row per defect.
| Task | Invoke | It runs |
|---|---|---|
| Optimize a website/app design | [**design-optimizer**](skills/design-optimizer/) | dont-make-me-think · ux-ax-review · viral-product-evaluator · website-agent-readiness, then frontend-design only if you opt in to apply fixes |
| Optimize for SEO, AI-bot or app-store search | [**search-optimizer**](skills/search-optimizer/) | Web: seo-ai-optimizer · website-agent-readiness · viral-product-evaluator. App store: aso-marketing · viral-product-evaluator |
| Take an idea to a build plan | [**product-planner**](skills/product-planner/) | idea-validator → prd-generator → (brand-name-checker) → tad-generator → tasks-generator, resuming from the furthest existing artifact |
| Review or improve code | [**code-review**](skills/code-review/) | One skill, four modes: review, perf, clean, cleanup |
| Draw a diagram | [**diagram-generator**](skills/diagram-generator/) | Routes to drawio-generator or excalidraw-generator |
These other task areas don't have a task skill. Each skill in them stands alone, so invoke them in this order:
| Task | Skills, in order |
|---|---|
| Prepare an app store submission | aso-marketing → appstore-assets → appstore-review-checker |
| Harden and ship a repo | security-setup → devops-pipeline → ship (auto-push and cleanup-project for day-to-day work) |
| Open-source a project | oss-ready → doc-manager → landing-page-generator → github-pages-publish |
| Brand and launch | brand-name-checker → logo-designer → landing-page-generator → github-pages-publish |
| Run an agent fleet | herdr-agent *or* rex-agent *or* tmux-agent-comms (alternative backends) · issue-work-loop (Herdr) · opencode-runner |
### Find by Category
| Category | What it covers |
|---|---|
| [Code Quality](#code-quality) | Reviews, cleanup, testing, optimization, usability |
| [Shipping](#shipping) | Auto push, repo cleanup, pipelines, releases, GitHub Pages publishing, security hardening |
| [Product Planning](#product-planning) | Validation, PRDs, architecture, tasks, naming |
| [Career Research](#career-research) | Tailored job discovery with employer/product due diligence |
| [Frontend & Design](#frontend--design) | UIs, logos, diagrams, design optimization |
| [Documentation](#documentation) | Docs gen, READMEs, SEO, OSS prep, agent config |
| [App Store](#app-store) | ASO, screenshots and creative assets, review compliance |
| [Tooling](#tooling) | CLIs, installers, local models, agent comms |
### Code Quality
| Skill | Version | Effort | What it does |
|---|---|---|---|
| [**code-review**](skills/code-review/) | 2.2.2 | high | Review or improve code — 4 modes: bugs/security, performance, clean-code audit, slop cleanup |
| [**codebase-modernizer**](skills/codebase-modernizer/) | 1.4.1 | max | Whole-repo audit + phased, testable plan to modernize a stale or messy codebase |
| [**test-coverage**](skills/test-coverage/) | 1.5.0 | low | Target untested branches and edge cases |
| [**user-test**](skills/user-test/) | 1.0.1 | high | Launch an app, API or CLI and test every feature as a real user; log bugs, perf and UX issues with evidence; fix and verify simple ones; report with a plan |
| [**dont-make-me-think**](skills/dont-make-me-think/) | 1.6.0 | medium | Usability review using Krug's principles |
| [**ux-ax-review**](skills/ux-ax-review/) | 1.2.0 | high | Evidence-backed human UX + AI/search AX audit and approval-gated improvement plan |
**`code-review` has four modes** — pick by intent or pass `mode:<name>`:
| I want to... | Mode | It... |
|---|---|---|
| Find bugs, security, or quality issues in a diff | `review` (default) | reads + reports prioritized findings |
| Make code faster / fix perf bottlenecks | `perf` | reads + reports performance fixes |
| Audit readability/standards vs the Clean Code cheat sheet | `clean` | writes an audit report (`CLEAN_CODE_AUDIT.md`) |
| Actually apply cleanup / refactor out AI slop & cruft | `cleanup` | **writes code** (8-subagent refactor) |
**`code-review` or `codebase-modernizer`?** Scope decides. `code-review` inspects a diff, a PR, or a
file set and reports findings. `codebase-modernizer` audits the *whole repo* across all ten
dimensions — including dependency and runtime currency, which nothing else here covers — and converts
the findings into a phased sprint plan with milestones. It is read-only: dependency upgrades become
planned tasks with migration steps, never a bulk `npm update`. Reach for it when returning to a
neglected project or untangling one that has drifted.
Adjacent skills: **test-coverage** (generate tests for untested branches) · **user-test** (run the app and test it as a user) · **dont-make-me-think** (usability/UX review).
### Shipping
| Skill | Version | Effort | What it does |
|---|---|---|---|
| [**auto-push**](skills/auto-push/) | 1.1.1 | low | Commit message + stage + push with secret and size checks |
| [**cleanup-project**](skills/cleanup-project/) | 1.0.2 | high | Review uncommitted changes, update ignore files, delete merged branches locally and on origin, end on clean main |
| [**devops-pipeline**](skills/devops-pipeline/) | 2.3.0 | medium | Pre-commit + GitHub Actions quality gates |
| [**github-pages-publish**](skills/github-pages-publish/) | 1.0.2 | high | Publish or update a static site on GitHub Pages via GitHub Actions in any repo; URL returned only after a live check |
| [**security-setup**](skills/security-setup/) | 1.5.0 | high | Local pre-commit secret scans, dep checks, static analysis, gated CI |
| [**ship**](skills/ship/) | 3.0.1 | max | Autonomous release: version bumped everywhere, changelog, docs and landing page, tag, GitHub release, publish |
### Product Planning
| Skill | Version | Effort | What it does |
|---|---|---|---|
| [**product-planner**](skills/product-planner/) | 1.1.0 | high | One run from idea to sprint tasks: idea-validator → prd-generator → tad-generator → tasks-generator, resuming from existing files |
| [**idea-validator**](skills/idea-validator/) | 1.6.0 | max | Market, feasibility, competitor checks for ideas |
| [**viral-product-evaluator**](skills/viral-product-evaluator/) | 1.7.0 | high | Score codebase + landing page vs 32 viral principles |
| [**brand-name-checker**](skills/brand-name-checker/) | 1.5.0 | max | Trademark, domain, social, registry conflicts |
| [**prd-generator**](skills/prd-generator/) | 1.5.0 | max | Structured PRD from idea or validate notes |
| [**tad-generator**](skills/tad-generator/) | 1.6.0 | max | Technical architecture document from PRD |
| [**tasks-generator**](skills/tasks-generator/) | 1.5.0 | max | Sprint tasks and plan from PRD |
> **`plan-to-issues` moved to [luongnv89/idd](https://github.com/luongnv89/idd)** (idd#502), next to the `issue-creator` it depends on: `asm install https://github.com/luongnv89/idd --skill plan-to-issues`, or the idd Claude Code plugin.
### Career Research
| Skill | Version | Effort | What it does |
|---|---|---|---|
| [**ai-job-scout**](skills/ai-job-scout/) | 1.1.1 | high | Rank open AI roles for a candidate; verify location and application links; assess each company's product, project, and technical interest with cited evidence; filterable HTML report for larger searches |
### Frontend & Design
| Skill | Version | Effort | What it does |
|---|---|---|---|
| [**frontend-design**](skills/frontend-design/) | 1.4.0 | high | Production UIs with usability-first approach |
| [**logo-designer**](skills/logo-designer/) | 1.4.0 | medium | 7 SVG logo variants from project context |
| [**diagram-generator**](skills/diagram-generator/) | 1.4.0 | high | One entry point for diagrams — routes to draw.io XML or Excalidraw JSON |
| [**design-optimizer**](skills/design-optimizer/) | 1.1.0 | high | One run to optimize a website/app design: usability, UX/AX, virality, agent readiness, opt-in fixes |
**Diagram generator engines** (install the umbrella or a single engine):
| Engine | Version | What it does |
|---|---|---|
| drawio-generator | 1.4.0 | draw.io XML — precise, editable, C4, swimlanes |
| excalidraw-generator | 1.5.0 | Excalidraw JSON — hand-drawn, sketch, wireframes |
### Documentation
| Skill | Version | Effort | What it does |
|---|---|---|---|
| [**doc-manager**](skills/doc-manager/) | 2.1.1 | medium | Generate/update docs to match code, cited to path:line, never invented |
| [**landing-page-generator**](skills/landing-page-generator/) | 1.7.0 | high | Landing pages: marketing copy from a brief, or a README-to-landing rewrite, with privacy, terms, changelog, and docs pages, built as HTML with frontend-design |
| [**search-optimizer**](skills/search-optimizer/) | 1.1.0 | high | One run to optimize SEO, AI-bot and app-store search: web or store branch, one merged report |
| [**seo-ai-optimizer**](skills/seo-ai-optimizer/) | 1.6.0 | high | Technical SEO + AI-bot directives |
| [**website-agent-readiness**](skills/website-agent-readiness/) | 1.4.0 | high | Scan a live site for agent readiness, plan the gaps, file them as issues |
| [**oss-ready**](skills/oss-ready/) | 1.4.0 | low | Add OSS files and templates |
| [**agent-config**](skills/agent-config/) | 2.2.0 | medium | AGENTS.md by default (CLAUDE.md on request), shadow-checked and evidence-pruned |
### App Store
| Skill | Version | Effort | What it does |
|---|---|---|---|
| [**aso-marketing**](skills/aso-marketing/) | 1.4.0 | max | App Store + Google Play keyword and metadata optimization |
| [**appstore-assets**](skills/appstore-assets/) | 1.0.0 | high | Upload-ready App Store screenshots and creative assets for iPhone, iPad and Mac, from code or a landing page |
| [**appstore-review-checker**](skills/appstore-review-checker/) | 1.5.0 | high | Pre-submission audit vs Apple guidelines |
### Tooling
| Skill | Version | Effort | What it does |
|---|---|---|---|
| [**cli-builder**](skills/cli-builder/) | 1.3.0 | high | 5-step CLI tool builder with approval gates and btop-inspired output |
| [**ollama-optimizer**](skills/ollama-optimizer/) | 1.3.0 | medium | Hardware-aware Ollama tuning |
| [**install-script-generator**](skills/install-script-generator/) | 2.3.0 | high | Cross-platform install.sh with env detection |
| [**opencode-runner**](skills/opencode-runner/) | 1.6.0 | medium | Delegate work to opencode free cloud models |
| [**herdr-agent**](skills/herdr-agent/) | 3.2.0 | medium | Manage Herdr agent fleets: tile panes, message/wait/read, steer, `help` |
| [**rex-agent**](skills/rex-agent/) | 1.0.0 | medium | Manage Rex agent fleets: equal columns, prompt/wait/read via program status, steer, `help` |
| [**issue-work-loop**](skills/issue-work-loop/) | 1.6.0 | max | Resolve one GitHub issue via a Herdr implementer→reviewer loop until CLEAN |
| [**tmux-agent-comms**](skills/tmux-agent-comms/) | 2.4.0 | medium | Spawn, message, read CLI agents in tmux |
| [**dev-machine-setup**](skills/dev-machine-setup/) | 0.10.0 | high | Gap-driven dev machine setup/tune-up across macOS, Linux, Windows |
---
## Suite Folders
Most skills are `skills/<name>/`. Multi-phase products live under a suite folder: umbrella at `skills/<umbrella>/` + phases at `skills/<umbrella>/<phase>/`.
Current suite: [diagram-generator](skills/diagram-generator/) (draw.io + Excalidraw engines behind one router). Install the umbrella or any child. Installers discover both levels.
Task orchestrators ([design-optimizer](skills/design-optimizer/), [search-optimizer](skills/search-optimizer/), [product-planner](skills/product-planner/)) stay flat at `skills/<name>/`. Their members are ordinary top-level skills, and a member can belong to more than one task: viral-product-evaluator and website-agent-readiness serve both design and search. Each orchestrator checks for its members in a Dependency Preflight and tells you how to install any that are missing.
Mirror the layout for your own multi-skill products.
---
## Project docs
| Doc | Purpose |
|---|---|
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribute skills; structure and versioning |
| [docs/guide-building-agent-skills.md](docs/guide-building-agent-skills.md) | Authoring guide (plan → write → validate → distribute) |
| [docs/brand_kit.md](docs/brand_kit.md) | Logo files, colors, typography |
| [docs/DECISIONS.md](docs/DECISIONS.md) | Doc ambiguity resolutions |
| [docs/troubleshooting.md](docs/troubleshooting.md) | Install/setup validation fixes |
| [docs/archive/](docs/archive/) | Historical work notes (not current product docs) |
| [CHANGELOG.md](CHANGELOG.md) | Release history |
| [SECURITY.md](SECURITY.md) | Vulnerability reporting |
| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards |
## FAQ
**Do I need every skill?**
No. Pick only what you need. All are independent.
**Which agents work?**
Any that load external skill files. Installer tools (`install.sh:23`): Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, OpenCode, Google Antigravity.
**How do I make my own?**
Follow [CONTRIBUTING.md](CONTRIBUTING.md), [docs/guide-building-agent-skills.md](docs/guide-building-agent-skills.md), or patterns from existing skills.
**Do skills change my runtime code?**
No. They only guide the agent during development.
---
<details>
<summary><b>Supported Tool Paths</b> (`install.sh:218-321`)</summary>
| Tool | Global | Project |
|---|---|---|
| Claude Code | `~/.claude/skills/<skill>/` | `.claude/skills/<skill>/` |
| Cursor | `~/.agents/skills/<skill>/` + `.cursor/rules/<skill>.mdc` | same |
| Windsurf | `~/.agents/skills/<skill>/` + `.windsurf/rules/<skill>.md` | same |
| GitHub Copilot | `~/.agents/skills/<skill>/` + `.github/instructions/<skill>.instructions.md` | same |
| OpenAI Codex | `~/.agents/skills/<skill>/` + `~/.codex/AGENTS.md` | same |
| OpenCode | `~/.agents/skills/<skill>/` | same |
| Google Antigravity | `~/.agents/skills/<skill>/` | same |
</details>
<details>
<summary><b>Project Structure</b></summary>
```
.
├── skills/ # Skill sources; also the lstack Claude plugin folder
│ ├── <name>/
│ │ ├── SKILL.md # Required: frontmatter + instructions
│ │ ├── references/ # Loaded on demand
│ │ ├── scripts/ tests/ # Optional helpers and their tests
│ │ ├── agents/ # Optional subagent prompts
│ │ ├── evals/ # evals.json trigger/behavior suites
│ │ └── docs/README.md # Human-facing docs
│ ├── <umbrella>/<child>/ # Suite children (install.sh:44-46)
│ ├── README.md # Plugin directory listing page
│ └── .claude-plugin/ # Generated plugin.json
├── packages/lstack/ # lstack manifest + runbook
├── scripts/ # Build, validation and eval runners
├── tests/ # lstack packaging tests
├── docs/ # GitHub Pages site, guides, brand assets
├── examples/ # Worked examples (logo-designer case study)
├── .claude-plugin/ # Root marketplace.json
├── .claude/agents/ # Maintainer subagents for this repo
└── install.sh / remote-install.sh
```
</details>
<details>
<summary><b>Acknowledgements</b></summary>
- frontend-design draws from Anthropic's patterns.
- Many skills follow the conventions established in the skill-creator lineage.
</details>
---
<p align="center">
<a href="https://luongnv.com">Website</a> ·
<a href="https://github.com/luongnv89/claude-howto">Claude How-To</a> ·
<a href="https://medium.com/@luongnv89">Blog</a>
</p>
Read the source README