Authoring & versioning

SKILL.md format

A skill is a single Markdown file with a YAML frontmatter block, then the instructions the agent should follow:

---
name: fastapi-service-scaffolding
namespace: python
version: 1.0.0
description: Scaffold a production FastAPI service with routers, settings and tests.
stack:
  layer: backend
  technologies: [fastapi, pydantic]
  languages: [python]
---
# FastAPI service scaffolding

Instructions the agent should follow…

name, namespace, and version are required. The stack block powers the technology/language facets and the layer filter used for search. layer names the part of the system the skill serves — e.g. backend, frontend, mobile, data, devops, qa, security.

Submit a new skill

From the CLI (diskills submit) or the website (Submit → paste/upload your SKILL.md). It lands as Pending for admin review; only approved versions become installable.

Update an existing skill (new version)

Any contributor can publish a new version of any skill — you don't have to be the original author. On the website, open the skill and click Submit new version: the form pre-fills with the current SKILL.md so you edit in place. Bump the version (semver) before submitting — re-submitting an existing version is rejected.

When an admin approves a version that becomes the newest, the skill's displayed metadata (description, layer, tags) refreshes from that version's manifest.

Review workflow

submit ──▶ Pending ──▶ (admin) ─┬─▶ Approved   → published, installable, newest sets metadata
                                └─▶ ChangesRequested → fix & resubmit

Every submission and review is recorded in the audit log.