SKILLYARD
Publish a skill

Auditing a skill

A portable skill is a recipe you can audit: clear inputs, a clear output, and no hidden side effects.

A teammate should answer four questions in under 10 seconds, without reading the whole SKILL.md:

  1. What does it take in? — inputs
  2. What does it emit? — outputs
  3. What is it allowed to touch? — touches, allowed-tools, permissions
  4. What side effects can it cause? — side_effects

Drafts may be incomplete. Published skills may not.

Why SKILL.md is shared

The contract lives in the SKILL.md frontmatter, not only in Skillyard's database. The same file you install in Claude Code, Codex or Cursor carries the same audit answers, so anyone can review it in a pull request or on disk.

inputs:
  - name: source
    type: text
    required: true
    description: The document, ticket, or notes to process
outputs:
  - name: artifact_markdown
    type: markdown
    description: The finished recipe output
side_effects: none
touches:
  - user_input
permissions:
  network: deny
  files: deny
  workspace: read
  secrets: deny

Reading allowed-tools and permissions

  • allowed-tools lists the agent tools the skill expects (for example Read, Write, Bash).
  • permissions states the ceiling: network deny/allow, files deny/read/write, workspace deny/read/write, secrets deny/allow.
  • They must agree. side_effects: none with Write or Bash in allowed-tools is a hidden side effect, and Skillyard blocks publishing it.
  • Colour code on skill pages: green = deny/none, amber = read, red = write, network, secrets, sending messages or mutating the workspace.

The rule

If it is not declared, it must not happen. The Skillyard runner only passes declared inputs, only keeps declared outputs, and treats any extra model fields as undeclared — never as the official artifact. If a request needs an undeclared side effect, the run returns an error explaining the contract blocked it.