pplx-sdk Development Meta-Skill

This meta-skill orchestrates all project-specific and community skills for pplx-sdk development. Activate this skill for any development task — it coordinates the right sub-skills automatically.

When to use

Use this skill for any development task on the pplx-sdk project: implementing features, fixing bugs, reviewing code, writing tests, or scaffolding new modules.

Subagent Architecture

Each skill delegates to a specialist subagent via context: fork . Subagents run in isolated context windows with restricted tool access.

┌───────────────────────────────────────────────────────┐ │ orchestrator │ │ (meta-orchestrator, delegates subtasks) │ ├───────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ code-reviewer │ │ test-runner │ │ │ │ (read-only) │ │ (run & fix) │ │ │ │ view,grep, │ │ bash,view, │ │ │ │ glob,bash │ │ edit,grep │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ scaffolder │ │ sse-expert │ │ │ │ (create new) │ │ (streaming) │ │ │ │ view,edit, │ │ view,edit, │ │ │ │ bash,grep │ │ bash,grep │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ reverse- │ │ architect │ │ │ │ engineer │ │ (diagrams & │ │ │ │ (API disc.) │ │ design) │ │ │ │ view,edit, │ │ view,edit, │ │ │ │ bash,grep │ │ bash,grep │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ spa-expert │ │ codegraph │ │ │ │ (SPA RE, │ │ (AST, deps, │ │ │ │ CDP, ext.) │ │ knowledge) │ │ │ │ view,edit, │ │ view,edit, │ │ │ │ bash,grep │ │ bash,grep │ │ │ └──────────────┘ └──────────────┘ │ │ │ └───────────────────────────────────────────────────────┘

Subagent Definitions (.claude/agents/ )

Subagent Role Tools Isolation

orchestrator

Decomposes tasks, coordinates others view, bash, grep, glob fork

code-reviewer

Read-only architecture review view, grep, glob, bash fork

test-runner

Run tests, diagnose, fix failures bash, view, edit, grep, glob fork

scaffolder

Create new modules and files view, edit, bash, grep, glob fork

sse-expert

SSE streaming implementation view, edit, bash, grep, glob fork

reverse-engineer

API discovery, traffic analysis view, edit, bash, grep, glob fork

architect

Architecture diagrams, design validation view, edit, bash, grep, glob fork

spa-expert

SPA RE: React/Vite/Workbox/CDP, extensions view, edit, bash, grep, glob fork

codegraph

AST parsing (Python + JS/TS), dep graphs, knowledge graphs view, edit, bash, grep, glob fork

Skill Dependencies

This meta-skill composes the following skills. Apply them in the order shown based on the task type.

Project-Specific Skills (repo root)

Skill Path Subagent Purpose

code-review

code-review/SKILL.md

code-reviewer

Architecture compliance and conventions

test-fix

test-fix/SKILL.md

test-runner

Diagnose and fix failing tests

scaffold-module

scaffold-module/SKILL.md

scaffolder

Create new modules per layered architecture

sse-streaming

sse-streaming/SKILL.md

sse-expert

SSE protocol and streaming patterns

reverse-engineer

reverse-engineer/SKILL.md

reverse-engineer

API discovery from browser traffic

architecture

architecture/SKILL.md

architect

System diagrams and design visualization

spa-reverse-engineer

spa-reverse-engineer/SKILL.md

spa-expert

React/Vite/Workbox/CDP webapp RE

code-analysis

code-analysis/SKILL.md

codegraph

AST parsing (Python + JS/TS), dependency graphs, knowledge graphs

Community Skills (installed via npx skills )

Skill Source Purpose

python-testing-patterns

wshobson/agents

pytest patterns, fixtures, mocking

python-type-safety

wshobson/agents

Type annotations, mypy strict mode

python-error-handling

wshobson/agents

Exception hierarchies, error patterns

python-design-patterns

wshobson/agents

Protocol pattern, DI, factory

api-design-principles

wshobson/agents

REST API design, endpoint conventions

async-python-patterns

wshobson/agents

async/await, concurrency patterns

skill-creator

anthropics/skills

Guide for creating new skills

mcp-builder

anthropics/skills

Build MCP servers for tool integration

webapp-testing

anthropics/skills

Test web apps with Playwright

ast-grep

ast-grep/agent-skill

Structural code search via AST patterns

knowledge-graph-builder

daffy0208/ai-dev-standards

Knowledge graph design and entity relationships

steering

nahisaho/codegraphmcpserver

CodeGraph MCP orchestration and traceability

Workflow: New Feature

[plan] → [explore] → [research] → [implement] → [test] → [review] → [done]

• Plan — orchestrator decomposes the task, identifies target layer

• Explore — code-reviewer (read-only fork) analyzes existing code and dependencies

• Research — reverse-engineer or sse-expert (fork) studies API behavior, reads docs, gathers context needed before implementation

• Scaffold — scaffolder (fork) creates files from templates

• Implement — sse-expert or scaffolder (fork) writes the code

• Test — test-runner (fork) runs pytest, fixes failures

• Review — code-reviewer (fork) validates architecture compliance

• Verify — ruff check --fix . && ruff format . && mypy pplx_sdk/ && pytest -v

Workflow: Bug Fix

• Reproduce — test-runner (fork) runs failing test with -v

• Research — code-reviewer (fork) traces the code path, reads related modules and tests

• Diagnose — test-runner reads traceback, identifies root cause

• Fix — test-runner edits source/test, applies python-error-handling patterns

• Verify — test-runner runs full suite

Workflow: SSE/Streaming Work

• Research — sse-expert (fork) reviews SSE protocol spec, existing transport code, and API response patterns

• Implement — sse-expert writes streaming code, applies async-python-patterns

• Test — test-runner (fork) runs tests with mock SSE responses

• Review — code-reviewer (fork) validates transport layer compliance

Workflow: API Discovery (Reverse Engineering)

[capture] → [research] → [document] → [scaffold] → [test] → [review]

• Capture — reverse-engineer (fork) analyzes cURL/traffic from perplexity.ai DevTools

• Research — reverse-engineer studies request/response patterns, tests variations, maps edge cases and auth flows

• Document — reverse-engineer writes endpoint documentation with field types and examples

• Scaffold — scaffolder (fork) creates Pydantic models and service methods from schema

• Implement — sse-expert or scaffolder implements transport and domain code

• Test — test-runner (fork) validates with mock responses matching discovered schemas

• Review — code-reviewer (fork) ensures architecture compliance

Workflow: API Endpoint

• Research — code-reviewer (fork) studies existing endpoints and api-design-principles patterns

• Design — code-reviewer reviews proposed schema against REST conventions

• Implement — scaffolder (fork) creates FastAPI endpoint

• Test — test-runner (fork) validates with pytest-httpx mocks

Workflow: Architecture Design & Visualization

[analyze] → [research] → [diagram] → [validate] → [document]

• Analyze — architect (fork) reads existing code, maps imports and layer dependencies

• Research — architect studies the components involved and their relationships

• Diagram — architect produces Mermaid diagrams (layer map, sequence, class hierarchy, state machine)

• Validate — architect checks for circular deps, upward imports, protocol conformance

• Document — architect embeds diagrams in README, docs, or PR descriptions

Workflow: SPA Reverse Engineering

[detect] → [research] → [intercept] → [extract] → [code-graph] → [document] → [implement]

• Detect — spa-expert (fork) identifies the SPA stack (React version, bundler, state management, service workers)

• Research — spa-expert studies the SPA internals, React component tree, and network patterns

• Intercept — spa-expert captures network traffic via CDP, Chrome extension, or DevTools

• Extract — spa-expert extracts React state shapes, API schemas, and Workbox cache strategies

• Code Graph — codegraph (fork) analyzes SPA source code: component tree, import graph, hook chains, TypeScript types; cross-references with spa-expert runtime findings

• Document — reverse-engineer

• spa-expert map runtime + static discoveries to SDK architecture

• Implement — scaffolder creates models and services; spa-expert builds tools/extensions

Workflow: Code Analysis & Knowledge Graph

[parse] → [graph] → [analyze] → [report] → [act]

• Parse — codegraph (fork) parses source AST: Python via ast module, JavaScript/TypeScript via grep-based import parsing

• Graph — codegraph builds dependency graph (module-to-module imports) and knowledge graph (Python: IMPORTS, INHERITS, IMPLEMENTS, CALLS, RAISES; SPA: RENDERS, USES_HOOK, CALLS_API, PROVIDES, CONSUMES)

• Analyze — codegraph detects patterns: circular deps, layer violations, dead code, complexity hotspots (Python); barrel file cycles, prop drilling, orphan routes (SPA)

• Report — codegraph produces structured insights report with Mermaid diagrams and actionable findings

• Act — Delegate findings: architect updates diagrams, code-reviewer reviews violations, scaffolder fixes gaps, spa-expert cross-references runtime analysis

Project Quick Reference

Install dependencies

pip install -e ".[dev]"

Install/update community skills

npx skills add wshobson/agents --skill python-testing-patterns --skill python-type-safety --skill python-error-handling --skill python-design-patterns --skill api-design-principles --skill async-python-patterns --agent github-copilot -y npx skills add anthropics/skills --skill skill-creator --skill mcp-builder --skill webapp-testing --agent github-copilot -y npx skills add ast-grep/agent-skill --skill ast-grep --agent github-copilot -y npx skills add "daffy0208/ai-dev-standards@knowledge-graph-builder" --agent github-copilot -y npx skills add nahisaho/codegraphmcpserver --skill steering --agent github-copilot -y

Lint, format, type-check, test

ruff check --fix . && ruff format . mypy pplx_sdk/ --ignore-missing-imports pytest tests/ -v --cov=pplx_sdk

Manage skills

npx skills list # Show installed skills npx skills check # Check for updates npx skills update # Update all skills

Architecture Invariants

These rules must never be violated regardless of which sub-skill is active:

• Layer dependencies: core/ → shared/ → transport/ → domain/ → client.py (never reverse)

• Exception hierarchy: All errors extend PerplexitySDKError

• Type annotations: 100% coverage, from future import annotations

• Google docstrings: On all public APIs

• Protocol pattern: Use typing.Protocol , never ABC