agent-project git:20260919.4491844A

Immutable. This exact content is served forever at /api/v1/blob/941a4eb6da56c4f8.

---
name: agent-project
description: "Set up a repository's agent layer: AGENTS.md and shared skills layout, coding-agent discovery, and host bridges."
license: MIT
metadata:
  kind: task
  author: Médéric HURIER (Fmind)
  source: github.com/fmind/dot/tree/main/skills/agent-project
  created: "2026-06-23"
  updated: "2026-09-19"
---

# Set Up Agents on a Project

Author the shared project instruction and skill layer once, then add only required host bridges. [repository-docs](../repository-docs/SKILL.md) owns instruction content; [mcp-setup](../mcp-setup/SKILL.md) owns MCP configuration.

## Workflow

1. **Inspect first**: preserve existing AGENTS.md, host files, skills, and user settings; reuse a stack-specific instruction file when one exists.
1. **Create the shared layer**: `AGENTS.md` from the [project template](templates/AGENTS.md), `.agents/skills/`, and an ignored `.agents/prompts/` working inbox for [task-prompts](../task-prompts/SKILL.md).
1. **Bridge installed hosts**: follow [host-setup.md](references/host-setup.md) for Claude links, optional configuration, and native custom-agent locations; do not create unused host files.
1. **Verify discovery**: read [host-discovery.md](references/host-discovery.md) for listing commands and native plugin catalogs; distinguish presence from demonstrated instruction following.
1. **Install vendor skills deliberately**: follow the shared [vendor-skill policy](references/vendor-skills.md) for source review, project scope, versioning, replacement, and the current `skills` versus preview `gh skill` boundary.
1. **Keep current**: route repository changes through [repository-docs](../repository-docs/SKILL.md), including project-local skill references.

## Gotchas

- **One rule body**: shared rules live in `AGENTS.md`; `CLAUDE.md` is only the bridge, never a second copy.
- **Smallest override**: project configuration overrides the user's global defaults; add only what the repository needs.
- **Strict formats**: keep JSON free of comments unless the host documents JSONC, and validate TOML before launching an agent.
- **Untrusted configuration**: review a repository's hooks, MCP servers, skills, plugins, and custom-agent definitions before enabling them.

## Official source audit

Read the [dated official skill source audit](references/official-skills.md) when selecting a vendor package. It records inspected sources and gaps; recheck the selected source before installation.

## Documentation

- [AGENTS.md standard](https://agents.md) · [Agent Skills specification](https://agentskills.io/specification)
- Companion skills: [mcp-setup](../mcp-setup/SKILL.md) (MCP servers), [repository-docs](../repository-docs/SKILL.md) (instruction conventions and freshness), [task-prompts](../task-prompts/SKILL.md) (`.agents/prompts/`).