Skip to content

README.md

Latest commit

 

History

History
201 lines (158 loc) · 8.9 KB

README.md

File metadata and controls

201 lines (158 loc) · 8.9 KB

Agent Rules

This repository is the single source of truth for shared commands, skills, and protocol. target repos use the agent-sync script to handle fetching and updating.

Syncing Shared Rules to Other Repos

3 easy steps...

1. Clone this repo as a sibling to the target repo

cd <target-repo>
git clone https://github.com/dep/agent-rules.git ../agent-rules

2. Run agent-sync in the target repo

Prerequisites: jq and gh CLI (both standard for developers).

cd <target-repo>
../agent-rules/bin/agent-sync

You can optionally add the following flags to the agent-sync command:

  • --local to force local source only (offline mode)
  • --dry-run to show what would change without writing
  • --check to exit 1 if anything is out of date (CI mode)

3. Commit the results

After running agent-sync, commit the results to your repo.

Note: This script adds a new file to your repo: .agents/REPO_RULES.md. You can add your repo-specific rules and conventions to this file. Your repository's root-level AGENTS.md points to it automatically — no further setup needed.

Customization Options

The agent-sync script creates .agents/REPO_RULES.md for repository-specific rules. Additionally, you can create optional custom context files:

  • .agents/USER_RULES.md - Personal AI preferences (gitignored)
  • .agents/TEAM_RULES.md - Team conventions (gitignored)
  • .agents/LEARNING_LOG.md - Agent-maintained learning log (gitignored, opt-in)

See .agents/README.md for details on the custom context system.

Optional Github Workflow

Want to keep things in sync with a Github Workflow? Place this in your .github/workflows directory, something like agent-sync.yml:

Once added to your target repo, you will start to see Pull Requests appear.

Note: Don't forget to replace <your organization> with where your agent-rules repo lives. You'll also need to create a personal access token and store it as a repo or organization secret, secrets.AGENT_SYNC_TOKEN.

name: '🤖 Agent Sync'

on:
  pull_request:
  push:
    branches:
      - main
      - master

jobs:
  agent_sync:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
    - uses: actions/checkout@v4
      continue-on-error: true
      with:
        fetch-depth: 1
        filter: blob:none
        ref: ${{ github.event.repository.default_branch }}
    - name: Clone the agent-rules repo
      if: github.event.pull_request.head.ref != 'chore/agent-sync' && github.actor != 'dependabot[bot]' && github.actor != 'github-actions[bot]'
      continue-on-error: true
      env:
        GITHUB_TOKEN: ${{ secrets.AGENT_SYNC_TOKEN }}
      run: |
        git clone https://x-access-token:${GITHUB_TOKEN}@github.com/<your organization>/agent-rules.git ../agent-rules
    - name: Run agent-sync
      if: github.event.pull_request.head.ref != 'chore/agent-sync' && github.actor != 'dependabot[bot]' && github.actor != 'github-actions[bot]'
      continue-on-error: true
      run: ../agent-rules/bin/agent-sync
    - name: Commit and open PR for agent-sync changes
      continue-on-error: true
      if: github.event.pull_request.head.ref != 'chore/agent-sync' && github.actor != 'dependabot[bot]' && github.actor != 'github-actions[bot]'
      env:
        GH_TOKEN: ${{ secrets.AGENT_SYNC_TOKEN }}
        FEATURE_BRANCH: chore/agent-sync
        DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
      run: |
        git config user.name "agent-sync[bot]"
        git config user.email "agent-sync[bot]@users.noreply.github.com"
        if gh pr list --head "$FEATURE_BRANCH" --state open --json number --jq '.[0].number' | grep -q .; then
          echo "Open PR for $FEATURE_BRANCH already exists, skipping sync"
          exit 0
        fi
        git checkout -b "$FEATURE_BRANCH"
        git add -A
        if git diff --staged --quiet; then
          echo "No changes to commit"
        else
          git commit -m "non-production: sync agent rules"
          if git ls-remote --exit-code --heads origin "$FEATURE_BRANCH" > /dev/null 2>&1; then
            git push origin :"$FEATURE_BRANCH"
          fi
          git push origin "$FEATURE_BRANCH"
          gh pr create --base "$DEFAULT_BRANCH" --head "$FEATURE_BRANCH" \
            --title "non-production: sync agent rules" \
            --body "Auto-generated by the Agent Sync workflow. Merge to apply synced agent rules." \
          | xargs gh pr merge --auto --squash
        fi

Agent Rules Structure

Repository Structure

agent-rules/
├── .agents/                                # Source of truth for commands and skills
│   ├── commands/                           # Commands for Claude Code, Cursor, and Codex
│   ├── skills/                             # Skills for Claude Code, Cursor, and Codex
│   ├── README.md                           # Custom context system documentation (synced to repos)
│   ├── LEARNING_LOG.md.example             # Agent-maintained learning log (gitignored, opt-in)
│   └── *_RULES.md.example                  # Templates for user/team customization
├── .claude/                                # REDIRECTS to `.agents`, avoid editing these files directly
│   ├── commands/                           # symlinks (redirects) to `.agents/commands`
│   └── skills/                             # symlinks (redirects) to `.agents/skills`
├── .cursor/                                # REDIRECTS to `.agents`, avoid editing these files directly
│   ├── commands/                           # symlinks (redirects) to `.agents/commands`
│   └── skills/                             # symlinks (redirects) to `.agents/skills`
├── .codex/                                 # REDIRECTS to `.agents`, avoid editing these files directly
│   ├── commands/                           # symlinks (redirects) to `.agents/commands`
│   └── skills/                             # symlinks (redirects) to `.agents/skills`
├── bin/                                    # agent-rules related scripts
│   ├── agent-sync                          # Sync script for target repos
│   └── local-os-agent-setup.sh             # OS-level setup script
├── .mcp.json                               # MCP server configuration
├── .gitignore                              # Git ignore rules
├── AGENTS.md                               # Agent System Instructions (source of truth)
├── CLAUDE.md                               # symlinks (redirects) to `AGENTS.md`
├── CURSOR.md                               # symlinks (redirects) to `AGENTS.md`
├── CODEX.md                                # symlinks (redirects) to `AGENTS.md`
├── GEMINI.md                               # symlinks (redirects) to `AGENTS.md`
└── README.md                               # This file

USE THE .agents DIRECTORY: You must place custom skills and commands in the .agents directory to ensure that all LLM tools can access them. Do not edit the .claude, .cursor, or .codex directories directly. This rule applies to both this repo and your target repos.

Contributing

Adding a New Skill

A skill is something you can teach Claude Code, Cursor, or Codex to do, and it will invoke them organically.

  1. Create a directory in .agents/skills

  2. Create a SKILL.md file in the directory with the following format:

    ---
name: <skill-name>
version: <version>
description: <description>
---

<the actual instructions for the skill>

  3. Once a skill is in agent-rules mainline, you can use it in any target repo by running ../agent-rules/bin/agent-sync in the target repo to sync the changes

Adding a New Command

A command is essentially a custom /COMMAND you can invoke manually.

  1. Create a .md file in .agents/commands
  2. Follow the format of an existing command file
  3. Once a command is in agent-rules mainline, you can use it in any target repo by running ../agent-rules/bin/agent-sync in the target repo to sync the changes
  4. You should then be able to invoke the command by typing /COMMAND in your editor, and it will execute the command.

Contribution Best Practices

  • Keep skills and commands focused and single-purpose
  • Include a version number, for skills in the metadata section of the file, and for commands in the H1 of the file
  • Increment the version number when you make changes to an existingskill or command
  • Include context and constraints explicitly
  • Use clear, descriptive names
  • Document any assumptions or prerequisites
  • It's always best to "dogfood" your own commands and skills before promoting them into this library

Resources