feat(agents): generalize repository guidance for coding agents

[Danigm-dev]

Summary

Generalizes the repository's internal coding-agent guidance so it can be reused beyond a single client.

This PR adds:

• a root AGENTS.md with repo-wide engineering guidance
• scoped AGENTS.md files under apps/sim/ for app-specific conventions
• reusable .agents/skills/* instructions for common Sim integration workflows

The goal is to make the repository guidance portable across coding agents such as Claude Code, Codex, and OpenCode without changing runtime product behavior.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Other: ___________

Testing

No runtime tests were added for this PR because it only introduces repository guidance and agent workflow instructions.

Reviewer focus:

• whether the scope is appropriate for the repository
• whether the guidance is clear and maintainable
• whether the scoped AGENTS.md files are placed in the right directories
• whether the .agents/skills/* instructions are sufficiently generic and useful

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Screenshots/Videos

N/A

[vercel]

@Danigm-dev is attempting to deploy a commit to the Sim Team on Vercel.

A member of the Team first needs to authorize it.

[cursor]

PR Summary

Low Risk
Documentation/agent-workflow additions only; no runtime code paths or product behavior are changed.

Overview
Adds a repo-wide AGENTS.md plus scoped AGENTS.md files under apps/sim/ (and subareas like blocks, tools, triggers, hooks, stores, components/emcn) to standardize engineering conventions for coding agents.

Introduces reusable agent “skills” under .agents/skills/ (e.g., add-block, add-tools, add-integration, add-trigger, add-connector, and validation skills) with detailed step-by-step guidance and OpenAI agent metadata, aimed at making Sim integration work (tools/blocks/triggers/connectors) consistent and portable across agent runtimes.

^{Written by Cursor Bugbot for commit bf5f4b4. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[greptile-apps]

Greptile Summary

This PR introduces a portable, hierarchical coding-agent guidance system for the Sim repository. It adds a root AGENTS.md with repo-wide engineering standards, scoped AGENTS.md files under apps/sim/ and its key sub-directories, and seven reusable skill instruction files under .agents/skills/ covering the full integration development lifecycle.

Key changes:

• Root AGENTS.md: Consolidates global standards (logging, imports, TypeScript, components, Zustand stores, React Query, testing, integration workflow) into a single authoritative document portable across Claude Code, Codex, and OpenCode agents.
• Scoped AGENTS.md files: 8 directory-scoped files (apps/sim/, blocks/, tools/, hooks/, hooks/queries/, stores/, components/emcn/, triggers/) layer precise sub-system rules on top of the root guidance.
• .agents/skills/ instruction files: 7 detailed skills (add-integration, add-block, add-tools, add-connector, add-trigger, validate-integration, validate-connector) provide step-by-step agent workflows with checklists. Each is accompanied by an OpenAI YAML metadata file.
• One broken link: apps/sim/AGENTS.md line 3 references the root AGENTS.md via a hardcoded local developer path (/home/danielgm/dev/sim/AGENTS.md) which will be broken for all other contributors and agent environments. This should be replaced with the repo-relative path /AGENTS.md.

Confidence Score: 4/5

• Safe to merge after fixing the one broken cross-reference link in apps/sim/AGENTS.md — no runtime behavior is changed.
• This is a documentation-only PR with no changes to runtime code. The content is thorough, well-structured, and consistent with existing project conventions. The single actionable issue is a hardcoded local developer path in apps/sim/AGENTS.md that will produce a broken link for all contributors and agent environments. Once fixed with a one-line change, the PR is ready to merge.
• apps/sim/AGENTS.md — contains a broken cross-reference link to the root AGENTS.md using a hardcoded local developer path.

Important Files Changed

Filename	Overview
apps/sim/AGENTS.md	App-scoped guidance for coding agents. Contains a broken cross-reference link using a hardcoded local developer path (/home/danielgm/dev/sim/AGENTS.md) that needs to be fixed to a repo-relative path.
AGENTS.md	Root-level coding-agent guidance covering architecture, imports, TypeScript conventions, components, hooks, Zustand stores, React Query, testing, and the integration checklist. Well-structured and consistent with existing .cursor/rules/ conventions.
.agents/skills/add-integration/SKILL.md	Comprehensive end-to-end skill for adding a new service integration (tools → block → icon → triggers → registry → docs). Correctly documents visibility: 'hidden' for OAuth tokens and visibility: 'user-only' for API keys, consistent with repo rules.
.agents/skills/add-block/SKILL.md	Detailed skill for creating or updating block configurations with SubBlock types, condition syntax, dependsOn patterns, canonicalParamId usage, mode options, output definitions, and a final validation checklist.
.agents/skills/validate-integration/SKILL.md	Thorough audit skill covering tool IDs, params, request mapping, response transforms, outputs, block ↔ tool alignment, advanced mode, wandConfig, OAuth scopes, pagination, and error handling. Issues are grouped by severity.
.agents/skills/add-connector/SKILL.md	Skill for adding knowledge-base connectors (OAuth and API-key modes), covering directory structure, auth config, configFields, selector canonical pairs, ExternalDocument shape, content hashing, tagDefinitions, mapTags, fetchWithRetry usage, and registry registration.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    ROOT["AGENTS.md\n(repo root)\nGlobal standards, architecture,\nimports, testing, integration guide"]

    SIMAPP["apps/sim/AGENTS.md\nApp-scoped conventions"]
    BLOCKS["apps/sim/blocks/AGENTS.md\nBlock definition rules"]
    TOOLS["apps/sim/tools/AGENTS.md\nTool definition rules"]
    HOOKS["apps/sim/hooks/AGENTS.md\nHook patterns"]
    QUERIES["apps/sim/hooks/queries/AGENTS.md\nReact Query patterns"]
    STORES["apps/sim/stores/AGENTS.md\nZustand store patterns"]
    EMCN["apps/sim/components/emcn/AGENTS.md\nEMCN component library rules"]
    TRIGGERS["apps/sim/triggers/AGENTS.md\nTrigger definition rules"]

    SKILLS[".agents/skills/"]
    ADD_INT[" add-integration\nFull integration workflow"]
    ADD_BLOCK["add-block\nBlock config skill"]
    ADD_TOOLS["add-tools\nTool config skill"]
    ADD_CONN["add-connector\nKB connector skill"]
    ADD_TRIG["add-trigger\nTrigger skill"]
    VAL_INT["validate-integration\nIntegration audit skill"]
    VAL_CONN["validate-connector\nConnector audit skill"]

    ROOT --> SIMAPP
    SIMAPP --> BLOCKS
    SIMAPP --> TOOLS
    SIMAPP --> HOOKS
    HOOKS --> QUERIES
    SIMAPP --> STORES
    SIMAPP --> EMCN
    SIMAPP --> TRIGGERS

    SKILLS --> ADD_INT
    SKILLS --> ADD_BLOCK
    SKILLS --> ADD_TOOLS
    SKILLS --> ADD_CONN
    SKILLS --> ADD_TRIG
    SKILLS --> VAL_INT
    SKILLS --> VAL_CONN

    ADD_INT --> ADD_BLOCK
    ADD_INT --> ADD_TOOLS
    ADD_INT --> ADD_TRIG

    style ROOT fill:#7C3AED,color:#fff
    style SIMAPP fill:#2563EB,color:#fff
    style SKILLS fill:#0F766E,color:#fff

Loading

_{Reviews (1): Last reviewed commit: "feat(agents): generalize repository guid..." | Re-trigger Greptile}