PVYai Agent is very slick and ease of use. And of course you can task it like any AI Agent with prompts. But the real power comes with Teams, Swarms, Loops and Specialisist, exactly tailored to a specific project, where you may also want to use language/framework specific SKILLS, which are fitting to the project plan and tasks to accomplish. And since we have built-in over 28+ AI Provider, so you can use different Models, from different Providers, not only PVYai, the example project configuration will cover this.
Project: pvybutler (
/Volumes/Data/Repos/pvybutler)
Models: Qwen 3.6 35B MoE · GLM-5.2 756B MoE · DeepSeek V4 Pro 1.6T (without PVYai Sentinel, Destructive Action/Prevention, but with PVYai Memory)
Last updated: 2026-07-26
This guide shows developers how to configure PVYai Agent’s specialist, swarm, and loop systems to autonomously refactor a real project. The example uses the pvybutler codebase (a TypeScript/Node.js Electron monorepo) and a 4-track refactoring plan: Brand, Security, Performance, Routes/Pipeline.
Everything here is copy-paste ready. Adapt the model IDs, paths, and prompts to your project.
┌─────────────────────────────────────────────────────────────────────┐
│ PVYai Orchestrator (Qwen 3.6) │
│ TUI session · pvybutler/ cwd │
│ │
│ ┌─── Team: brand ──────────────────────────────────────────────┐ │
│ │ brand-explorer (Qwen 3.6, read-only) │ │
│ │ brand-worker (Qwen 3.6, edit+execute) │ │
│ │ → handoff to security team │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Team: security ───────────────────────────────────────────┐ │
│ │ security-auditor (GLM-5.2, Think High, read-only) │ │
│ │ security-fixer (Qwen 3.6, edit+execute) │ │
│ │ → handoff to perf-routes team │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Team: perf-routes ────────────────────────────────────────┐ │
│ │ perf-profiler (DeepSeek V4 Pro, Think Max, read-only) │ │
│ │ routes-worker (Qwen 3.6, edit+execute) │ │
│ │ test-writer (Qwen 3.6, edit+execute) │ │
│ │ → final handoff to code-review │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ Loop: pvyai cron add "*/30 * * * *" --cwd pvybutler/ │
│ Reads .pvyai/loop.md → incremental progress each cycle │
└─────────────────────────────────────────────────────────────────────┘
| Model | Role | Speed | Context | Why |
|---|---|---|---|---|
| Qwen 3.6 35B MoE (3B active) | Orchestrator + mechanical refactoring + test writing | 110 tok/s | 128K/262K | Fast, native function calling, good for repetitive edits and test generation |
| GLM-5.2 756B MoE | Security audit (deep reasoning) | Cloud | 976K | Large context for whole-codebase security scanning, Think High for thorough analysis |
| DeepSeek V4 Pro 1.6T (49B active) | Performance optimization (frontier reasoning) | Cloud | 1M | 1M context for entire codebase profiling, Think Max for complex optimization decisions |
All 3 models are available through the PVY.ai Platform provider (https://ai-api.pvy.swiss/api). See config-snippet.json for the multi-provider setup.
.pvyai/
├── config.json # Multi-provider config (or use ~/.config/pvyai/config.json)
├── loop.md # Autonomous progress instructions
├── specialists/
│ ├── brand-refactor.md # Brand renaming specialist (Qwen 3.6)
│ ├── security-audit.md # Security audit specialist (GLM-5.2)
│ ├── perf-optimizer.md # Performance profiling specialist (DeepSeek V4 Pro)
│ ├── routes-refactor.md # Routes/pipeline restructuring specialist (Qwen 3.6)
│ └── ts-test-writer.md # TypeScript test generation specialist (Qwen 3.6)
├── skills/
│ ├── brand-rename-checklist/
│ │ └── SKILL.md # Brand renaming checklist
│ ├── security-scan/
│ │ └── SKILL.md # Security scan checklist
│ ├── perf-profiler/
│ │ └── SKILL.md # Performance profiling steps
│ └── routes-api-conformance/
│ └── SKILL.md # API route conformance checklist
└── specs/
└── refactor-v1.md # Approved refactoring spec (4 tracks)
Note: Skills are installed to
~/.local/share/pvyai/skills/(user-level) or<project>/.pvyai/skills/(project-level). The paths above show the project-level layout for team sharing. See Skills for installation details.
# Copy specialists to the project
cp -r specialists/ /path/to/pvybutler/.pvyai/specialists/
# Copy loop.md
cp loop.md /path/to/pvybutler/.pvyai/loop.md
# Copy the refactoring spec
cp project-plan.md /path/to/pvybutler/.pvyai/specs/refactor-v1.md
# Install skills (user-level, shared across projects)
for skill in skills/*/; do
pvyai skills add "$skill"
done
Edit ~/.config/pvyai/config.json and add the 3 providers from config-snippet.json. Or run:
pvyai setup pvyai --model qwen3.6:35b
# Then manually add glm-5.2:cloud and deepseek-v4-pro:cloud as additional providers
cd /path/to/pvybutler
pvyai
In the TUI:
/spec Execute the refactoring plan in .pvyai/specs/refactor-v1.md
Or start the autonomous loop:
pvyai cron add "*/30 * * * *" --cwd /path/to/pvybutler --model qwen3.6:35b
pvyai cron run
/ps: List all running tasks/plan: View the refactoring plan progressswarm_status: Check team status| File | Content |
|---|---|
| specialists/ | 5 specialist manifests (one per role) |
| skills/ | 4 skill checklists loaded on demand |
| project-plan.md | 4-track refactoring spec |
| loop.md | Autonomous incremental progress instructions |
| swarm-orchestration.md | Swarm team design, handoff patterns, mailbox messages |
| config-snippet.json | Multi-provider config for 3 models |
.pvyai/loop.md lets the agent make progress every 30 min without supervisionskill toolTo use this setup for a different project:
loop.mdproject-plan.md to match your project’s needsclaude-sonnet-4.5 instead of qwen3.6:35b)maxTeamSize in config.json based on your budget — more members = more concurrent costMy opinionated take, based on how the PVYai Agent skill system actually works:
Skills are loaded into the LLM’s context window via skill("name"). Every byte competes with code, conversation, and tool schemas. A 5000-token skill on “how to write REST APIs” wastes context teaching the LLM something it already knows — while a 200-token checklist of “which patterns THIS project uses” is pure signal.
| Aspect | Over-specified (bad) | Right-sized (good) |
|---|---|---|
| What | “Use parameterized queries to prevent SQL injection” | “All DB queries go through storage-service.ts. Use the query() method, never raw SQL.” |
| Why | LLM already knows this | LLM doesn’t know YOUR project’s convention |
| Code examples | Full implementation templates | One-liner showing the import path or function name |
| Edge cases | Every possible scenario | The 3-5 gotchas that actually bit your team |
| Length | 500+ lines, covers everything | 50-150 lines, covers decisions already made |
1. Encode decisions, not knowledge.
The LLM knows REST. It doesn’t know that your project uses snake_case for DB columns and camelCase for API responses. That’s a decision — put it in the skill. “Use proper status codes” is knowledge — leave it out.
2. Point to files, don’t duplicate code.
Instead of embedding a full component template, say: “See apps/web/src/client/components/ui/Button.tsx for the pattern. All new components follow this structure.” The LLM will read the file — it has read_file. One line vs. 50 lines of context.
3. Cap at what the LLM can’t infer.
If the LLM can figure it out from reading the codebase, don’t put it in a skill. Skills are for things that are invisible from the code: team conventions, “never touch X” rules, deployment steps, review criteria.
There’s one exception: audit/review checklists. The security-scan and routes-api-conformance skills we wrote are intentionally detailed because they’re exhaustive checklists — the LLM needs to check every item, not infer which ones apply. Missing one is a bug. Here, detail prevents omissions.
But for skills like brand-rename-checklist, we point to rg commands and let the LLM figure out the rest. The checklist structure guides; the LLM executes.
If they have skills for ui, db, patterns, api — the question is: are these teaching the LLM (over-specified) or constraining it to project conventions (right-sized)?
Quick test: if you deleted the skill, would the LLM still produce correct code by reading the codebase? If yes, the skill is teaching (drop it or trim). If no, the skill encodes something invisible (keep it).
My recommendation: Audit the existing skills. For each one, ask “can the LLM infer this from reading the code?” If yes → trim to a 5-line pointer. If no → keep as a focused checklist of decisions and gotchas. Saves tokens, rounds and context.