Configure AI for your codebase

AI agents need reliable project context to follow your repository's structure and conventions. Build on the documentation and automation you already maintain. Start with one repeated problem, reuse an existing customization when it fits, and add your repository's own guidance only where needed.

This guide first helps you choose the right customization, then shows how the pieces fit together in a TypeScript API project. You'll apply what you need to your repository with focused project instructions and optional extensions. Finally, you'll try a representative task and refine the guidance based on the results.

The example uses the GitHub Copilot harness in Visual Studio Code, with alternatives for the Anthropic Claude and OpenAI Codex harnesses. A harness is the agent environment that provides tools and loads customizations. It is separate from the language model.

Before you start

Prepare your session

Choose the article's tabs for your harness, not your language model. For example, a Claude model in a Copilot session still uses the Copilot harness.

Note

Work in the current folder rather than a new worktree so new sessions can access your uncommitted customization files. In the Agents window, leave New Worktree unselected.

Note

Claude and Codex harnesses are disabled when Copilot enterprise-managed settings apply. Contact the IT team that deployed the settings to discuss access.

Review your existing setup

Before adding another customization, check what the project already provides:

  • Existing instruction files, skills, agents, and installed plugins for your harness.
  • Setup, build, lint, and test commands documented in README.md, CONTRIBUTING.md, or other project documentation.
  • Representative implementations, tests, and shared helpers that demonstrate the conventions you want followed.

Fix missing, stale, or unreliable documentation and commands that affect the task you want to improve. A customization should point to those shared sources rather than maintain a separate version solely for the agent.

If you haven't used an agent on this repository yet, run a representative task and use its result as a baseline. Otherwise, choose one recurring problem and note what the agent currently does and what a better result would look like. For example, generated API tests duplicate setup code, but should reuse the project's existing test helper.

Choose the right customization

Choose the customization that matches the need. A one-time requirement belongs in the current prompt, not shared project configuration.

What you encounter Smallest useful response
A published workflow already covers the capability you need Reuse an existing skill or plugin before building another
The agent puts handlers in the wrong layer or uses the wrong project command Add project instructions pointing to the expected structure, examples, and commands
Generated tests repeatedly duplicate shared setup Add scoped rules for the relevant test files
You repeatedly need an API investigation with the same scope and output Define a custom agent for that role
You repeat the same procedure to prepare a change for review Package the procedure as an agent skill
A command needs to run at a supported workflow event without the model requesting it Configure a hook

Example: Customize an API project

Consider a TypeScript API project with existing application code and tests. The .github entries below show the optional customizations discussed in this example, not files that every project needs:

your-project/
  CONTRIBUTING.md              # Build, lint, and test commands
  src/
    api/routes/                # HTTP handlers
    schemas/                   # Request validation
    repositories/              # Data access
  tests/
    api/                       # Endpoint tests named *.test.ts
    helpers/createTestApp.ts   # Shared application setup for tests
  .github/
    copilot-instructions.md    # Copilot project instructions
    instructions/
      api-tests.instructions.md
    agents/
      researcher.agent.md
    skills/
      validate-change/
        SKILL.md

The team wants new handlers to follow this structure, API tests to reuse their existing setup, a researcher to explain request flows, and a repeatable procedure for checking an API change. These are different needs, not reasons to keep adding rules to one instruction file.

The four files below show one way to separate them for the Copilot harness. Their full paths are relative to the repository root. Adapt them to files that exist in your project, and merge useful guidance into existing customizations rather than replacing them wholesale. You don't need all four files to get started.

.github/copilot-instructions.md
# API project conventions

* Put HTTP handlers in `src/api/routes`.
* Put shared request-validation schemas in `src/schemas`.
* Keep database access in `src/repositories`, not in HTTP handlers.
* Read a nearby implementation before adding a new handler or schema.

## Project commands

Use the build, lint, and test commands documented in `CONTRIBUTING.md`.

Select the code to copy it manually.

.github/instructions/api-tests.instructions.md
---
applyTo: 'tests/api/**/*.test.ts'
---
# API tests

* Reuse application setup from `tests/helpers/createTestApp.ts`.
* Check the response status and body for the requested behavior.
* Keep each test's data independent of other tests.

Select the code to copy it manually.

.github/agents/researcher.agent.md
---
name: Researcher
description: Trace API request handling and explain existing patterns without editing files
tools: ['read', 'search']
---
Investigate the API behavior identified in the request.
Follow the handler through validation and data access.
Read related tests to understand the expected behavior.

Return:
* Relevant files and symbols.
* A concise explanation of the request flow.
* Existing patterns to reuse for the proposed change.
* Open questions that the available code does not answer.

Do not edit files or run terminal commands.

Select the code to copy it manually.

.github/skills/validate-change/SKILL.md
---
name: validate-change
description: Check an API change using the project's tests and lint commands. Use when preparing a change for review.
---
# Validate an API change

1. Inspect the changed handlers, schemas, repositories, and related tests.
1. Read `CONTRIBUTING.md` for test, lint, and setup commands.
1. Choose the smallest set of checks that covers the changed behavior.
   If a command or required tool is unavailable, report the limitation.
1. Run those checks without changing application code or weakening tests.
1. Summarize the commands, results, and remaining gaps.

Select the code to copy it manually.

.github/copilot-instructions.md: Lines 3-10

Keep repository knowledge shared

Project instructions describe decisions that matter across tasks: where code belongs, how layers interact, and where to find project commands. Keep this knowledge in one place instead of repeating it in every prompt or custom agent. For your repository, replace the example paths and remove rules that don't address a recurring problem.

.github/instructions/api-tests.instructions.md: Line 2

Narrow guidance to the files that need it

The pattern targets API test files, such as tests/api/users.test.ts, rather than the handler in src/api/routes/users.ts. It is relative to the repository root, not the instructions directory. Use a scoped file when a part of your codebase needs guidance that would be distracting in the project-wide file.

.github/instructions/api-tests.instructions.md: Lines 6-8

Put specialized conventions beside their scope

These rules describe how this team writes API tests. They complement the shared architecture rules rather than repeating them. Adapt the fixture path and conventions to existing tests in your project. You don't need a separate agent just because one directory follows different rules.

.github/agents/researcher.agent.md: Lines 2-4

Define a role for a recurring task

The researcher has a focused purpose and access to reading and search tools. Use it to trace an API request from its handler through validation and data access before deciding where to make a change. It is not another file of general coding conventions. Tool access is harness-specific, so configure available tools and permissions rather than relying on role text to restrict actions.

.github/agents/researcher.agent.md: Lines 6-14

Describe the result, not the repository again

The agent body defines the investigation and the answer it should return. It doesn't repeat the directory rules or test setup. This keeps role-specific guidance separate from shared project knowledge, so each can change without maintaining several copies of the same rules.

.github/skills/validate-change/SKILL.md: Lines 2-12

Package a procedure for repeated use

The skill describes a sequence: inspect a change, select checks, run them, and summarize the result. Its description explains when to use that procedure. Unlike the scoped test rules, it is a task you invoke or the agent selects when relevant, not a convention for every matching file. Use it with an agent that has the required tools: the researcher above has no command-execution tools, and this skill's instructions don't change that configuration.

These responsibilities are useful across harnesses, but their file locations, activation rules, and tool controls differ. Use the harness-specific steps below to create your files. Instructions guide the model; they don't guarantee that it follows your conventions.

Add project instructions

The first useful change is often one focused rule in an existing project instructions file. For example, point the agent to src/api/routes and a representative handler when it repeatedly creates handlers in the wrong layer. Keep an example of the current result so you can compare it after adding guidance. If the existing behavior already meets your needs, don't add a rule for it.

  1. Open or create the project instructions file for your harness, relative to the repository root:

    • Copilot: .github/copilot-instructions.md or AGENTS.md
    • Claude: CLAUDE.md
    • Codex: AGENTS.md

    To open the Agent Customizations editor, run Chat: Open Customizations from the Command Palette.

  2. Add the guidance needed for your recurring problem. Use the API project example as a starting point, replacing its paths and conventions with your repository's own.

  3. Preserve useful existing rules, remove conflicting or duplicate guidance, and save the file.

The example's project file is plain Markdown. You can adapt that body for another harness's project file, but don't assume that scoped-rule metadata or custom-agent tool lists transfer in the same way.

Tip

You can ask an agent in chat to improve a customization. Identify the file and describe the behavior you want to change. Ask it to inspect relevant project conventions, preserve useful existing guidance, and limit changes to the customization. Use the intended harness and review the proposed changes.

Keep the guidance focused

Keep only rules that help with your project:

  • Name real paths, commands, and conventions instead of generic advice.
  • Document decisions the agent cannot reliably infer from the code alone.
  • Resolve conflicts and remove guidance duplicated elsewhere.
  • Leave rules already enforced by formatters, linters, or CI in those tools. Explain how to run the existing checks instead of copying their configuration into prose.
  • Move specialized rules into a narrower customization when they don't belong at project scope.

Learn more about writing effective instructions. If this file addresses your need, skip the optional extensions and try the guidance.

Extend only where needed

Add another customization only when it addresses a specific need that your existing setup does not cover. Choose from the options below, or skip to trying and refining your guidance. You don't need to use every type.

Scoped rules for specialized conventions

Use scoped instructions when the agent needs conventions that apply only to particular files or directories. Keep broadly applicable rules in project instructions. A separate folder doesn't need its own instructions unless its conventions differ.

In the API project example, endpoint tests reuse a shared application setup. The scoped rules describe that test-specific convention without repeating the project-wide architecture rules.

Create the file for your harness below, or ask the agent to create it from your existing test conventions.

Create .github/instructions/api-tests.instructions.md. For the example project's TypeScript API tests, include this YAML frontmatter before the Markdown instructions:

---
applyTo: 'tests/api/**/*.test.ts'
---

Add the API test rules from the example, adapted to your repository. The pattern matches .test.ts files under tests/api, including subdirectories.

Learn more about targeted instructions and pattern syntax.

Save the scoped rules and use a matching file when you try the guidance. If you change the session's working folder for nested instructions, return to the repository root before creating other workspace customizations.

Custom agents for specialized roles

Create a custom agent when you repeatedly need a distinct role with a consistent scope, expected output, or tool configuration. Use project or scoped instructions for additional coding conventions rather than creating a role for them.

The researcher in the API project example traces a request through the code and returns findings before you decide what to change.

Adapt the researcher's role to your needs and use the file location and tool configuration for your harness:

Save the adapted researcher example as .github/agents/researcher.agent.md. Keep its tools allowlist limited to the intended reading and search tools rather than tools that can edit files, run commands, or delegate work.

Save the file and select the researcher from the agents dropdown in a new chat with the same harness. Ask it to explain an API request flow. Review its findings and tool activity.

For a complete test procedure and guidance on refining the agent's role, see Verify your custom agent.

Skills for repeatable procedures

Use an agent skill when you repeatedly explain the same multi-step procedure. Package the procedure for an agent to use rather than creating a separate role just to repeat that workflow. Use scoped instructions instead when you need a convention for particular files, not a procedure to carry out.

The validate-change skill in the API project example packages the process of selecting and running relevant checks, then summarizing their results.

Adapt that complete SKILL.md file to your repository's process. Use the directory for your harness below. A skill can also include scripts, templates, and other resources; see the testing skill and report template for a multi-file example.

Store the skill at .github/skills/validate-change/SKILL.md, with its supporting files in the same skill directory.

Review the skill and all supporting files. Keep its name consistent with the directory name, and use the description to explain when the workflow is useful. In a fresh chat, select validate-change from the / menu and give it a small task. If you also want automatic selection, try a matching request separately without naming the skill. See Verify a skill.

Hooks for event-driven actions

Use a hook when a command should run at a supported event, such as recording a tool call or running a formatter after a tool completes. Unlike an instruction or skill, the hook is invoked by the runtime at that event rather than relying on the model to request the action.

Keep ordinary build and quality checks in your existing automation. Add a hook only when running a command at a specific agent event matters, reusing existing scripts or checks where possible.

Hooks run code, and their event formats, permissions, and failure behavior depend on the harness. Review the script and its dependencies before enabling it. For setup and a connected configuration-and-script example, see Configure agent hooks. Hooks complement project guidance; they don't replace it or guarantee that the model follows other instructions.

Before building a reusable workflow or role, browse customization marketplaces for an existing skill or plugin. Plugins package related customizations so you can adopt them together. Review the publisher, included files, and supported harness before installing because a plugin can include scripts or servers that run code. Keep repository-specific rules in your project's instructions rather than duplicating a plugin's workflow. For more on how instructions, agents, skills, and hooks fit together, see Agent customization.

Try and refine your guidance

Choose a small task affected by the rule or role you added. For the API example, this could be adding a handler in the right layer, writing a test that reuses the shared setup, or explaining a request flow.

  1. Save the customization and start a fresh chat with the same harness and repository. Confirm that the file appears in the Agent Customizations editor.
  2. Repeat the task without restating the saved instructions in your prompt. Use a matching file for scoped guidance, select the custom agent for a role, or explicitly invoke a skill for its workflow.
  3. Check References, where available, or inspect the request if it is unclear whether the instructions were included.
  4. Compare the actual changes and tool activity with the earlier result. Keep the model, task, and relevant context consistent where practical. Check file placement, reused patterns, and command output, not only the agent's summary.

Discovery, inclusion, and following the guidance are different checks. If a file is missing or not included, troubleshoot the customization before adding more instructions. If it is included but the result misses your goal, clarify one relevant rule and repeat the task.

Stop when the guidance addresses the need. More instructions consume context and can introduce conflicts. For a broader comparison of quality, reliability, and resource use, follow the usage optimization loop.

Keep useful customizations in version control with their supporting files, and update them when your project's structure or conventions change.