Skip to content

AGENTS.md

Latest commit

 

History

History
103 lines (81 loc) · 10.8 KB

AGENTS.md

File metadata and controls

103 lines (81 loc) · 10.8 KB

AGENTS.md

Context for AI agents working inside this repo. Human-facing docs live in README.md and CONTRIBUTING.md; this file is the agent entry point and complements (does not duplicate) those.

⚠️ Don't confuse this AGENTS.md with templates/AGENTS.md. This file is the contract for an agent contributing to this repo. The template is what consuming projects copy to their own root so the skills published from this repo can resolve project-specific values. Different audiences, different files.

What this repo is

Frontify/skills publishes self-contained agent skills conforming to the open Agent Skills spec. Each skill is one folder under skills/<kebab-case>/ containing a SKILL.md (with YAML frontmatter) plus optional references/, scripts/, assets/. Skills are installed via npx skills add Frontify/skills [...] into any compatible agent (Claude Code, Cursor, Codex, OpenCode, Gemini CLI, etc.).

Repo map

skills/             — the shipped skills, one folder per skill
  <skill-name>/
    SKILL.md          required — frontmatter + body
    references/       optional — task templates, checklists, etc.
                      Canonical groupings (not enforced by tooling):
                        - workflow `write-*` and `fix-*` skills
                        - quality-gate skills (empirical-proof, adversarial-review,
                          distillation-discipline, etc.)
                        - standalone `persona-<name>` skills
                      Every skill is fully self-contained — no cross-skill imports.
templates/          — copy-into-consumer-repo templates
  AGENTS.md           the contract template that consuming repos paste at their own root
docs/               — design-rationale documentation, every claim cited
  README.md           docs index (table of contents)
  activation.md       why descriptions are in directive form
  body-anatomy.md     numbered rules, length budgets, anti-patterns sections
  execution.md        the two reliability problems and the forced-visible-output fix
  self-containment.md why skills don't reference each other; the AGENTS.md contract
  task-files.md       why most workflow skills ship a task template, vs. plan-mode artefacts
  scope.md            what the repo deliberately is and is not
  sources.md          full bibliography
README.md           — human-facing intro, install, AGENTS.md contract overview
CONTRIBUTING.md     — human-facing structure rules, frontmatter rules, PR workflow
AGENTS.md           — this file (agent entry point)
CLAUDE.md           — thin pointer to this file

Rules an agent MUST follow when modifying this repo

These are mandatory. They restate (compactly) the load-bearing rules from CONTRIBUTING.md so an agent doesn't have to load both. Read CONTRIBUTING.md for the full rationale before opening a PR.

  1. Read CONTRIBUTING.md before adding or modifying any SKILL.md. Non-negotiable. It defines the frontmatter rules, agent-agnostic phrasing rules, and the AGENTS.md contract pattern that every skill body must follow.
  2. Skill folder names are lowercase kebab-case. name in frontmatter matches the folder name exactly.
  3. description follows the directive form. Four clauses in order: WHAT (imperative verb + object) · ALWAYS apply this skill when (explicit triggers, including "even if…" for implicit signals) · Do not directly · Skip this skill for — where Y names the task type that belongs elsewhere, never a sibling skill name (self-containment forbids assuming any sibling is installed). Target 350–600 characters; hard cap 800 (above 600 the description starts working against itself — trim, don't grow). Empirically, this form activates ~3× more reliably than passive "Use when…" phrasing.
  4. No cross-skill references in SKILL.md. Skills are installed individually. If a related rule is load-bearing, restate it inline. Do not link sibling skills from a SKILL.md. The persona skills are the canonical example: each persona-<name>/SKILL.md is fully standalone — installing write-audit does not pull in persona-auditor.
  5. No hardcoded project commands in SKILL.md prose. Reference the consuming repo's AGENTS.md instead — for example, "the project's validation command (AGENTS.md > Commands > Validation)". Mustache placeholders ({{cmdValidate}}, {{slug}}, …) are fine inside references/*.md task templates because those are agent-instantiated scaffolds.
  6. No agent-specific paths in SKILL.md unless the skill is genuinely about that infrastructure. The non-exhaustive forbidden list covers both legacy and current agent-specific surfaces: ~/.claude/..., .claude/, .cursorrules (deprecated), .cursor/rules/..., .github/copilot-instructions.md, .agents/..., docs/agents/..., /plugin install …. If a new agent introduces another path, add it here.
  7. SKILL.md body stays under ~500 lines. Per the open spec. Push detail into references/. Practical target: under 200 lines; well-shaped persona and quality-gate skills typically land around 60–80.
  8. Forced-visible-output for verification steps. Any ## Self-review (or equivalent) block must back every claim with a paste of actual command/file output, not a paraphrase. Use the ### Verification outputs (paste actual command output — do not paraphrase) header pattern.
  9. Update the README skills table when adding or removing a skill. It is hand-maintained.
  10. Flag any out-of-contract AGENTS.md value your skill needs in the PR description. Don't unilaterally extend the contract from inside a skill — propose the extension in the PR.

Where things live (when modifying)

If you are … Read first Then edit
Adding a new skill CONTRIBUTING.md (full) skills/<new-skill>/SKILL.md (use the minimal template at the bottom of CONTRIBUTING.md)
Editing an existing skill the skill's own SKILL.md the file in place
Adding a task template / reference CONTRIBUTING.md § Bundled resources skills/<skill>/references/<file>.md
Updating the AGENTS.md contract for consumers README.md § The AGENTS.md contract and CONTRIBUTING.md § The AGENTS.md contract (for skill authors) templates/AGENTS.md and the relevant docs
Updating design rationale or adding a citation The matching file in docs/ the same file (and add the source to docs/sources.md)

Project commands

This repo is documentation-only — there is no compiled artefact, and (deliberately) no automated validation, CI, or scripts shipped in-tree. The repo is exclusively a container for skills + their surrounding documentation.

  • Validation: none. PR review is visual / reviewer-driven against the rules above.
  • Test: n/a — no executable code.
  • Format: Markdown formatting is hand-maintained; respect existing style (sentence case headings, no trailing whitespace, fenced code blocks with language tags). Run your editor's prettier if available.

If a future validation rule emerges that all reviewers agree should be enforced, propose it in a PR — but the default stance is "no automation in this repo".

Conventions specific to this repo

  • Sentence-case headings. Not Title Case.
  • Numbered hard rules use the form ### 1. <Rule> — not ### Rule 1 or ### 1) <Rule>.
  • description field starts with a capital letter, ends with a period.
  • No emojis in SKILL.md bodies unless quoting an existing pattern (e.g. ❌ in anti-pattern lists).
  • Mustache placeholders use {{double-braces}} inside references/*.md. Document new placeholders inline so future authors don't reinvent names.
  • Markdown links in SKILL.md use repo-relative paths only when pointing inside a skill folder (e.g. references/task-template.md); never reach across skill folders.

Out of scope (what NOT to add)

  • Stack-specific skills (e.g. "React 19 best practices", "Postgres index patterns"). This repo is universal agent-workflow disciplines only.
  • Vendor-specific skills (Datadog, Snowflake, AWS, etc.). Same reason.
  • Engineering-domain skills enforcing a particular operational practice (auth patterns, incident response, observability/caching strategy, postmortem format). The goal is how an agent works, not what an engineer should know.
  • Internal Frontify product docs. Product knowledge lives in product repos.
  • Automation, scripts, GitHub Actions, validation harnesses, evaluation frameworks. The repo is exclusively a container for skills + documentation. If you find yourself authoring tooling, that tooling belongs in its own repo.

Pointers for common follow-up tasks

  • "Why is the description / body / structure of an existing skill the way it is?" → docs/README.md is the entry point; each principle has its own page. Every claim there cites a primary source (the 650-trial activation study, Anthropic best practices, Lost in the Middle, the two-reliability-problems analysis).
  • "What's deliberately not in this repo and why?" → docs/scope.md.
  • "How do consumers install this?" → README.md § Quickstart.
  • "What does a consuming repo need to do?" → README.md § Quickstart (step 2 — set up AGENTS.md) and § The AGENTS.md contract.
  • "What is the contributor checklist?" → CONTRIBUTING.md § Workflow.

When you're stuck

If a request would require breaking one of the rules above (typically the self-containment, hardcoded-commands, agent-specific-paths, or forced-visible-output rules), stop and surface the conflict in your response rather than working around it. The rules are load-bearing — every existing skill assumes the others were authored under them.