Agent Skills for independent developers — teach your AI coding agent how to validate, interview, smoke-test, specify, and grow a product, not only how to write code.
Languages: English (this file) · 中文说明
Independent developers now have something previous generations did not: AI agents that can write large amounts of software quickly.
That creates a new failure mode.
| Easy (with AI) | Still hard (and still decides outcomes) |
|---|---|
| Scaffold an app | Know whether anyone needs it |
| Ship features | Talk to real users without fooling yourself |
| Polish UI | Test demand before months of build |
| Refactor forever | Write a buildable product definition |
| Generate blog posts | Earn attention with honest search strategy |
First principle: code is leverage on a decision. If the decision is wrong, more code multiplies waste.
Most agent tools optimize the left column. zstack optimizes the right column — the product-judgment loop that solo founders cannot afford to skip.
You do not need to be an AI engineer to use this.
Think of a skill as a playbook your agent loads on demand:
- You select
z-market-validatewith your host's syntax (/in Claude/Grok,$in Codex), or describe the intent in plain language. - The agent opens a
SKILL.mdfile — a structured set of steps, checklists, and quality bars. - It follows that playbook with its normal tools (search, edit files, run commands).
- You get a repeatable workflow, not a one-off chat that evaporates next week.
For practitioners: skills follow the common Agent Skills convention (name + description frontmatter + markdown body). One source file installs into Claude Code, Codex, and Grok-compatible skill roots via symlink. See ARCHITECTURE.md for host discovery paths, frontmatter policy, and install model.
zstack is an open-source collection of original skills aimed at one-person companies and indie builders.
It is:
- A product workflow pack (validate → discover → smoke-test → specify → SEO)
- Portable across major AI coding agents
- Installable with one script
- Versioned in git so your playbooks improve over time
It is not:
- A replacement for general engineering packs such as gstack (
/qa,/ship,/browse, …) — use those for engineering factory work; use zstack for product truth - A dump of vendored third-party skills
- A hosted SaaS or a separate agent product you must run as a service
| You will feel at home if… | You may want something else if… |
|---|---|
| You build alone or nearly alone | You need a full enterprise product-ops suite |
| You use Claude Code, Codex, or Grok Build | You only want model prompts with no install story |
| You have been burned by “AI-built apps nobody wants” | You only need code review / browser QA (try gstack) |
| You want process that compounds across projects | You want a black-box “AI CEO” with no inspectable steps |
zstack skills are designed to chain. You can enter at any step; the default path is:
Idea (half-baked is fine)
│
▼
z-market-validate ← public signals: is anyone complaining / paying?
│
▼
z-customer-discovery ← real humans, Mom Test: past behavior, not compliments
│
▼
z-landing-smoke ← cheapest behavior test: page + waitlist / pre-order
│
▼
z-write-prd ← only then: a buildable product definition
│
▼
build (your stack + your engineering skills)
│
▼
z-seo-plan ← when there is something worth finding in search
Why this order?
- Public signal is cheap and kills obvious non-problems.
- Interviews produce truth you cannot scrape — and catch self-deception.
- Smoke tests ask for behavior (email, money), not opinions.
- PRDs without the above often document fiction with high confidence.
- SEO on a wrong product is paid advertising for a dead end.
Every skill id starts with z- so it does not collide with other packs on the same machine.
| Skill | Skill id | In plain language | Deeper purpose |
|---|---|---|---|
| z-market-validate | z-market-validate |
“Is this idea even worth a week?” | Multi-channel demand scan (X, Reddit, HN, PH, …), pro and con evidence, indie fit, 30–90 day return odds, entry wedge |
| z-customer-discovery | z-customer-discovery |
“Talk to 5–15 real people without fooling yourself” | Mom Test coaching: recruit, interview guide, debrief, synthesis on pain / existing spend / switch willingness |
| z-landing-smoke | z-landing-smoke |
“Cheapest way to see if anyone cares” | English landing + waitlist/pre-order, traffic plan, conversion & kill criteria before a large build |
| z-write-prd | z-write-prd |
“Turn notes into something you can build” | Indie-sized PRD: problem, scope, FR IDs, acceptance criteria, non-goals, milestones |
| z-seo-plan | z-seo-plan |
“What should we actually try to rank for?” | Keyword research from PRD/URL/code, primary terms, page map, on-page & technical notes — no fake volume numbers |
Each skill ships with references/ (templates, quality bars, playbooks). Read those when you want the full methodology; the agent is instructed to load them during a run.
- macOS or Linux. On Windows, use WSL; native Windows is not currently tested.
- Git
- At least one of: Claude Code, OpenAI Codex, Grok Build
bash(for install/doctor scripts)- Ruby 2.6+ for contributor tests, strict YAML/evidence validation, and routing evaluation tooling; basic install/unlink remains Bash-only
git clone https://github.com/zh30/zstack.git ~/code/zstack
cd ~/code/zstack
./scripts/setup.sh
./scripts/doctor.shdoctor.sh reports every problem it finds by default. Use --source-only to
skip installed-link checks, or --fail-fast to stop at the first error during
focused iteration.
setup.sh symlinks each active catalog skill into the current required discovery
roots. Optional compatibility profiles are available through --hosts:
| Profile | Root | Default | Why |
|---|---|---|---|
| Agent Skills hub | ~/.agents/skills/ |
Yes | Current Codex user root; also discovered by Grok |
| Claude Code | ~/.claude/skills/ |
Yes | Claude Code user root; also compatible with Grok |
| Legacy Codex | ~/.codex/skills/ |
No | Older compatibility root: ./scripts/setup.sh --hosts codex |
| Explicit Grok | ~/.grok/skills/ |
No | Optional dedicated root: ./scripts/setup.sh --hosts grok |
An explicit --hosts selection enables an optional profile. Later default runs
leave that unselected root untouched.
Edit a skill under skills/ and every host sees the change immediately (symlink).
Conflicts are skipped and make setup exit non-zero; pass --force to preserve
the old path as *.zstack-backup-*/original inside an atomically reserved,
timestamped backup directory. If link creation then fails, setup restores the
original path. Managed global and --project links are recorded for cleanup:
./scripts/unlink.shUnlinking never removes conflict backups or non-symlink content. Re-running setup reconciles only the selected host roots: links for skills that became draft/deprecated or lost that host are removed, while unselected hosts and other zstack clones are left untouched.
Explicit invocation differs by host:
Claude / Grok: /z-market-validate
Codex: $z-market-validate
Natural language is portable across hosts:
Run customer discovery setup for ICP: independent design consultants.
Pain: weekly client reporting. Target 10 interviews.
┌──────────────────────────┐
│ This git repo │
│ skills/z-*/SKILL.md │ ← source of truth
└────────────┬─────────────┘
│ ./scripts/setup.sh (symlink)
┌───────┴────────┐
▼ ▼
~/.agents/skills ~/.claude/skills
Codex + Grok Claude + Grok
Optional explicit compatibility roots: ~/.codex/skills, ~/.grok/skills
Design choices (first principles):
| Choice | Why |
|---|---|
| Markdown playbooks, not a new runtime | Agents already execute; we constrain judgment |
| Symlink install | One edit, all hosts; no stale copies |
z- prefix |
Shared skill directories are crowded; namespaces prevent collisions |
| Original skills only | Quality and licensing stay coherent for open source |
| Current roots by default | Codex uses ~/.agents; Claude uses ~/.claude; Grok discovers both |
| Legacy roots are opt-in | Avoid unsupported duplicate installs while retaining older Codex and explicit Grok compatibility |
| Evidence over vibes | Skills force disconfirming search, Mom Test rules, kill criteria |
Deeper internals: ARCHITECTURE.md · authoring: docs/authoring.md · agent rules for contributors: AGENTS.md.
zstack/
├── README.md # You are here (English)
├── README.zh-CN.md # Chinese
├── ARCHITECTURE.md # Multi-host design
├── AGENTS.md # Rules when AI edits this repo
├── CONTRIBUTING.md # Contribution workflow and quality gates
├── catalog.yaml # Skill registry
├── hosts/ # Per-agent install profiles
├── evals/
│ ├── cases.yaml # Behavioral regression prompts and criteria
│ ├── routing.yaml # Description-only skill-selection cases
│ └── runs/ # Dated clean-context responses and grades
├── scripts/
│ ├── setup.sh # Install / refresh symlinks
│ ├── doctor.sh # Validate skills + links
│ ├── test.sh # Installer + validator integration tests
│ ├── new-skill.sh # Scaffold z-* skill
│ ├── unlink.sh # Remove zstack-managed links only
│ ├── check-evidence-docs.rb # Keep visible host counts aligned with evidence
│ ├── report-evidence-coverage.rb # Behavioral/routing provenance matrices
│ ├── run-behavioral-evals.rb # Shared isolated behavioral-runner core
│ ├── run-{codex,claude,grok}-behavioral-evals.rb # Host entry points
│ ├── archive-behavioral-run.rb # Shared reviewed-archive core
│ ├── archive-{codex,claude,grok}-behavioral-run.rb # Host entry points
│ ├── run-routing-evals.rb # Shared isolated description-routing core
│ ├── run-{codex,claude,grok}-routing-evals.rb # Host entry points
│ ├── archive-routing-run.rb # Shared atomic routing-archive core
│ ├── archive-{codex,claude,grok}-routing-run.rb # Host entry points
│ ├── generate-evidence-manifests.rb # Rebuild / check whole eval archives
│ ├── validate-yaml.rb # Optional strict YAML + duplicate-key validation
│ ├── validate-evidence.rb # Eval archive JSON / byte / SHA-256 validation
│ └── lib/ # Shared parsing + stable eval/evidence input contracts
├── skills/
│ ├── _template/
│ ├── z-market-validate/
│ ├── z-customer-discovery/
│ ├── z-landing-smoke/
│ ├── z-write-prd/
│ └── z-seo-plan/
└── docs/
├── authoring.md
├── compatibility.md
├── evidence-handoff.md
├── evaluation.md
└── frontmatter.md
./scripts/new-skill.sh z-my-workflow product
# edit SKILL.md and customize the generated references/quality-bar.md
# review the auto-created draft in catalog.yaml
# add three behavioral (including happy-path) + two routing cases, then activate
./scripts/test.sh
./scripts/setup.shRules of thumb:
- Name = directory = portable skill id; must match
z-[a-z0-9-]+. descriptionis the API for auto-invocation — put triggers in it.- Write the body for any host: prefer “run this command / read this file” over host-specific tool brand names.
- Put long material in
references/; keepSKILL.mdexecutable. - No secrets, no machine-local absolute paths.
- New scaffolds include the Evidence handoff and quality-bar baseline, but intentionally fail validation until skill and catalog placeholders are replaced; draft skills do not require behavioral or routing eval cases yet.
Pull requests are welcome; see CONTRIBUTING.md for the
original-content policy, required checks, and smoke-test evidence.
Behavioral and routing test methodology lives in
docs/evaluation.md.
Archived runs preserve the model response separately from its grade; the
host compatibility evidence links the current run
matrix. A passing archive is evidence for that runner and date, not a guarantee
across every model or host. The latest Codex routing evidence includes a
context-budget regression
and a Chinese routing regression,
both with raw selections preserved.
The same routing protocol now has a reviewed
Grok 25-case matrix
covering all English, Chinese, boundary, and no-match requests with complete
provenance.
The complete-output happy-path run
passed all five skills with raw artifacts preserved.
The reviewed Codex resilience matrices A
and B
first brought complete-provenance behavioral coverage to 20/20 cases at their
August 1 source snapshot.
The subsequent host-gap audit
preserved three passes and one real artifact failure; the isolated
artifact rerun
retains the deployable page and closed Codex-specific coverage at 20/20 for
that snapshot.
The same snapshot, anti-leak, review, and atomic-archive protocol now has a
Claude Code adapter that records requested versus actual model ids and rejects
API errors even when the host wraps them in a nominal success result.
At the 2026-08-02 local recheck, the Claude provider rejected its configured
models before generation; the runner reported this as a redacted
model-unavailable failure rather than counting external configuration as
skill evidence.
The Grok adapter adds an isolated host home with a bounded stable auth copy,
anonymous-descriptor prompt-file transport, an exact
final-response boundary, tool/sandbox controls, redacted API-error categories,
and the same private-provenance checks. Its reviewed
19-case response matrix
remains historical evidence for the earlier skill snapshot. The retained
landing artifact failure
triggered stricter provider-confirmed-success rules. Progressive-disclosure
edits later changed all five skill bodies, so all 20 behavior cases now need a
fresh Grok rerun. Grok CLI 0.2.118 returns HTTP 401 before generation, leaving
the 2026-08-02 recheck at 0/20 current-source Grok behavior cases.
Deterministic adapter fixtures do not count as model evidence. A retained
provider-schema failure
then exposed a guessed Buttondown tag-ID contract. The skill now requires dated
official provider semantics or an explicit launch-blocking VERIFY_* mapping.
Codex's latest reviewed reruns cover market,
PRD,
SEO,
discovery,
and landing response
plus artifact
passed all 20 cases at their 2026-08-02 source snapshots. The artifact keeps unknown attribution out
of decision lanes, strips the query and fragment before analytics setup, makes
no analytics or Buttondown request while explicit contract placeholders remain,
and exposes no raw provider or exception data. Its Function passed 18 local
adversarial intake/provider scenarios, including actual streamed-byte limits
without trusting Content-Length; deterministic browser checks also proved the
closed analytics gate and bounded attribution. CI requires current skill bytes
for both behavior and routing; the open Grok gap therefore fails closed until a
reviewed authenticated rerun is published.
Current-source evidence: Claude behavior 0/20, Codex behavior 20/20, Grok behavior 0/20; Claude routing 0/25, Codex routing 25/25, Grok routing 25/25.
Cross-host discovery evidence and all five Grok happy-path runs are recorded in host compatibility, including retained failures that led to discovery, landing-integrity, and PRD fixes.
Do I need all three agents?
No. Install works for whichever roots exist on your machine.
Will this write my product for me?
Skills produce decisions and artifacts (reports, interview guides, landing copy, PRDs, SEO plans). You still own judgment, outreach, and shipping.
Why force English landing pages in z-landing-smoke?
Default smoke surface is global English; the skill allows CN pages when your ICP is China-primary. Experiment notes follow your language.
Is this affiliated with gstack?
No. Complementary tooling. Avoid reusing gstack short names (qa, ship, …).
Can I vendor other people’s skills here?
Project policy: original skills only. Link out in docs if useful.
Actively developed at github.com/zh30/zstack.
| Area | State |
|---|---|
| Skill catalog (5) | Usable |
| Multi-host setup/doctor | Usable |
| Architecture docs | Usable |
| CI validation | Configured; host-specific evidence gaps fail closed (see the current-source block above) |
| Contributor guide | Usable |
MIT — free to use, modify, and distribute with attribution.
Built for one-person product companies that refuse to confuse shipping code with shipping value.
If this pack saves you from a dead-end build, star the repo and open an issue with what you learned — that feedback is how the skills get sharper.