ZAgentic Skills

ZAgentic is a collection of composable skills for human-guided engineering, codebase documentation, research, and everyday agent workflows. Public skills live in six purpose-based buckets under skills/; setup-specific skills live in root-level personal/ and are deliberately excluded from this catalog.

Start with /zj-guide when you do not know which route fits your situation.

Quick start

Install selected public skills through skills.sh:

npx skills@latest add jununfly/ZAgentic

Then choose the entry point that matches the repository's state:

• Use /zj-docs-ontology to establish, migrate, or govern a documentation system, including when no document map has been selected.
• Use /zj-repo-init after a document map is selected to configure tracker, triage vocabulary, and concise Agent entrypoints.
• Use /zj-guide for every other route, including implementation, research, maintenance, and standalone work.

Local installation

From a local clone, scripts/link-skills.sh installs every public and personal skill into detected supported agent skill directories:

Platform	Skill directory
claude	~/.claude/skills
codex	~/.codex/skills
workbuddy	~/.workbuddy/skills

# Install into every detected platform.
scripts/link-skills.sh

# Limit installation and preview it first.
scripts/link-skills.sh --platform codex --dry-run

# Copy is the default snapshot; symlink keeps a local checkout live.
scripts/link-skills.sh --platform codex --method copy
scripts/link-skills.sh --platform codex --method symlink

The installer replaces a same-named target skill folder; use --dry-run before overwriting an existing installation. Reload WorkBuddy plugins (or restart it) after installation so its scanner sees the new skills.

Refresh or remove a local installation

scripts/zagentic-skills-list is the generated inventory for uninstalling the locally installed collection. Regenerate it after adding or removing a public or personal skill:

scripts/list-skills.sh > scripts/zagentic-skills-list

Review that inventory before removing the matching directories from an agent's skills folder. The installer itself only installs or replaces skills.

Validate the repository layout

Run the validation entry point before distributing a local clone:

scripts/validate-plugin.sh

It runs the official plugin validator first. If that validator is unavailable or returns non-zero, it runs ZAgentic's recursive layout validator, which checks the six public buckets, root-level personal/, skill frontmatter, README registration, and public coverage in zj-guide.

Frontmatter validation needs PyYAML; install it once before validating:

python3 -m pip install -r requirements.txt

The script works on macOS, Linux, and Windows shells (including Git Bash and WSL). On Windows it converts paths to the form the detected Python interpreter expects, and it accepts either python3 or python on PATH.

Recommended paths

• Documentation system — /zj-docs-ontology discovers and proposes; /zj-docs-architecture owns architecture views. Migrations and deletions require explicit Human confirmation.
• Feature delivery — use /zj-grill-with-docs or /zj-grilling to align, then /zj-to-spec → /zj-to-tickets → /zj-implement as the work needs. /zj-steelman, /zj-dry-run, and /zj-debrief are the pre-plan, pre-implementation, and post-task checkpoints.
• Long-running uncertainty — /zj-wayfinder carries decisions and blockers until the work is ready for a spec and tickets; /zj-roadmap-driven tracks an agreed execution route.
• Complex problem solving — /zj-discuss turns a genuinely hard problem into a master document plus independent sub-documents, runs role-based multi-agent discussion per sub-problem, synthesizes the result, and hands off to /zj-docs-ontology; for a single issue use its companion /zj-discuss-view plus /zj-steelman directly instead.
• Goal-to-Plan composition — /zj-composer assembles a reviewable, versioned Plan from a goal, its constraints, and permission boundaries, surfaces capability gaps in the current catalog, and stages a bounded handoff to an execution chain. It stops at the Plan; it does not execute or own the work.
• Research and design — /zj-research produces evidence, /zj-code-research maps a repository, /zj-tech-research-report makes a technical recommendation, and /zj-tech-design-review tests a proposed design.
• UI delivery — the ten /zj-ui-* skills run a single chain from /zj-ui-brief to /zj-ui-handoff. One skill owns each stage, a Human gate chooses direction and signs review, and nothing advances on a guess: missing input becomes an unknown entry or NEEDS_CONTEXT, never an invented value.
• Closeout — /zj-debrief records process material after work; /zj-docs-ontology later governs durable extraction and proposed deletion. /zj-neat-freak reconciles broader docs, rules, memory, and workspace drift.

Public skills

Engineering

• zj-guide — Route a request to the skill or flow that fits it.
• zj-diagnosing-bugs — Diagnose hard bugs and performance regressions through a disciplined feedback loop.
• zj-triage — Move incoming issues through explicit triage roles.
• zj-codebase-design — Design deeper modules, clear seams, and small interfaces.
• zj-git-bypass-safe-delete — Diagnose and recover from WorkBuddy safe-delete Git corruption.
• zj-steelman — Reality-check a plan before grilling it.
• zj-dry-run — Rehearse a ticketed plan before implementation.
• zj-implement — Implement a spec or ticket with TDD and review checkpoints.
• zj-improve-codebase-architecture — Find codebase-deepening opportunities and turn a chosen one into work.
• zj-merge-skill-pair — Execute one approved skill-pair merge as an atomic commit.
• zj-merge-skills-wave — Plan a multi-skill merge wave from another collection.
• zj-resolving-merge-conflicts — Resolve an in-progress merge or rebase by each side's intent.
• zj-leader — Turn a one-line idea into an agent-runnable /goal brief.
• zj-repo-init — Configure tracker, triage vocabulary, and Agent entrypoints after a document map is selected.
• zj-tdd — Build a feature or fix test-first with red-green-refactor.
• zj-wizard — Generate a guided Bash workflow for steps only a Human can perform.
• zj-code-review — Review a change against repository standards and its originating spec.
• zj-tech-design-review — Review a technical design from framing through rollout and validation.
• zj-to-tickets — Slice a plan or spec into blocking-aware tracer-bullet tickets.
• zj-to-spec — Turn the current conversation into a spec and issue.
• zj-prototype — Build a throwaway prototype to answer a design question.

Codebase Docs

• zj-docs-architecture — Maintain and validate complementary architecture handbook views.
• zj-docs-ontology — Discover, govern, validate, and report on one codebase's documentation system.
• zj-debrief — Close out a task as process material and route durable conclusions for later synthesis.
• zj-domain-modeling — Maintain a project's domain language and glossary.
• zj-grill-with-docs — Conduct repository-aware grilling with documentation updates.
• zj-neat-freak — Reconcile codebase knowledge and governance drift.
• zj-roadmap-driven — Maintain a decision-carrying execution roadmap.
• zj-wayfinder — Maintain a shared map of large-work planning decisions.

Productivity

• zj-caveman — Switch to ultra-compressed communication mode.
• zj-composer — Compose a reviewable, versioned task Plan from a goal, constraints, evidence needs, and permission boundaries.
• zj-grilling — Stress-test a plan, decision, or idea through structured questions.
• zj-handoff — Create a compact handoff for another human or agent.
• zj-show-me — Explain the current topic visually with concise inline sketches and focused HTML artifacts.
• zj-wait-what — Re-pitch the last message when it did not land.
• zj-write-a-skill — Create a skill with progressive disclosure and bundled resources.
• zj-writing-for-agents — Write skills, rules, and agent-consumed documents clearly.
• zj-teach — Teach a concept across multiple sessions in a stateful workspace.
• zj-to-questionnaire — Turn an unresolved decision into a questionnaire for another person.
• zj-doc-collab — Base skill. Generic substrate for document-backed multi-agent collaboration: a shared document set as the single source of truth, per-agent scoped private memory layered on it, and a mechanical non-degradation structural gate. Reference this from other zj-* skills that need multiple Agents/SubAgents to collaborate over one document set; not user-query triggered on its own.
• zj-discuss — Decompose a complex problem into a master doc + independent sub-documents, run multi-agent independent discussion per sub-problem, synthesize, and hand off to zj-docs-ontology — with a static per-role launch-pack generator and a mechanical sub-document structural gate. Built on the zj-doc-collab base skill.
• zj-discuss-view — Companion to zj-discuss: in a separate independent Agent session, Read a sub-document original and write one role's independent viewpoint.

UI

The UI delivery chain: one skill per stage, one write owner per artifact, and a stop-and-ask default whenever ownership or semantics is ambiguous.

• zj-ui-core — S0 base carrier (not a stage): the deterministic engine every stage imports — schema validation, deny-first rejection, unknown quartets, idempotent commits, WCAG contrast, plus the fixture harness.
• zj-ui-brief — S1: turn conversation or UI-BRIEF.md edits into a brief draft with unknown entries instead of guesses.
• zj-ui-discover — S2: close brief gaps with a question budget of two, grading evidence and recording unknown.
• zj-ui-direction — S3: produce comparable direction cards and wait for the Human to choose.
• zj-ui-design-system — S4: freeze tokens and the component catalog, blocking unregistered components and failing contrast.
• zj-ui-flow — S5: own ui-flow/v1 across its six distinct meanings with a passing semantic round-trip.
• zj-ui-prototype — S6: build a local preview from the flow using catalog components only, with effects behind a policy gate.
• zj-ui-visual-review — S7: inspect and screenshot against the user task and risk class, producing an attributable review record.
• zj-ui-break — S8: break the interface with long, empty, error, extreme and localized data at 390/768/1440.
• zj-ui-verify — S9: run DOM/ARIA, focus, contrast and reduced-motion gates into a replayable verification receipt.
• zj-ui-handoff — S10: hand off with change summary, commands, risks, known limits, fallback and owner.

Misc

• zj-git-guardrails-claude-code — Add Claude Code hooks that block dangerous Git operations.
• zj-migrate-to-shoehorn — Migrate test assertions to @total-typescript/shoehorn.
• zj-scaffold-exercises — Scaffold lintable exercises, problems, solutions, and explainers.
• zj-setup-pre-commit — Set up Husky, lint-staged, type checks, and tests at commit time.
• zj-aihot — Retrieve current Chinese AI news and highlights from AIHOT's read-only API.
• zj-storage-analyzer — Analyze macOS or Windows storage usage and produce an actionable cleanup report.

Research

• zj-research — Produce cited primary-source findings or a sealed evidence ledger.
• zj-code-research — Build a commit-scoped repository map and bounded architecture study.
• zj-tech-research-report — Turn findings and sealed ledgers into a technical-solution research report.
• zj-systematic-research — Systematically study a product, company, concept, technology, or person.
• zj-open-source-capability-fit — Apply the ZAgentic open-source capability-fit decision model to an external OSS candidate (R×O matrix → A/B/C/D, with mechanical gates).