AGENTS.md — skills

Instructions for AI agents working in this repo. Human contributors: see README.md.

What this is

A collection of standalone Agent Skills following the agentskills.io specification. Each top-level directory is one self-contained skill, installable on its own:

npx skills@latest add MKAbuMattar/skills/<skill-name>

There is no build, no stack, no runtime. A skill is a SKILL.md (YAML frontmatter + Markdown body) plus optional references/, assets/, scripts/, and an MIT LICENSE. This is a flat skills collection, not a Claude Code plugin — there is no .claude-plugin/ manifest and no /namespace:command invocation. Do not add one without being asked; it changes how every skill installs.

Layout

• <skill-name>/SKILL.md — the skill itself: frontmatter contract + body. The only required file besides LICENSE.
• <skill-name>/references/*.md — progressive disclosure. Detail the agent loads only when a task needs it. Every file here must be mentioned by path in SKILL.md (its load trigger).
• <skill-name>/assets/ — templates and worked examples. Use assets/templates/, not a top-level templates/.
• <skill-name>/scripts/ — runnable helpers. Self-contained; no install step.
• <skill-name>/LICENSE — MIT, one per skill, so a single-skill install carries its license.
• README.md — human-facing index, grouped by category, with an install snippet per skill.
• __SCRIPTS__/ — repo-level tooling: the validation gate, the frontmatter check, and the description eval. Not a skill; the gate skips any directory without a SKILL.md.
• __SCRIPTS__/fixtures/<skill>.json — eval queries per skill. Kept out of the skill directory on purpose: a single-skill install copies only that directory, and eval data is repo tooling rather than shipped content.
• .github/ — CI workflow plus the community health files (contributing guide, code of conduct, security policy, PR template, issue forms).
• CHANGELOG.md / ROADMAP.md — what changed, and what is queued next.

The skills

23 skills. Scripting: linux- python- javascript- typescript- golang- makefile-script-developer. Authoring: skill-builder · generic-by-design. Planning: information-architecture · deep-discovery · plan-interview · architecture-audit. CI/CD: gitops-pipeline-developer · gitops-cd-developer. IaC: terraform-module-developer. Hygiene: pre-commit-setup. QA: qa. Presentations: interactive-deck-builder. Editing: humanizer (prose) · ui-deslop (visual design). Memory: autodream. Teaching: teacher-mode. Data: xquik-x-data (third-party service).

Frontmatter contract

Every SKILL.md declares these keys, in this order:

---
name: <kebab-case, must equal the directory name>
version: <semver>
description: |
  <block scalar. The auto-invoke trigger, so name every domain and the casual
  phrasings a user might actually type. Must contain "use this skill" / "use when" /
  "whenever". Hard limit 1024 characters.>
license: MIT
compatibility: claude-code opencode
allowed-tools:
  - <only what the skill genuinely uses>
metadata:
  author: MKAbuMattar
  requirements: >-              # optional; runtime needs, not client support
    <e.g. "Go 1.22+ on Linux, macOS, or Windows">
---

Two distinctions worth keeping straight:

• compatibility means clients (claude-code opencode). Runtime prerequisites — language versions, required CLIs — go in metadata.requirements. Conflating them hides the prerequisite from anyone scanning for client support.
• description is a trigger, not a summary. It is the only thing an agent sees when deciding whether to load the skill. Write the phrasings a user types, not a précis.

Working commands

No compiler; validation is one script, and it is the source of truth.

Test a change by loading the skill in a client and running a real task, not by any build step.

Automation

Both entry points call the same __SCRIPTS__/validate-all.sh, so a local pass and a green CI run cannot disagree.

• CI — .github/workflows/validate.yml runs on every pull request and on pushes to main / develop. The skills job is blocking: it runs the gate, then checks the frontmatter contract (required keys, name matches directory, LICENSE present, description under 1024 chars and free of hyphenated words split across lines). The fingerprints and descriptions jobs are advisory and never block a merge.

• Local hooks — .pre-commit-config.yaml. Install with:

  uv tool install pre-commit
  pre-commit install --hook-type pre-commit --hook-type commit-msg

  The second --hook-type is not optional. Without it the Conventional Commits check is installed but never runs, which looks identical to passing.

Two deliberate choices worth knowing before changing them:

• The fingerprint scan is advisory, in both places. The scanner cannot tell a real leak from a skill that legitimately names vendors, and generic-by-design's own documentation is full of the latter. A gate that cries wolf trains people to reach for --no-verify, which costs more than the check is worth.
• Conventional Commits are enforced with commitizen, not commitlint. commitlint is Node-based, and this repo deliberately ships no package manifest.
• The description eval is a lexical proxy, and advisory for that reason. It measures whether a skill outranks its 22 siblings on a query, which is computable. It does not measure whether a model would load it, which is not. Gating on it would invite tuning a description to satisfy a token scorer, and the guide explicitly warns against overfitting to failed queries. Fixtures may set "proxy_blind": true where the deciding signal is semantic; those are reported separately rather than counted as failures.

Conventions

• Progressive disclosure is the point. SKILL.md stays under 200 lines. When it grows past that, move detail to references/ and leave a one-line index plus an explicit load trigger (Load references/x.md for ...). A body over ~5k tokens is loaded in full on every invocation — that cost is why the limit exists.
• One skill, one directory, no cross-imports. A skill must work when installed alone. Never reference a sibling skill's files by relative path; name the skill in prose instead.
• Self-contained scripts. No package manifest, no install step. bash and standard Unix tools; for Python, a PEP 723 inline-dependency header so uv run <script>.py resolves deps with nothing to install first. Use uv as the Python package manager, never pip.
• Generic by design. No org names, internal hostnames, real vendor stacks asserted as "ours", absolute home paths, or fork-source attributions in skill content. Concrete patterns belong in generic-by-design/scripts/data/*.txt (gitignored tool data), never in prose. Run the scanner before publishing anything adapted from internal work.
• Every references/ file earns its load trigger. An undocumented reference file is dead weight the agent never reads.

Hard rules

• validate-skill.sh must report 100% for any skill you touch. A green score with a suspicious number is worse than a red one — if a count looks wrong, verify the checker before trusting it.
• name must equal the directory name. Installers resolve by path; a mismatch installs a skill that cannot be invoked.
• One LICENSE per skill directory. Single-skill installs copy only that directory.
• Never vendor a third-party skill without its license and explicit attribution — and prefer pointing at the upstream marketplace instead.
• Clean commits. Conventional-commit subject + body. No Co-Authored-By trailer, no "Generated with Claude Code", no Opus/Anthropic/AI mention of any kind.
• Don't commit local tooling. .serena/, .claude/settings.local.json, .DS_Store, and populated scripts/data/*.txt wordlists are git-ignored — never add them.
• Bump a skill's version when its content changes materially.
• Push only when asked.