agent-sync-action: Skill for Claude Code

Update Agents Content

Upsert .agents source-of-truth files for agents, skills, or rules based on user input.

Behavior

1. Validate input.

   • If input is missing or empty, ask: "What should I add or update in .agents?"

2. Identify target type and name.

   • Supported types: agent, skill, rule.
   • If the user explicitly says the type, use it.
   • If type is not explicit, infer it only when confidence is high.
   • If not confident, ask: "Should this be an agent, skill, or rule?"

3. Include the underlying issue.

   • When the user raises a concrete issue or provides evidence such as screenshots while requesting agent guidance, update the guidance and implement the underlying product or code fix in the same task.
   • Treat the issue and evidence as requested scope, not merely as background for the .agents update.
   • Skip the underlying fix only when the user explicitly requests an instruction-only change.

4. Resolve the agent-content target path inside .agents only.

   • agent -> .agents/agents/<name>.md
   • rule -> .agents/rules/<name>.md
   • skill -> .agents/skills/<name>/SKILL.md
   • Never read or write .cursor/*, .claude/*, .codex/*, or any other non-.agents agent or provider folder.
   • Do not manually create, update, or sync mirrored command/skill/rule files in those folders; repository automation propagates changes from .agents to Cursor, Claude, Codex, and similar targets.
   • This path restriction applies to the agent-content update, not to source changes required to fix an underlying issue from step 3.

5. Upsert behavior.

   • If target file exists, read it completely before updating it in place with the requested changes.
   • If target file does not exist, create it with a concise structure matching existing style.
   • Place new guidance under the broadest existing subject section that fits. Use durable topic headings rather than creating a heading for one requirement.
   • Express each independent requirement once, usually as one concise bullet. Merge overlapping or synonymous guidance without losing distinct criteria or exceptions.
   • Normalize the touched file's nearby structure when needed: combine narrow sections, remove redundant wording, and order foundational guidance before specialized concerns.
   • When adding a new restriction or rule, keep the wording concise—one clear statement or bullet per idea; do not pad with redundant sentences or multiple bullets that restate the same requirement.
   • Stable guidance: Do not embed concrete repository file paths or copy code examples from the current codebase into .agents files; those go stale when files move or refactors land. Prefer generic placeholders (for example services/<name>/...), short pattern descriptions, or minimal invented examples that are not tied to live paths or current line-level code.
   • Retain examples only when they clarify a non-obvious distinction; remove examples that merely repeat the prose.
   • Keep topic-specific restrictions with their topic. Keep an existing ## Guardrails section at the bottom, and create one only for cross-cutting safety or preservation constraints.