AGENTS.md — workflows

Overview

GitHub Actions workflows and CI/CD automation

Key Files

File	Purpose
release.yml	Release
validate-agents.yml	Validate AGENTS.md

Workflow files

• Workflows: 2 workflow file(s)

Directory structure

.github/
  workflows/
    ci.yml              → Main CI workflow (lint, test, build)
    release.yml         → Release/deploy workflow
    dependabot.yml      → Dependency updates
  actions/
    <action-name>/      → Composite actions (reusable)
      action.yml
  CODEOWNERS            → Code ownership rules
  pull_request_template.md

Workflow conventions

• Pin action versions with full SHA, not tags (uses: actions/checkout@abc123...)
• Minimal permissions: Use permissions: block, never use permissions: write-all
• Reusable workflows: Extract common patterns to .github/workflows/reusable-*.yml
• Job dependencies: Use needs: to express dependencies
• Caching: Use actions/cache for dependencies (npm, composer, go)

Naming conventions

Type	Convention	Example
Workflow file	<purpose>.yml	ci.yml, release.yml
Workflow name	Title Case	CI Pipeline, Release
Job ID	kebab-case	build-and-test, deploy-staging
Step name	Sentence case	Install dependencies
Secret	SCREAMING_SNAKE	DEPLOY_TOKEN, NPM_TOKEN

Common patterns

Basic CI workflow

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

Matrix builds

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
        node: ['18', '20', '22']
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
        with:
          node-version: ${{ matrix.node }}

Reusable workflow

# .github/workflows/reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '20'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}

Conditional deployment

jobs:
  deploy:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    needs: [test, build]
    environment: production
    steps:
      - name: Deploy
        run: ./deploy.sh

Security & safety

• NEVER expose secrets in logs: use ::add-mask:: for dynamic secrets
• Pin actions to full commit SHA, not mutable tags
• Minimal permissions: Start with contents: read, add only what's needed
• Environment protection: Use environments with required reviewers for deploys
• Secret scanning: Enable in repository settings
• Dependency review: Use actions/dependency-review-action for PRs
• OIDC: Prefer OIDC over long-lived secrets for cloud providers

PR/commit checklist

• Actions pinned to full SHA (not tags)
• Permissions block uses minimal required permissions
• Secrets are not exposed in logs
• Workflow syntax valid: actionlint or GitHub UI validation
• Matrix strategy covers required versions/platforms
• Caching configured for dependencies

Patterns to Follow

Prefer looking at real code in this repo over generic examples. See Golden Samples section above for files that demonstrate correct patterns.

When stuck

• GitHub Actions docs: https://docs.github.com/en/actions
• Workflow syntax: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
• Action marketplace: https://github.com/marketplace?type=actions
• Use act for local testing: https://github.com/nektos/act
• Check existing workflows in this repo for patterns

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

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

Type	Detection	Features
Go	go.mod	Version extraction, CLI tool detection
PHP	composer.json	TYPO3/Laravel/Symfony detection
TypeScript	package.json	React/Next.js/Vue/Express detection
Python	pyproject.toml	Poetry/Ruff/Django/Flask detection
Hybrid	Multiple markers	Auto-creates scoped files per stack

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

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