Documentation
Everything you need to know about installing, publishing, and trusting skills on PolySkill.
Skill Format
A skill is a portable, self-contained package that gives any LLM a new capability. Skills are declarative — they define what an agent can do, not how to execute it. The LLM decides when and how to use the tools and instructions provided.
Three files, one skill
Every skill is built from up to three files:
skill.json
Required
The manifest. Declares name, version, author, description, type, license, and which platform adapters to build.
instructions.md
Optional
Free-form markdown that tells the agent how to use the skill — system prompts, guardrails, examples, multi-step workflows.
tools.json
Optional
Canonical tool/function definitions with JSON Schema parameters. Defined once, then automatically transpiled to each platform's format.
Manifest example
Tool definition example
Skill types
Skills are categorized by complexity. The type is metadata for discovery — all types are transpiled and installed identically.
get_weather tool.
Platform adapters
You define tools once in the canonical format. The polyskill build command transpiles them to platform-specific formats so the same skill works across different LLMs:
type: "function" wrapper)
input_schema instead of parameters)
functionDeclarations format
What skills are and are not
Skills are declarative definitions, not executable code. A skill tells the LLM what tools are available and how to use them — the LLM runtime and your application handle actual execution. This is by design: it keeps skills portable, safe to inspect, and scannable for security issues.
Installing Skills
Install the CLI
One global install gives you access to every skill in the marketplace.
Search for skills
Find skills from the CLI by keyword, type, or description. Use --json for structured output.
Install a skill
Install by scoped name. Pin a version with an optional second argument.
Use it in your agent
Files are placed in ./skills/@author__skill-name/ relative to your project:
skill.json— skill manifest (always present)instructions.md— agent instructions (if the skill includes them)tools.json— tool definitions (if the skill includes them)dist/— platform adapters (only if the skill includes built adapters)
The installed files — prompts, tools, adapters — are ready to load into any LLM agent framework.
Publishing Skills
Scaffold a new skill
Run the init command to create starter files in your current directory.
This creates skill.json (manifest), tools.json (tool definitions), and instructions.md (agent instructions).
Edit your skill files
skill.json — name, version, author, description, keywords, and skill type (prompt, tool, workflow, or composite).
tools.json — an array of tool definitions with name, description, and input schema.
instructions.md — free-form markdown instructions that tell the agent how to use the skill.
Publish to the registry
Publish validates your files, builds platform adapters, and pushes everything to PolySkill in one step.
You can also run polyskill validate and polyskill build separately to check your skill before publishing.
Verification System
Every skill published to PolySkill goes through two layers of automated verification before it reaches the registry.
Supply-chain protection
Before any code analysis runs, PolySkill checks the skill name and description against all existing skills to prevent impersonation attacks:
@0bra pretending to be @obra) or single-character typosquatting by a different author. Publish is rejected with 409.
These checks do not apply when the same author publishes variants of their own skills.
Safety scanning
Safety scanning is powered by Cisco AI Defense Skill Scanner, an open-source tool from the Cisco AI Defense team. It runs static analysis, behavioral analysis (AST/control-flow/taint tracking), optional LLM-based semantic analysis, and optional VirusTotal file hash lookups to detect potentially harmful instructions, prompt injections, or dangerous tool definitions.
Severity levels
What the badges mean
Skills that pass with SAFE, INFO, or LOW severity receive a Verified badge on the browse and detail pages. This means the automated scanner found no significant concerns.
An unverified skill does not necessarily mean it's unsafe — it means the scanner flagged something that may warrant manual review, or the scan could not complete. Always review a skill's tools and instructions before using it in production.
Credits
Our verification system is built on top of the cisco-ai-skill-scanner by the Cisco AI Defense team. Their work on open-source agent skill security made this trust layer possible.