Skip to content
Conduit

skill

agents-md

AI-native dev standards (bilingual EN/中文). For teams whose code is written by Claude Code / Cursor / Codex / Devin / Windsurf agents.

maweis1981/agents-mdcommunitylistedunreviewed
Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/maweis1981/agents-md itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 26, 2026

agents-md

AI-Native Development Standards for the Vibe Coding Era

A bilingual (English / 简体中文) specification and installable skill pack for how AI agents — Claude Code, Cursor, Codex / OpenAI Agents, Devin, Windsurf, and friends — should commit code, manage branches, run CI/CD, handle database migrations, and ship to production.

English ・ 简体中文

Why this exists

AI agents generate code at a speed humans were never designed to commit at. Naively wiring an agent into Git produces:

  • GitHub API rate-limit storms
  • Runaway GitHub Actions / CI bills
  • Unreadable commit history (fix, wip, update, asdf × 500)
  • Deployment storms in production
  • Always-on database connections from short-lived agents
  • Schema migrations applied through pooled connections (and breaking)

agents-md is a compatibility layer between AI coding and traditional Git workflows. It encodes the rules a team needs so that AI can iterate fast locally while the system remains low-churn and production-safe. It also defines a Backlog-to-Kanban workflow for GitHub Issues and Projects, including multi-repository ownership and safe planning boundaries for agents.

What's inside

PathPurpose
STANDARDS.md / STANDARDS.zh-CN.mdThe full single-file spec — read this first.
docs/Chaptered, human-readable docs (EN + zh-CN).
skills/Installable Claude Code Skill packages.
templates/Drop-in CLAUDE.md, AGENTS.md, GitHub Actions workflow, settings.
CLAUDE.mdEntry point Claude Code reads automatically.
AGENTS.mdEntry point Codex / OpenAI Agents / Cursor read automatically.

Quick install

Option A — Drop the whole standard into your project

# In your repo root
curl -L https://raw.githubusercontent.com/maweis1981/agents-md/main/templates/CLAUDE.md   -o CLAUDE.md
curl -L https://raw.githubusercontent.com/maweis1981/agents-md/main/templates/AGENTS.md   -o AGENTS.md

Both files reference the canonical STANDARDS.md and contain the minimum rules the agent must follow.

Option B — Install a single Skill (Claude Code, superpower-style)

# Project-scoped skill
mkdir -p .claude/skills
cp -r path/to/agents-md/skills/ai-native-git-workflow .claude/skills/

Claude Code will autoload the skill when its trigger conditions match (see the YAML frontmatter in each SKILL.md).

Option C — Vendor the whole repo as a submodule

git submodule add https://github.com/maweis1981/agents-md docs/agents-md

Tip on stable URLs: The curl commands above point at main. For a reproducible setup, replace main with a tagged release (e.g. v0.2.0) so your install pinning doesn't drift when this repo evolves.

Option D — Enforce the rules in CI

This repo also ships small bash lint scripts under scripts/ that check Conventional Commits, branch naming, bilingual symmetry, and internal links. Copy them into your own project's scripts/ and wire them into a workflow modeled on .github/workflows/lint.yml. The companion templates/.commitlintrc.json configures @commitlint/cli with the same ruleset for projects that already run commitlint via Husky.

The core rules at a glance

  1. AI may modify frequently — but must commit infrequently.
  2. Never let an agent push directly to main. Use ai/<feature> branches.
  3. One PR = one feature. Merge with squash, not merge-commits.
  4. No on: push full deploys. Use pull_request or workflow_dispatch.
  5. Production deploys come from main only. Agent branches → preview / staging.
  6. Migrations run on a direct connection. App runtime uses a pooled one.
  7. Aggregate schema changes. No "one migration per prompt".
  8. Search before generating. Reuse existing components, utils, schemas, prompts.
  9. No infinite retry loops. Cap retries, surface failure, ask a human.
  10. Event-driven, not polling. Scale-to-zero is the default posture.
  11. Issues are the work record. Start only Ready work, keep Project status truthful, link PRs, and require human authority for new commitments.

The full ruleset, including rationale and examples, lives in STANDARDS.md. The operational GitHub workflow is available in docs/github-issues-projects.md.

Status

v0.2.0 — adds AI-specific (secrets / prompts / evals / observability) and platform-engineering (IDP / CODEOWNERS / doc-freshness / DORA) chapters on top of the founding release. The spec is stable enough to adopt, and we expect breaking changes only at major version bumps.

Contributing

PRs, translations, and additional skill packs are welcome. See CONTRIBUTING.md. All contributors are expected to follow the Code of Conduct.

License

MIT. Use it, fork it, ship it.

Git was not designed for AI agents. Until something better arrives, these rules are the bridge.

↑↓ navigate openesc close