Agent Configuration

AI Agent Configuration

When to use this skill

• Set up agent configuration for a new repo or team
• Decide whether guidance belongs in AGENTS.md, CLAUDE.md, settings, hooks,

skills, plugins, or MCP

• Tighten permission and safety guardrails without over-approving commands
• Share reusable agent defaults across a team without creating prompt sprawl

Prefer a narrower sibling skill when the main job is more specific:

• agent-workflow for day-to-day execution loops, handoffs, and runtime flow
• skill-standardization for auditing or rewriting a specific SKILL.md
• security-best-practices for broader application hardening beyond agent

configuration

Instructions

Step 1: Classify the configuration job before changing files

Sort the request into one or two lanes:

• instruction-scope: always-on project rules, repo context, coding standards
• guardrails: permissions, hooks, approvals, dangerous-command blocking
• capability-packaging: skills, plugins, extensions, MCP, custom commands
• team-sharing: defaults, checked-in config, local override boundaries

Do not jump straight to file creation. First decide what must always be loaded, what should stay on demand, and what must remain local to one machine.

Step 2: Choose the smallest correct configuration surface

Use these defaults unless the environment proves otherwise:

• always-on repo instructions belong in project instruction files such as

AGENTS.md, CLAUDE.md, or equivalent repo guidance

• reusable task-specific guidance belongs in skills
• external integrations belong in plugins, extensions, or MCP configuration
• safety controls belong in settings, permission rules, and hooks
• personal preferences stay local unless the team explicitly wants them shared

Keep the main project instructions concise. Move detailed procedures and platform-specific examples into references/.

Step 3: Configure guardrails with least privilege

When the request touches approvals, hooks, or permissions:

• default to narrow allowlists over broad wildcard approval
• block destructive commands explicitly
• separate safe automation from risky human-review steps
• document where host-only or secret-bearing settings must stay out of the repo

Avoid recommending blanket auto-approval, unrestricted host execution, or unknown MCP endpoints as defaults.

Step 4: Package reusable capability cleanly

When the request is about extending what the agent can do:

• use skills for reusable instructions and decision procedures
• use plugins, extensions, or MCP when external tools or services are required
• keep overlap explicit so users know when to route to a sibling skill instead
• add references or evals when the configuration surface is likely to be reused

or reviewed

Do not create a new package surface when a smaller edit to existing project guidance would solve the problem.

Step 5: Verify the resulting configuration

Before claiming the configuration is good:

• check that the chosen surface matches the actual need
• confirm the scope is correct: global, project, repo, or user-local
• review for over-broad permissions, duplicated instructions, or secret risk
• run validation or linting where the repo provides it

If the output is a team-shared configuration, leave an explicit note about what is intentionally shared and what must remain local.

Examples

Example 1: Decide where instructions belong

Input:

Should this repo guidance live in AGENTS.md, a skill, or local settings?

Expected shape:

• distinguishes always-on rules from on-demand guidance
• keeps repo-specific policy in project instruction files
• avoids turning every repeated note into a new skill

Example 2: Tighten safety settings

Input:

I want the agent to run tests automatically but never approve dangerous shell
commands. How should I configure that?

Expected shape:

• uses least-privilege approval guidance
• separates safe test automation from risky commands
• recommends explicit deny or warning patterns for destructive actions

Example 3: Choose between skills and integrations

Input:

We need reusable prompts, browser access, and external service connections
across the team. Should this be a skill, plugin, or MCP setup?

Expected shape:

• routes reusable guidance to skills
• routes external integrations to plugins, extensions, or MCP
• keeps the answer scoped to what must be shared vs what stays local

Example 4: Share team defaults safely

Input:

How should we share our agent configuration in the repo without leaking local
machine preferences or secrets?

Expected shape:

• defines repo-shared vs local-only boundaries
• recommends checking in only the stable team defaults
• calls out secrets and user-specific overrides as local

Best practices

1. Start with scope: global, user-local, project, or repo-shared 2. Keep always-on instructions short and move details behind references 3. Prefer narrow approval patterns over broad wildcard trust 4. Use skills for reusable guidance and integrations only when a tool surface is actually required 5. Avoid duplicating the same rule across project files, skills, and settings 6. Add evals before considering an optimization loop for a newly packaged skill

References

• references/instruction-files-and-scope.md
• references/guardrails-and-permissions.md
• references/skills-plugins-and-team-sharing.md
• Agent Skills specification
• Agent Skills best practices
• Claude Code subagents
• Gemini CLI extensions
• OpenAI Codex

Guardrails And Permissions

Treat safety configuration as a least-privilege exercise, not a convenience shortcut.

Default posture

• Allow common read, test, and lint flows narrowly
• Warn or block destructive commands explicitly
• Keep secrets and host-level privileges outside repo-shared defaults
• Review wildcard approvals carefully before recommending them

High-risk patterns

Do not recommend these as normal defaults:

• unrestricted host execution
• blanket sudo approval
• destructive deletion patterns such as rm -rf /
• piped remote execution such as curl ... | sh
• trusting unknown MCP servers by default

Safer approval patterns

• approve bounded read-only commands
• approve test or lint commands with narrow command shapes
• require a human checkpoint for publish, deploy, secret, or destructive flows
• keep secret-bearing config local rather than checked into the repo

Verification checklist

• Does the approval pattern match the exact command family?
• Is the risky path denied or clearly escalated?
• Would a teammate inherit unsafe defaults by pulling the repo?
• Are there any secrets, personal paths, or host-only assumptions in the file?

Instruction Files And Scope

Use the smallest surface that matches how often the guidance must load.

Scope defaults

• Always-on repo rules: AGENTS.md, CLAUDE.md, or the platform's

project-level instruction file

• Reusable task guidance: skill package
• User-local preferences: local settings, aliases, editor choice, local paths
• External capability setup: plugin, extension, MCP, or custom command config

Scope questions

Answer these before writing config:

1. Must this be loaded on every task? 2. Is it repo-specific or user-specific? 3. Does it require a tool or service connection? 4. Would duplicating it across surfaces create drift?

Practical rules

• Put coding standards, repo layout, and safety warnings in the project

instruction file.

• Put step-by-step reusable procedures in skills.
• Keep personal shell aliases, editor preferences, and machine-specific paths

out of team-shared repo files unless the team explicitly standardizes them.

• If the same detail makes the project instruction file too long, move the

detail into references/ and keep only the routing sentence in SKILL.md.

Cross-platform mapping

Normalize configuration choices into:

• settings: model choice, permissions, local defaults, tool access
• rules: always-on repo instructions, safety policy, routing boundaries
• hooks: pre/post action automation, notifications, policy checks

This mapping keeps the skill portable across Claude, Codex, Gemini, and other agent clients even when exact filenames differ.

Skills Plugins And Team Sharing

Use the packaging surface that matches the job.

Surface selection

• Skill: reusable guidance, routing logic, decision procedures
• Plugin or extension: packaged capabilities, commands, or agent definitions
• MCP: live connection to an external tool or service
• Project instruction file: repo-wide rules that should always be active

When not to create a new surface

• Do not create a new skill when one repo-specific rule in AGENTS.md is

enough.

• Do not add an MCP server when the task is purely local and the shell already

solves it.

• Do not check in personal-only setup that the team cannot use safely.

Team-sharing boundaries

Safe to share:

• stable repo rules
• documented team defaults
• packaged skills that do not embed secrets
• reproducible plugin or MCP setup instructions

Keep local:

• secrets, tokens, credentials, local paths
• machine-specific editor settings
• private integrations not meant for the team

Why this matters

Recent agent tooling keeps pushing configuration into reusable packaged surfaces: skills, subagents, extensions, and tool-server integrations. That raises the value of explicit routing so a team does not accumulate the same instruction in three places with different scopes.