AGENTS.md Generator Skill

Netresearch AI skill for generating and maintaining AGENTS.md files following the agents.md specification.

What is AGENTS.md? A context file written for AI coding agents, not humans. Human readability is a side effect, not a goal. Adopted by 60,000+ open-source projects. See the official specification and best practices from 2,500+ repositories.

Standards Compliance

This skill implements two complementary standards:

1. agents.md - The file format this skill generates. A simple Markdown convention for guiding AI coding agents, supported by Claude Code, GitHub Copilot, Cursor, and 60,000+ open-source projects.

2. Agent Skills - How this skill is packaged and distributed. A portable format for procedural knowledge that works across AI agents.

Supported Platforms:

• ✅ Claude Code (Anthropic)
• ✅ Cursor
• ✅ GitHub Copilot
• ✅ Other skills-compatible AI agents

Features

• Thin Root Files - ~30 lines with precedence rules and global defaults
• Scoped Files - Automatic subsystem detection (backend/, frontend/, internal/, cmd/)
• Auto-Extraction - Commands from Makefile, package.json, composer.json, go.mod
• Multi-Language - Templates for Go, PHP, TypeScript, Python, and hybrid projects
• Idempotent Updates - Preserve existing structure while refreshing content
• Managed Headers - Mark files as agent-maintained with timestamps

Installation

Marketplace (Recommended)

Add the Netresearch marketplace once, then browse and install skills:

# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace
/plugin install agent-rules@netresearch-claude-code-marketplace

Without a marketplace

Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own:

mkdir -p ~/.claude/skills
git clone https://github.com/netresearch/agent-rules-skill.git \
  ~/.claude/skills/agent-rules

It loads as agent-rules@skills-dir on the next session. Update with git -C ~/.claude/skills/agent-rules pull and start a new session; remove it by deleting the directory. This route has no claude plugin update.

npx (skills.sh)

Install with any Agent Skills-compatible agent:

npx skills add https://github.com/netresearch/agent-rules-skill --skill agent-rules

Download Release

Download the latest release and extract to your agent's skills directory.

Git Clone

git clone https://github.com/netresearch/agent-rules-skill.git

Composer (PHP Projects)

composer require netresearch/agent-rules-skill

Requires netresearch/composer-agent-skill-plugin.

npm (Node Projects)

npm install --save-dev \
  @netresearch/agent-skill-coordinator \
  github:netresearch/agent-rules-skill

Requires @netresearch/agent-skill-coordinator, which discovers the skill in node_modules and registers it in AGENTS.md via a postinstall hook. For pnpm, also allowlist the coordinator's postinstall:

{
  "pnpm": {
    "onlyBuiltDependencies": ["@netresearch/agent-skill-coordinator"]
  }
}

Usage

The skill triggers on keywords like:

• "AGENTS.md", "agents file"
• "agent documentation", "AI onboarding"
• "project context for AI"

Example Prompts

"Generate AGENTS.md for this project"
"Update the agents documentation"
"Create scoped AGENTS.md files for each subsystem"
"Validate AGENTS.md structure"

Supported Projects

Structure

agents/
├── SKILL.md              # AI instructions
├── README.md             # This file
├── LICENSE-MIT           # Code license (MIT)
├── LICENSE-CC-BY-SA-4.0  # Content license (CC-BY-SA-4.0)
├── composer.json         # PHP distribution
├── references/           # Convention documentation
├── scripts/              # Generator scripts
│   ├── generate-agents.sh
│   ├── validate-structure.sh
│   └── detect-scopes.sh
└── templates/            # Language-specific templates
    ├── go/
    ├── php/
    ├── typescript/
    └── python/

Contributing

Contributions welcome! Please submit PRs for:

• Additional language templates
• Detection signal improvements
• Script enhancements
• Documentation updates

Governance and policies

This repository follows the organisation-wide policies of netresearch:

• Governance: roles, how changes are decided and disputes resolved, and who controls access to sensitive resources.
• Roadmap: the maintenance work planned and excluded for the coming year.
• Handling of dependency and code analysis findings: which vulnerability, licence and static-analysis findings block a change, the deadlines for the others, and how exceptions are recorded.
• Secret management: where CI secrets are stored, who can access them, and when they are rotated.
• Access roster: the accounts with admin, maintain and write access to this repository.

Checks that run on every pull request to main (.github/workflows/security.yml):

• Dependency review: fails on a known vulnerability of severity high or critical in a dependency the pull request adds or changes.
• Composer Audit: fails on a known vulnerability in a Composer dependency.
• Opengrep: static security analysis of the repository's code; which findings fail the check is set by the organisation's static analysis rule.
• Betterleaks: fails on a committed secret.
• zizmor: static analysis of the GitHub Actions workflows; findings go to code scanning and do not fail the check.

What you can and cannot expect from this repository in terms of security, with its threat model: docs/SECURITY-ASSURANCE.md.

License

This project uses split licensing:

• Code (scripts, workflows, configs): MIT
• Content (skill definitions, documentation, references): CC-BY-SA-4.0

See the individual license files for full terms.

Credits

Developed and maintained by Netresearch DTT GmbH.

Made with ❤️ for Open Source by Netresearch