AGENTS.md — oss-ai-skills

Rules for creating and maintaining skills in this repository. Read this before editing any SKILL.md.

Repository layout

frameworks/ — library and framework skills (django, ratatui, pytest, sqlalchemy, …)
languages/ — language-level skills (rust-core)
tool/ — CLI tool skills (ast-grep, redis, waydroid)
extend/ — plugin and extension skills (firefox-extension, opencode, …)
Skill directories use kebab-case. One skill per directory.
README.md must stay in sync: one row per skill with trigger-style description, current line count, and tags. Hub skills list sub-skills with ↳ indentation.

Every SKILL.md must follow the frontmatter syntax documented in the README ("Skill Format" section), per the skillreg.dev specification:

name — kebab-case, must match the parent directory name (exception: frameworks/pyqt/ sub-skills predate this rule and keep their pyqt-* names; the linter allowlists them)
description — trigger-focused, one line (see writing rules below)
metadata.author — the maintainer name
metadata.version — semver string, bumped on content changes, never downgraded
metadata.tags — lowercase, comma-relevant keywords also used in the README row

Do not introduce alternative frontmatter shapes; the README example is canonical.

The frontmatter description decides when an agent loads the skill. Write the triggering conditions.

Bad: "Rust terminal UI framework - widgets, components, layouts, events, input handling, and state management"
Good: "Use when building terminal UIs in Rust with the ratatui crate - layout system, widget usage, input/event handling, app state architecture, TUI testing, or migrating between ratatui 0.29 and 0.30"

SKILL.md is the entry file: target ≤ 600 lines (~25 KB).
Above that, split: SKILL.md (quick start, core reference, pointers) + references/*.md deep dives that the agent loads on demand. Each reference file opens with a one-line note that it is loaded on demand from the entry file.
Bloat smell: duplicated sections and mirrored documentation (e.g. four widget sections and three examples in one file). Merge duplicates before anything else.
Splitting into separate skills (hub + sub-skills) is reserved for genuinely independent domains, like pyqt or django-admin/django-transaction.

Write recipes, decision guides, and pitfalls the agent can act on.
No feature-history narration: no "added in vX.Y.Z", no release dates sprinkled through sections. Terse minimum-version markers like (v0.30+) on a heading are allowed; prose about releases is not.
Version upgrades and breaking changes live in ONE compact migration table, not in scattered annotations.
Do not reproduce official documentation — API listings, config tables, color palettes, basic usage prose. Link the official docs; keep only what is non-obvious: pitfalls, recipes, patterns, gotchas.
Examples must be generic, not project-specific (no real project names, no internal module paths).

Updates are additive by default: never delete or replace curated sections to make room for new content. Add new sections; fix facts in place.
Never downgrade a version number. Bump semver: minor for content additions, major for restructures.
Cite source URLs for researched material (repo/docs links next to each library or feature).
After any content change, update the skill's README.md row: description and line count.

Before planning a skill rework, run scripts/skill_update_report.py <skill> to mine session evidence, and scripts/analyze_skills.py for baseline evaluation scores (the latter needs the OpenCode server on 127.0.0.1:18889).
After edits: recheck line counts, grep for leftover duplicated sections, verify every internal link in SKILL.md resolves to an existing file, confirm no version downgrade happened.