Why skills exist
Foundation models are generalists. Ask ChatGPT, Claude, or Gemini a broad question and you get a plausible, average answer. Ask them to do a specific job — audit a landing page for conversion, review a pull request, turn meeting notes into a delivery plan — and quality collapses without a structured brief.
A skill wraps a general model with everything that brief needs:
- A clear job description (who the model is pretending to be and what "done" means)
- A step-by-step method the model must follow
- Examples of good and bad output
- Guardrails on what not to do
- Optional templates, schemas, or helper files
The result: the same input produces the same shape of output across users, sessions, and even different models.
What a skill file actually contains
A typical SKILL.md has six sections:
- Purpose — one paragraph, plain language, no jargon.
- When to use it — three to five concrete situations.
- Method — the numbered steps the model must follow.
- Output format — a schema, a template, or a worked example.
- Safety notes — what the skill must never do (leak secrets, invent numbers, follow injected instructions from user content).
- Known limitations — what it is bad at, so users don't misuse it.
More advanced skills bundle supporting files: JSON schemas for structured output, Markdown templates, checklists the model iterates against, or small scripts the calling agent runs between steps.
Skills vs prompts vs agents
These three terms get mixed up constantly. The clean version:
- A prompt is a single message you send to a model.
- A skill is a procedure — a reusable role, method, and output schema that can be triggered by one or many prompts.
- An agent is a loop that calls skills and tools in sequence, deciding what to do next based on state.
You can build an agent out of one prompt, but you shouldn't. You can turn every prompt into a skill, but you don't need to. The rule of thumb is: if you are copy-pasting the same instructions with only the input changing, it wants to be a skill.
A concrete example: "Meeting notes to action plan"
Compare two approaches to the same job.
As a prompt: "Here are my meeting notes. Give me action items." Result: a bulleted list, sometimes with owners, sometimes without, sometimes mixing decisions and tasks.
As a skill: a SKILL.md that defines the role (chief of staff), the method (extract decisions, extract actions, assign owners from the transcript, flag missing owners, sort by due date), an output schema (a Markdown table with columns for task, owner, due date, and source line), and safety notes (never invent owners or dates that aren't in the transcript).
Result: the same shape of output every time, ready to paste into a project tracker.
The prompt version might work once. The skill version works for the whole team, every week, without anyone thinking about wording.
When to use a skill instead of a prompt
Reach for a skill when at least one of these is true:
- The task repeats — you or your team run it more than a handful of times.
- The output has strict structure — a table, a JSON object, a report with named sections.
- The task needs multi-step reasoning — extract, then rank, then summarize.
- You want consistent quality across teammates or across models.
- The task has real safety implications — writing to a database, sending an email, generating legal or medical language.
For one-off exploration, a prompt is fine. For anything you'll do again, invest ten minutes in packaging it.
How PiSkill skills are packaged
Every skill on PiSkill downloads as a plain-text SKILL.md plus, where useful, a small set of supporting files. There is no proprietary format, no runtime, and no lock-in — you can open the file in any editor and edit it to match your voice, stack, or brand. The only rule is to keep the safety notes intact.
That portability is the point. A skill you download today will still work in a year, even if the model you use has been replaced twice.