agent setup maintenance
- Repo stars 27,778
- Author repo langfuse
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @langfuse · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Docker
- Runtime requirements
- Docker
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Agent Setup Maintenance
Use this skill when changing the shared agent setup for the repository.
## Start Here
- Read [`../../README.md`](../../README.md) for the shared config and shim model.
- Read root [`../../AGENTS.md`](../../AGENTS.md) for repo-level expectations.
- When adding or editing shared skills, use
[`../skill-creator/SKILL.md`](../skill-creator/SKILL.md), then apply the
repo-specific checks in this skill.
- Inspect [`../../../scripts/agents/sync-agent-shims.mjs`](../../../scripts/agents/sync-agent-shims.mjs)
before changing generated outputs or provider discovery behavior.
- Inspect [`../../../scripts/postinstall.sh`](../../../scripts/postinstall.sh)
and [`../../../package.json`](../../../package.json) when changing install-time
sync behavior.
## Workflow
1. Edit the canonical files under `.agents/`, not generated provider outputs.
2. Keep root `AGENTS.md` and `CLAUDE.md` as discovery symlinks; do not turn
them back into manually maintained copies.
3. Treat tool-specific directories such as `.claude/`, `.cursor/`, `.codex/`,
`.vscode/`, and `.mcp.json` as generated discovery surfaces unless the tool
requires a truly tool-specific feature.
4. Keep root `AGENTS.md` concise and router-like. Move detailed or conditional
workflows into shared skills or package `AGENTS.md` files.
5. Treat developer feedback as a learning loop: when a task reveals a durable
repo convention, recurring pitfall, reusable workflow, or verification
pattern, update the smallest relevant `AGENTS.md` or shared skill.
6. When adding or changing a shared skill, update `skills/README.md` and link
it from root `AGENTS.md` if it changes the default reusable workflow.
7. When shared setup behavior changes materially, update `README.md` and
contributor-facing docs in the same PR.
## Docker / Install-Time Constraint
- `pnpm install` runs in environments that may not contain the full repo source
tree.
- In Docker builds, Turbo's pruned install stage can run root `postinstall`
before `scripts/` and `.agents/` are available in the image.
- Keep install-time agent setup logic robust in those pruned contexts: skip
cleanly when the required repo-owned files are not present.
## Required Verification
Run after changing shared agent setup:
- `pnpm run agents:sync`
- `pnpm run agents:check`
Run additional verification when relevant:
- `pnpm run postinstall` when install-time behavior changes
- targeted tests for any scripts you changed
## Design Rules
- Prefer one repo-owned source of truth over duplicated provider-specific files.
- Keep shared setup tool-neutral where possible.
- Only keep provider-specific files in source control when the provider requires
a fixed discovery path or feature that cannot be expressed through the shared
setup model.
Sections and files
Listed in source order.
sections -> Start Here → Workflow → Docker / Install-Time Constraint → Required Verification → Design Rules
terms -> Use this skill when changing the shared agent setup for the repository. · - Read [../../README.md](../../README.md) for the shared config and shim model. · 1. Edit the canonical files under .agents/, not generated provider outputs. · - pnpm install runs in environments that may not contain the full repo source tree. · - Prefer one repo-owned source of truth over duplicated provider-specific files.
files/cmd -> ../../README.md · ../../AGENTS.md · ../skill-creator/SKILL.md · ../../../scripts/agents/sync-agent-shims.mjs · ../../../scripts/postinstall.sh · ../../../package.json · .agents/ · AGENTS.md
body sha256 -> 42dfba56043c
Start Here
Read
../../README.mdfor the shared config and shim model. Read root../../AGENTS.mdfor repo-level expectations. When adding or editing shared skills, use../skill-creator/SKILL.md, then apply the repo-specific checks in this skill.Workflow
Edit the canonical files under
.agents/, not generated provider outputs. Keep rootAGENTS.mdandCLAUDE.mdas discovery symlinks; do not turn them back into manually maintained copies. Treat tool-specific directories such as.claude/,.cursor/,.codex/,.vscode/, and.mcp.jsonas generated discovery surfaces unless the toolDocker / Install-Time Constraint
pnpm installruns in environments that may not contain the full repo source tree. In Docker builds, Turbo's pruned install stage can run rootpostinstallbeforescripts/and.agents/are available in the image. Keep install-time agent setup logic robust in those pruned contexts: skipRequired Verification
Run after changing shared agent setup:
pnpm run agents:syncpnpm run agents:checkRun additional verification when relevant:pnpm run postinstallwhen install-time behavior changesDesign Rules
Prefer one repo-owned source of truth over duplicated provider-specific files. Keep shared setup tool-neutral where possible. Only keep provider-specific files in source control when the provider requires a fixed discovery path or feature that cannot be expressed through the shared setup model.