Perplexity Research Publishes Practical Guide to Building and Maintaining Agent Skills

Perplexity Research has published a public guide describing how its Agents team designs, reviews, and maintains modular components called Agent Skills. The document captures the team’s internal practices so engineers across the company can develop and review Skills with consistent expectations, and Perplexity is making the guide available publicly so other organizations and individual users can apply the same patterns when productizing agent capabilities.

At the center of Perplexity’s approach is a folder‑based Skill model: a Skill is a directory rather than a single file. A typical Skill directory includes a SKILL.md frontmatter file for human‑readable metadata and intent, a scripts/ folder for executable logic, a references/ folder for heavy documentation that is loaded conditionally, an assets/ folder for templates, schemas and data, and a config.json for first‑run setup. Perplexity argues this hub‑and‑spoke structure keeps Skills focused while enabling multilevel hierarchies where needed.

The guide explicitly contrasts Skill design with traditional software engineering, arguing many familiar coding aphorisms do not translate. Perplexity presents five direct comparisons drawn from the Zen of Python and reframes them as a “Zen of Skills”: for example, “Simple is better than complex” becomes “A Skill is a folder, not a file. Complexity is the feature,” and “Explicit is better than implicit” becomes “Activation is implicit pattern matching. Progressive disclosure.” These reframings emphasize that Skills are curated bundles of contextual content for models, not ordinary libraries of code.

Perplexity ties those design principles to concrete operational consequences. Keeping bulky documentation in a references/ directory and loading it only when relevant helps conserve tokens and manage runtime context size; separating assets and schemas supports predictable I/O; and centralizing onboarding behavior in config.json makes first‑run setup reproducible. The guide also stresses designing for rare but consequential edge cases rather than pruning them away, since “gotchas” can represent the highest‑value content for agent behavior.

The company illustrates tradeoffs with a production example from its tax work: presenting a model with a single folder containing all 1,945 sections of the U.S. Internal Revenue Code produced worse performance than not loading the Skill at all, so Perplexity employed three levels of topical nesting to improve precision. That hierarchy required extra curation and tooling — quick reference guides and custom search utilities — to manage indirection, a cost the guide says is often justified by improved model performance. The public document does not include release timing or adoption metrics, so readers interested in implementation details or licensing will need to consult the source directly.