agents-creator

name	agents-creator
description	Use when initializing, creating, updating, reviewing, or generating `AGENTS.md` files that provide project-level guidance to AI coding agents. Use when analyzing a codebase to decide whether guidance belongs in `AGENTS.md`, a reusable skill, or another document.
license	CC-BY-NC-SA-4.0
metadata	{"copyright":"Caleb Cushing"}

Agents Creator

Guidance for creating and maintaining AGENTS.md files.

Overview

AGENTS.md provides project-level instructions to AI coding agents. It governs the directory it lives in and all subdirectories. Deeper AGENTS.md files take precedence over parent ones, and user instructions always take highest precedence.

REQUIRED SUB-SKILL: Use writing-skills when the guidance would be better expressed as a reusable skill. This skill is provided by the Superpowers plugin; install it alongside this plugin for the referenced workflow to be available.

When to Create or Update

• Conventions agents must follow on every session
• Directory-specific rules differ from parent directories
• You modify files, styles, structures, workflows, or configs AGENTS.md describes

What Belongs in AGENTS.md

• Stable, low-churn conventions
• Build, test, lint, and formatting commands
• License and copyright requirements
• Skill routing guidance
• References to source-of-truth files and retrievable state

What Does NOT Belong in AGENTS.md

Avoid duplicating or high-churn content:

• Bug workarounds, migration steps, or per-ticket instructions
• Detailed API or library documentation
• Rarely-needed tasks; tell agents in the moment instead
• Human contributor guidance → CONTRIBUTING.md
• Values retrievable with local tools → point to the tool or file

For reusable techniques, write a skill. For temporary guidance, use CLAUDE.md or GEMINI.md.

Reference, Do Not Duplicate

Point agents to the canonical source rather than copying it:

• Tool versions → .tool-versions, package.json
• Dependencies → package.json, build.gradle.kts, uv.lock
• Scripts → package.json, Makefile, --help
• Git state → git status, git log, gh pr view
• Environment → env, asdf current
• Plugin manifest → .kimi-plugin/plugin.json

If a value can change between sessions, prefer live retrieval.

CONTRIBUTING.md for Human Contributors

Put human-oriented contribution guidance in CONTRIBUTING.md. Load it when it exists and reference it from README.md.

Template

<!--
SPDX-FileCopyrightText: Copyright © 2026 Author Name
SPDX-License-Identifier: CC-BY-NC-SA-4.0
-->

# Project Name

One-line description.

## Build and Test

- Run tests: `<test-command>`
- Run lint: `<lint-command>`

## Source of Truth

- Tool versions → `<version-file>`
- Scripts → `<script-source>`

## Maintenance

Update this file when you change workflows it describes.

Format

• Keep it concise; agents load this on every session
• Use clear headings and scannable lists
• Include SPDX copyright and license identifiers
• Place the file at the root or directory level it governs

Token Efficiency

AGENTS.md consumes context on every session:

• Move detailed reference to skills or separate docs
• Cross-reference skills instead of duplicating guidance
• Prefer bullets and tables over paragraphs
• Point to --help or external references instead of copying them

Maintenance Rule

If you modify anything AGENTS.md describes, update AGENTS.md in the same change.