Troubleshooting issues

This guide helps you resolve common issues encountered while using the Agentic Developer Toolkit with assistants such as Cursor and Claude Code.

You have successfully installed a skill (via npx or git clone), and the commands are visible in the chat interface. However, the development rules are not enforced:

• Platform 3.0 standards are not applied.
• The assistant allows you to write Platform 2.x code without warnings or corrections.

The installed skill contains an incomplete or outdated plugin.json file. Specifically, it is missing the rulesDirectory declaration, which tells Cursor where the architectural rules are located. This often occurs if the skill was built for older versions of Cursor or if you are using an outdated branch of the repository.

To fix this issue, you must manually update the plugin.json file in your local skill directory.

1. Verify the configuration

   Open your terminal and run the following command to check the contents of the plugin.json file for the affected skill (this example uses fw-app-dev):

   cat ~/.cursor/skills/fw-app-dev/.cursor-plugin/plugin.json

   If the following lines are missing, proceed to step 2:

   "rulesDirectory": "./rules",
   "commandsDirectory": "./commands"

2. Update the file

   1. Run the following command to navigate to the skill directory and back up the original file before applying the fix:

        cd ~/.cursor/skills/fw-app-dev/

        cp .cursor-plugin/plugin.json .cursor-plugin/plugin.json.backup

   2. Run the following command to inject the missing fields into the configuration:

      1cat .cursor-plugin/plugin.json | \
      2python3 -c "import sys,json; d=json.load(sys.stdin); d['rulesDirectory']='./rules'; d['commandsDirectory']='./commands'; print(json.dumps(d,indent=2))" \
      3> .cursor-plugin/plugin.json.new && \
      4mv .cursor-plugin/plugin.json.new .cursor-plugin/plugin.json

3. Restart Cursor to reload the updated plugin configuration.

To confirm the rules are now active:

1. Open a JavaScript (.js) file in your workspace.
2. Attempt to write legacy code, such as $request.post('url', {})
3. If the fix was successful, Cursor should immediately issue a warning or suggest a Platform 3.0 alternative. If you still do not see warnings after a restart, see Issue #2: Resolving Duplicate Rules.

Cursor fails to apply updates to rules or displays unpredictable behavior when executing commands. This typically happens when your skill directory contains redundant folders, such as:

• skills/fw-app-dev/rules/*.mdc
• skills/fw-app-dev/.cursor/rules/*.mdc

In this scenario, Cursor may load an outdated version of a rule or fail to recognize new commands entirely.

This issue is caused by a legacy file structure from Cursor versions older than v0.40.

Old Pattern: Rules and commands were nested inside a .cursor/ subdirectory.

New Pattern: Cursor v0.40+ and other IDEs now require a multi-IDE compatible structure where rules/ and commands/ reside at the root of the skill directory, with a .cursor-plugin/plugin.json file directing the assistant.

When both structures exist, Cursor may ignore the correct files or encounter conflicts.

To resolve this, run the following commands to remove the legacy .cursor/ subdirectories and ensure your rules reside in the root-level folders:

1. Navigate the affected skill folder:

   cd ~/.cursor/skills/fw-app-dev/

2. Delete the outdated .cursor/ subdirectories

   Note:Do not delete the .cursor-plugin/ folder, as it contains your configuration.

   rm -rf .cursor/commands
   rm -rf .cursor/rules

3. Ensure the rules and commands are present at the root of the skill directory:

   ls -la rules/
   ls -la commands/

Run the following commands in your terminal to ensure the cleanup was successful:

1. Confirm legacy files are gone:

   ls .cursor/rules 2>&1 | grep "No such file"
   ls .cursor/commands 2>&1 | grep "No such file"

2. Confirm active files exist:

   ls rules/*.mdc | wc -l

   It should return a number greater than 0.

   ls .cursor-plugin/plugin.json

   It should return the file path.

Tip:After performing these steps, restart Cursor to ensure the assistant re-indexes the correct file paths.

When you attempt to use a skill, the commands do not appear or autocomplete in the chat interface. Specifically:

• Typing / displays standard assistant commands, but Freshworks-specific commands (like /fdk-fix) are missing.
• Manual entry of a command results in no action or a "command not recognized" error.

This issue typically indicates that the skill was not installed correctly, the file structure is corrupted, or the AI assistant's command index has not been refreshed.

Follow these steps to verify the installation and restore command functionality.

1. Verify the installation

   Check if the skill files exist on your local machine. Run the command corresponding to your AI assistant:

   For Cursor:

   ls ~/.cursor/skills/fw-app-dev/SKILL.md
   ls ~/.cursor/skills/fw-app-dev/commands/

   For Claude Code:

   ls ~/.claude/skills/fw-app-dev/SKILL.md
   ls ~/.claude/skills/fw-app-dev/commands/

   If the files do not exist: The skill is not installed. Return to the installation instructions.

   If the files exist but do not work: Proceed to step 2.

2. Refresh the assistant

   Most command discovery issues are resolved by a full application restart. Close all windows of your AI assistant or IDE and reopen them. This forces the assistant to re-index the skills directory.

3. Inspect command files

   Ensure the individual command definitions are present and in the correct format. Run the following to list the command files:

   For Cursor:

   ls ~/.cursor/skills/fw-app-dev/commands/*.md

   For Claude Code:

   ls ~/.claude/skills/fw-app-dev/commands/*.md

   You should see a list of Markdown files such as fdk-fix.md, fdk-migrate.md, and fdk-review.md.

   • If no .md files are visible: The skill package is corrupted.
   • If files are present but invisible to the assistant: The SKILL.md file may be malformed.

4. Reinstall the skill

   If the steps above do not resolve the issue, remove the existing skill directory and perform a clean installation.

   To remove the skill:

   • For Cursor: rm -rf ~/.cursor/skills/fw-app-dev

   • For Claude Code: rm -rf ~/.claude/skills/fw-app-dev

   After removal, follow the standard installation steps for your assistant.

In your AI assistant's chat interface, ask the following:

"What skills do you have? List all available commands."

If the assistant lists /fdk-fix, /fdk-migrate, and other relevant commands, the installation is successful.

Note:If the commands are still missing after a clean reinstallation, please report the issue and include the output of your ls commands.

• The skill is installed and the rules/ folder contains the correct .mdc files, yet the assistant fails to enforce them.
• You do not receive warnings when writing legacy Platform 2.x code.
• The assistant does not offer "agentic" suggestions based on the Platform 3.0 standards.
• The rules appear to be completely inactive despite being present on your machine.

If the rules exist but are ignored, the cause is usually a configuration error in the plugin manifest or a malformed rule file that the assistant cannot parse. This typically happens if:

• The plugin.json file is missing the pointer to the rules directory (see Issue #1: Cursor rules fail to load after installation).
• The skill package has internal file permission issues or syntax errors within the .mdc files.

Follow these steps to diagnose and resolve the rule enforcement failure.

1. Verify rule existence

   Run the following command to confirm that the rule files are present in the expected directory:

   ls ~/.cursor/skills/fw-app-dev/rules/*.mdc

   If you see multiple .mdc files, proceed to the next step.

   If the directory is empty, your installation is incomplete. You need to reinstall the skill.

2. Cross-reference with Issue #1

   The most common cause for this behavior is a missing rulesDirectory declaration in the configuration. Review Issue #1: Cursor rules fail to load after installation to ensure your plugin.json is correctly configured to point to the **./rules **folder.

3. Perform a clean reinstallation

   If the configuration is correct but the rules still do not trigger, the local skill package may be corrupted. Run the following commands to perform a clean reinstallation from the latest source:

   rm -rf ~/.cursor/skills/fw-app-dev

   npx skills add https://github.com/freshworks-developers/fw-dev-tools --skill fw-app-dev

Open a JavaScript file and type a known legacy pattern:

// This should trigger a Platform 3.0 enforcement warning
$request.get(url);

If the assistant fails to highlight this or suggest an alternative, the issue may be a bug within the skill's rule logic itself.

If the rules still do not apply after a clean reinstallation, please collect diagnostic information and report the bug.

Run these commands to get diagnostic info:

cd ~/.cursor/skills/fw-app-dev/

cat .cursor-plugin/plugin.json | grep rules

ls -la rules/*.mdc

Note:When reporting, include the version of Cursor you are using, as rule processing logic can vary between different versions of the IDE.

You have successfully downloaded the toolkit, but the AI assistant behaves as if no skills are installed. Upon inspecting your file system, you find the skills nested in extra subdirectories, such as:

• Incorrect: ~/.cursor/skills/freshworks-repo/skills/fw-app-dev/
• Correct: ~/.cursor/skills/fw-app-dev/

This issue occurs when a git clone or an npx command creates an extra "wrapper" folder. The Cursor skill loader is not recursive; it only indexes skills located exactly one level below the root skills/ directory. If your skills are buried inside a marketplace/ or repo/ folder, they will be ignored.

To resolve this, flatten the directory structure so that the individual skill folders reside directly within the parent skills/ directory.

1. Run the following command in your terminal to navigate to the skills root folder:

   cd ~/.cursor/skills/

2. Identify the "wrapper" folder (for example marketplace or fw-dev-tools) and move its contents to the current directory. Replace wrapper-folder with the actual name of the extra directory:

   mv wrapper-folder/skills/* .

3. Remove the now-empty wrapper folder:

   rm -rf wrapper-folder

Confirm that the critical files are now in the correct location. The SKILL.md file must be exactly two levels deep from your home directory's .cursor folder:

ls -la ~/.cursor/skills/fw-app-dev/SKILL.md

ls -la ~/.cursor/skills/fw-setup/SKILL.md

These paths should return valid files.

• Full repository cloning: Cloning the entire Freshworks repository instead of adding specific skills.
• Path syntax errors: Using an incorrect path or URL during the npx skills add process.
• Manual copying: Accidentally including parent directories when dragging and dropping folders into the skills directory.

Note:After moving the folders, restart your AI assistant to trigger a fresh scan of the updated directory structure.

When attempting to run a setup script or background task, the terminal returns an error:

zsh: operation not permitted
zsh: permission denied: ./scripts/fw-setup-run-background.sh

In some cases, macOS may display a pop-up dialog stating that the script cannot be opened because it is from an unidentified developer.

This issue is caused by macOS Gatekeeper, a security feature that blocks the execution of unsigned scripts or binaries downloaded from the internet. On macOS 13 (Ventura) and later, Gatekeeper automatically applies a "quarantine" attribute to files downloaded via git, npx, or a web browser, preventing them from running in the shell.

To resolve this, manually remove the quarantine attribute and ensure the scripts have executable permissions.

1. Remove the quarantine attribute

   Run the following command to navigate to the affected skill directory and use the xattr command to clear the security flag:

   cd ~/.cursor/skills/fw-setup/

   xattr -r -d com.apple.quarantine scripts/

   xattr -r -d com.apple.quarantine .

2. Set executable permissions

   Run the following command to ensure that the shell scripts have the necessary permissions to run:

   chmod +x scripts/*.sh

3. Adjust System Settings (Optional)

   If you continue to receive security prompts:

   • Open System Settings and navigate to Privacy & Security.
   • Scroll down to the Security section.
   • Under Allow apps downloaded from, ensure App Store and identified developers is selected.
   • If a block was recently triggered, click Allow Anyway next to the script name.

Run the following commands to confirm that the quarantine attribute has been removed by listing the file attributes:

cd ~/.cursor/skills/fw-setup/

xattr -l scripts/fw-setup-run-background.sh

Expected result: The command should return no output. If you still see com.apple.quarantine in the results, the attribute was not successfully removed.

Note:You may need to prefix the xattr and chmod commands with sudo if your user account does not have administrative ownership of the .cursor directory.

• You notice that some development rules are enforced correctly, while others appear to be ignored.
• Certain legacy code patterns trigger immediate warnings (for example, Platform 3.0 standards).
• Other patterns that should be restricted (for example, high code complexity or deprecated APIs) do not trigger any notifications.
• The assistant seems "partially aware" of the toolkit's requirements.

If the skill is installed and some rules are functioning, the issue is typically not with your environment or installation. Instead, this indicates a bug in the specific .mdc rule files provided by the skill developer. The assistant may be unable to parse specific rules due to syntax errors, incorrect regex patterns, or conflicting logic within the skill package.

This is a skill developer issue. Do not attempt to debug the rule files yourself. Instead, report the problem with the following specifics:

1. Identify working rules: Provide an example of code that correctly triggers a warning.
2. Identify non-working rules: Provide an example of code that should trigger a warning but does not.
3. Submit a report: Post these details at fw-dev-tools Issues.

What to include in your report:

• Success Case: Example of code that correctly triggers a warning.
• Failure Case: Example of code that should trigger a warning but doesn't.
• Environment Data: Your Cursor version (found in About Cursor) and the output of the ls command.

Example of a helpful bug report:

Platform 3.0 rule works:
- Writing $request.post() triggers warning ✅

Complexity rule doesn't work:
- Writing function with 15 if statements, no warning ❌

Environment:
- Cursor version: 0.41.3
- Skill: fw-app-dev
- Rules exist: ls ~/.cursor/skills/fw-app-dev/rules/*.mdc shows 9 files

• Claude Code successfully loads the skill, but it does not consistently adhere to the defined rules or patterns.
• The assistant accepts Platform 2.x code without correction.
• Suggestions do not reflect the architectural standards defined in the toolkit.
• Commands are available, but the "reasoning" behind code generation ignores Platform 3.0 constraints.

Unlike Cursor, Claude Code does not feature automatic, background rule enforcement (via .mdc files). Instead, it relies entirely on the instructions provided in the SKILL.md file. Claude must actively read and prioritize these instructions during the conversation. If Claude misses a rule, it is usually because the context window is crowded or the skill was not correctly indexed at the start of the session.

To resolve this, perform a clean reinstallation of the skills to ensure the assistant is reading the most recent instruction sets.

1. Remove old skills

   Run the following commands to remove old skills:

   rm -rf ~/.cursor/skills/fw-app-dev

   rm -rf ~/.cursor/skills/fw-setup

2. Reinstall the latest version

   Run the following commands to reinstall the latest version:

   cd ~/Downloads

   git clone https://github.com/freshworks-developers/fw-dev-tools.git

   cd fw-dev-tools

   cp -r skills/fw-app-dev ~/.cursor/skills/

   cp -r skills/fw-setup ~/.cursor/skills/

3. Restart Cursor by closing all active windows and instances of the IDE to force a reload of the skill definitions.

Once you have restarted the assistant, perform the following tests to confirm the fix:

• Test commands: Type /fdk in the chat interface and verify that the autocomplete menu displays the expected commands.
• Test rules: Write $request.post() in a JavaScript file. If the fix was successful, the assistant should trigger a warning regarding Platform 3.0 standards.

After running git clone against the freshworks-developers/fw-dev-tools repository, you are unable to locate the specific installation files or the skills do not appear in your AI assistant.

The repository is a monorepo. The individual skills are located within the skills/ subdirectory rather than at the root of the repository. AI assistants expect each skill to be in its own dedicated directory under the local skills folder, not contained within a wrapper repository.

To install correctly from a Git clone, you must move the individual skill folders to the appropriate directory for your assistant.

1. Clone the repository and open it

   Run the following commands to clone the repository and navigate into it:

   git clone https://github.com/freshworks-developers/fw-dev-tools.git

   cd fw-dev-tools/

2. Copy skills for Cursor

   Run the following commands to copy the specific skill folders to the Cursor skills directory:

   cp -r skills/fw-app-dev ~/.cursor/skills/

   cp -r skills/fw-setup ~/.cursor/skills/

3. Copy skills for Claude Code

   Run the following commands to copy the specific skill folders to the Claude Code skills directory:

   cp -r skills/fw-app-dev ~/.claude/skills/

   cp -r skills/fw-setup ~/.claude/skills/

4. Close and reopen your AI assistant to index the new skills.

Do not use the following commands, as they create incorrect nesting or links that the IDE cannot parse:

• cp -r marketplace ~/.cursor/skills/
• ln -s $(pwd) ~/.cursor/skills/fw-dev-tools
• mv marketplace ~/.cursor/skills/