Perplexity opens agent skills manual with 'Zen of Skills' rules for folder-based workflows

• Perplexity published the internal guide its agents team uses to build and review reusable agent Skills, and perplexity_ai's launch post points readers to the full research manual.
• The sharpest framing change comes from perplexity_ai's Zen of Skills thread, which argues that good Skills invert familiar software aphorisms: complexity is useful, gotchas are the valuable part, and obvious explanations should usually be deleted.
• In the manual, a Skill is a directory with SKILL.md, scripts, references, assets, and optional config, not a one-file prompt, according to the official article and perplexity_ai's summary.
• AravSrinivas tied the post directly to Perplexity Computer, and the manual says the same Skill library spans general-purpose utilities plus domain modules for finance, law, and health in Perplexity's agent stack.

You can read the full manual, browse the broader Perplexity Research hub, and the post gets unusually concrete about files, routing descriptions, dependency tags, and token budgets for loading Skills at runtime.

Perplexity's public pitch is that Skill writing behaves differently from normal software work. In the official manual, the agents team says strong engineers still get heavy revision feedback because common coding habits become antipatterns in Skill creation.

The five rules Perplexity surfaced are more useful than the slogan:

• A Skill is a folder, not a file.
• Activation is implicit pattern matching, with progressive disclosure.
• Context is expensive, so signal density matters more than sparse elegance.
• Gotchas are the highest-value cases.
• If a behavior is easy to explain, the model probably already knows it.

The manual's most concrete contribution is the filesystem layout. In Perplexity's version, a Skill directory can include:

• SKILL.md for frontmatter and instructions
• scripts/ for code the agent should run instead of regenerate
• references/ for large docs loaded only when needed
• assets/ for templates, schemas, and data
• config.json for first-run setup

The manual also treats hierarchy as a routing tool. One example groups 300 topics into 20 subject areas so the model chooses among smaller menus instead of one giant list.

Perplexity says the description field is not human-facing documentation. In the manual, it is the routing trigger, which is why good descriptions read more like "Load when..." than "This Skill does...".

The same document says root frontmatter can also declare depends: for hierarchical Skill dependencies and metadata: for review and evaluation. The team says review is strict enough that many pull requests from experienced engineers still come back with long revision lists.

Perplexity's runtime model is a three-stage load path described in the official post: the agent first sees a compact index of Skill names and descriptions, then loads a Skill's SKILL.md, then reads deeper files like references, assets, scripts, and subskills only if needed.

The token accounting is explicit:

• Index: about 100 tokens per Skill, always paid for every session
• Load: about 5,000 tokens for the full SKILL.md
• Runtime reads: effectively unbounded, but only when the agent opens those files

That explains why the post obsesses over terse descriptions and conditional loading. Perplexity is publishing a design manual, but it is also publishing a cost model for agent scaffolding.

The most specific example in the manual is Perplexity Computer's U.S. income tax Skill. The research article archive dates the post to May 1, and the article says the team used three levels of topical nesting during tax season because dumping all 1,945 sections of the U.S. Internal Revenue Code into one folder performed worse than not loading the Skill at all.

To make the hierarchy usable, the team says it added quick reference guides, custom search utilities, and other navigation tools inside the Skill itself. That is a more revealing pattern than the tweet slogan: Perplexity is treating information architecture, not just prompting, as core agent behavior.