Skip to content

Link agent instruction templates from main README for discoverability #31

Description

@dieterbaier

Goal

Improve discoverability of the new agent instruction templates by ensuring they are clearly referenced and linked from the main repository README, making it easy for new users and projects to find and understand these templates during onboarding.

Rationale

PR #29 adds three new agent instruction templates in templates/agents/:

  • global-agent-instructions.md
  • project-agents.md
  • github-copilot-instructions.md

These templates are critical for:

  • Setting up new projects with the toolkit
  • Configuring local agent installations
  • Establishing a shared instruction contract across tools and projects

However, if the main README does not link to or prominently feature these templates, they may be hard for users to discover, especially when first exploring the repository or onboarding a new project.

First Step: Audit Main README

Before adding or updating links, check whether:

  • The main README.md already contains a section about agent setup or instructions
  • Links to templates/agents/ or individual template files already exist
  • The README explains where these templates should be placed in consuming projects
  • The README mentions the relationship between project instructions and the toolkit

If links exist, assess whether they are prominent, clear, and easy to find.

Implementation

If gaps or unclear links are found, enhance the main README to include:

  1. A dedicated section (e.g., "Agent Setup" or "Installation & Configuration") that:

    • Explains what agent instructions are and why projects need them
    • Lists the three templates and their purpose
    • Provides links to each template file
    • References the toolkit's AGENTS.md and skills/bootstrap-project/SKILL.md for detailed guidance
  2. A quick-reference table or checklist showing:

    • Which template goes in which directory
    • What each template is for
    • Which audiences should use each one (individual developers, projects, teams, etc.)
  3. Integration with existing README structure:

    • Decide if this fits best in a "Getting Started" section, a "Templating" section, or "Project Setup"
    • Ensure it is positioned early enough that new visitors see it

Definition of Done

  • Audit complete; current README coverage documented in issue comments
  • Main README updated with clear, discoverable links to agent templates
  • Template purpose and placement (global vs. project) are explained concisely
  • Links are tested and point to the correct template files

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions