---
name: langfuse-agent-setup-maintenance
description: "Shared workflow for editing Langfuse's repo-owned agent setup under `.agents/`. Use when changing AGENTS files, shared skills, `.agents/config.json`, generated shim behavior, provider discovery paths, or install-time agent sync."
license: "NOASSERTION"
metadata:
  decimalai-skill-id: "5d9179cc-c5b6-45b2-a373-a38de8d6b7c2"
  decimalai-version-id: "0c794d9c-94f9-4ce8-a67b-5bed85a54ae0"
  decimalai-version: "2"
  decimalai-body-sha256: "9cb7f0b251282538a7157b59d49a1dc7c4bc91a56e9475b1af0526b77bfef94f"
  decimalai-name: "langfuse/agent-setup-maintenance"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "agent-tooling"
  decimalai-source: "https://app.decimal.ai/s/langfuse-agent-setup-maintenance@2/SKILL.md"
---
# 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` as a symlink to `.agents/AGENTS.md`. Write folder
   instructions in `AGENTS.md` directly; do not generate `CLAUDE.md` companions.
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. 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, keep `SKILL.md` as the entrypoint; do
   not add skill-by-skill links to root `AGENTS.md`.
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`
- `node --test scripts/agents/sync-agent-shims.test.mjs` when sync behavior changes

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.