Skill Authoring

---
name: skill-authoring
description: "Creates and updates canonical Agent Skills in the Scientific Agent
  Skills repository while preserving scope, frontmatter, progressive disclosure,
  versioning, tests, catalog entries, and diagram policy. Use for new skills,
  skill revisions, metadata fixes, references/scripts/assets placement, or
  contribution checklists."
disable-model-invocation: true
metadata:
  disco-role: operating
license: MIT
---

# Skill Authoring

Use this route when the task changes a canonical skill under `skills/<name>/`.

## Before editing

1. Read the existing `SKILL.md` and every linked local reference/script that the change may affect.
2. Read `AGENTS.md` and the relevant `CONTRIBUTING.md` section.
3. Decide whether the request is a new skill, an update, or a scope correction. Do not create a broad orchestrator skill merely because several neighboring skills exist.
4. Use current upstream package/platform documentation for API claims; keep untested behavior explicitly illustrative.

Read `references/authoring-workflows.md` for the new/update checklists and `references/frontmatter-and-layout.md` for the exact structural contract. Use `scripts/audit_skill_frontmatter.py` for a fast local preflight before the repository validator.

## New skill route

- Create `skills/<name>/` with a matching lowercase-hyphen `SKILL.md`.
- Put only runtime content in the skill directory: `SKILL.md`, `references/`, `scripts/`, and useful `assets/`.
- If the skill ships scripts, create tests under `tests/<name>/` and add a matching entry to `tests/skill-requirements.toml`.
- Keep the root document router-like; move long API tables, examples, data schemas, and troubleshooting matrices into references.
- Update the public catalog and any required generated diagram only after the content is final. Read `references/catalog-and-diagrams.md` because this checkout may not contain the diagram generator named by repository policy.

## Existing skill update route

- Make the smallest useful change and preserve unrelated behavior.
- Bump the quoted `metadata.version` in the same change.
- Re-run touched examples/scripts and the skill's own test suite.
- Re-check local links, line count, optional dependency claims, credentials, and safety boundaries.
- If the workflow or references changed materially, regenerate the diagram when the required tool is available; a typo/link/version-only change does not require an image refresh.

## Exit handoff

Before handing off, report the skill directory, files changed, evidence consulted, intentional omissions, version bump, test/validation commands to run, catalog/diagram status, and any upstream or environment uncertainty. Route execution to `validation-testing`, then route scanner review to `security-scanning`.