Skip to content

AUTHORING.md

Latest commit

 

History

History
98 lines (67 loc) · 2.89 KB

AUTHORING.md

File metadata and controls

98 lines (67 loc) · 2.89 KB
Raw

PortalJS Skill Authoring Guide

Skills live in .claude/commands/ (OSS, no Datopian keys required) or .claude/datopian/ (Datopian-internal, requires API access).

File format

Each skill is a markdown file. The filename becomes the slash command.

---
description: One sentence shown in /help and command picker
allowed-tools: Read, Write, Edit, Bash, WebFetch
---

# /skill-name

One paragraph explaining what this skill does and when to use it.

## Required input

...

## Steps

...

Frontmatter fields:

  • description (required) — shown in /help
  • allowed-tools (optional) — restricts which tools Claude may call

Input contract

Every skill must document the minimum required input before doing any work.

Minimum required fields (must be present or the skill must prompt before proceeding):

  • At minimum: one identifying noun (project name, file path, dataset name)
  • If a file path or URL is required: state the supported formats explicitly

Prompting rule: If required input is absent, emit one clarifying question and stop. Do not guess. Do not proceed with placeholder values.

Example prompt pattern:

I need a dataset file path or URL to continue. Please provide one of:
- A local file path: ./data/myfile.csv
- A public URL: https://example.com/data.csv

Output expectations

Every skill must describe what it produces:

  • Files created (paths, formats)
  • Files modified (paths, what changes)
  • Commands run (and expected exit codes)
  • What the user sees when it succeeds

Error handling

On any hard failure, emit a structured error block and stop:

ERROR: [SKILL_NAME] [CODE] <message> — <remediation hint>

Examples:

ERROR: [new-portal] MISSING_INPUT No project name provided — add a name to your brief and retry.
ERROR: [add-dataset] UNSUPPORTED_FORMAT .xlsx files are not supported — convert to CSV first.
ERROR: [add-dataset] FETCH_FAILED Could not fetch https://... — check the URL is publicly accessible.

Do not silently continue past a hard failure. Do not use placeholder values to paper over missing input.

Referencing other skills

In v1, skills are user-invoked and do not call each other programmatically. If a skill's output is the natural input to another skill, say so at the end:

Done. Next: run /portaljs-add-dataset to load your client's CSV into this portal.

Datopian-internal skills

Any skill in .claude/datopian/ must include this header immediately after the title:

> Datopian-internal skill. Requires Datopian API access. Not for general OSS use.

Definition of done

A skill is done when:

  1. It has frontmatter with description
  2. It documents required input and supported formats
  3. It describes its output
  4. It uses the ERROR: format for failures
  5. It has been tested end-to-end on at least one real project (not a toy example)
  6. It ends with a "next step" pointer if another skill naturally follows