mirror of https://github.com/skymavis/skills.git synced 2026-09-14 13:45:55 +08:00

Files

T

Trung Nguyen 1344b7c6f2 chore(commits): require a body on every commit message

.gitlint had `ignore=body-is-missing`, so gitlint only checked the
subject and let subject-only commits through — including several from
this agent that dropped the "why" a body exists to capture. Drop that
ignore so gitlint's body-is-missing rule (B6) actually applies, and
update CONTRIBUTING.md/AGENTS.md to state the body is mandatory rather
than optional. AGENTS.md now points at CONTRIBUTING.md's "## Commits"
section instead of restating the rule, so the two can't drift again.

2026-07-02 01:15:13 +07:00

2.9 KiB

Raw Permalink Blame History

AGENTS.md — the skills repo

You are an agent authoring and maintaining reusable agent skills in this repo. This file governs how to work here; each skill's own SKILL.md governs how to use that skill.

Read order (every task)

This file.
README.md — the catalog and layout.
scripts/validate_skills.py — the contract you must satisfy.
CONTRIBUTING.md — the authoring workflow and local dev loop.
The target skill's SKILL.md.

The skill contract (self-check before running the validator)

A skill is a folder skills/<name>/ containing a SKILL.md.
Folder name == frontmatter name, kebab-case ^[a-z0-9-]+$, ≤ 64 chars, no leading/trailing/consecutive hyphen, and not anthropic/claude.
Frontmatter is a top-of-file YAML block fenced by --- … ---. Allowed keys only: name, description, license, allowed-tools, metadata, compatibility. name and description are required.
description: non-empty, ≤ 1024 chars, third person, no angle brackets. It is the trigger surface — say what the skill does and when to use it.
SKILL.md body ≤ 500 lines (budget). Push depth into references/.
Relative links in SKILL.md must resolve.

Authoring discipline

Each skill is self-contained under skills/<name>/: scripts/ (executable logic), references/ (depth loaded on demand), assets/ (templates/files the skill emits), tests/ (pytest, with a conftest.py that injects scripts/ onto sys.path).
Prefer the standard library; declare any extra test deps in the skill's requirements-dev.txt (CI always installs pytest).
Progressive disclosure: keep SKILL.md lean; depth goes in references/.
Don't hand-format SKILL.md line shape. pre-commit runs mdformat --wrap 100 over every SKILL.md, so write prose in whatever line shape and let the hook reflow it (it leaves tables, code blocks, and long URLs intact). Run pre-commit run --all-files and commit the result; CI checks the same fixed point.

Point to skills; never copy from them

A SKILL.md is the source of truth for what it owns. Referencing or linking a skill is good. Copying one skill's mechanics into README.md, AGENTS.md, or another skill is wrong — it duplicates, drifts, and goes stale. A skill may expose a CI-safe check command (the model is decisions.py check from decision-records); CI runs it. Never hand-edit a skill's generated artifacts (e.g. a generated INDEX.md) — regenerate via that skill's own tool.

Definition of done (before opening a PR)

python scripts/validate_skills.py passes for all skills.
The touched skill's python -m pytest -q passes.
New or changed behavior has a test.
pre-commit run --all-files is clean, and the README catalog is updated if a skill was added or its description changed.
Commits follow the contract in CONTRIBUTING.md's "## Commits" section (enforced by gitlint).

2.9 KiB Raw Permalink Blame History