Troubleshoot Skills Registry

Your agent must be configured to connect through Agent Guard.

To verify connectivity:

1. Ask your agent: "Can you confirm you have access to JFrog?"
2. Your agent should confirm the JFrog service endpoint URL and your project name.

Suggested solution: If the agent cannot verify connectivity:

• Check that Agent Guard is configured.
• Verify your JFrog credentials are valid and not expired.
• Confirm you have project membership and repository access.
• Restart your IDE.
• Contact your platform administrator if credentials or permissions are the issue.

Agent Guard must resolve your active project.

To resolve the project context:

1. Confirm you're working within a project context. Check your IDE's project selector.
2. Ask your agent: "What project are you currently working in?"
3. If no project detected:
   • Ensure you're inside a project workspace.
   • Check the IDE's project context.
   • Restart the IDE.

Suggested solution: If the issue persists, contact your platform administrator.

On first publish, the AI Catalog auto-provisions a skills repository. If this failed:

To fix:

Try to republish the skill as follows:

1. Ask your agent to try publish again.
2. Watch for error messages. Common causes:
   • No write permission on the project
   • Auto-provisioning failed in JFrog
3. Contact your platform administrator to:
   • Confirm you have write access.
   • Verify the repository was auto-provisioned.
   • Manually provision if needed.

For more information, see Skills Repositories.

When you ask your agent to discover, it queries the Skills Registry for your active project.

To find published skills:

1. Confirm you're in the correct project context.
2. Ask your agent: "Are any skills published to this project?"
3. If no skills appear but you know they exist:
   • Wait 10 to 15 seconds and ask again.
   • Check AI/ML > Discovery > Skills in the Platform UI.
   • If skills exist in the UI but the agent doesn't see them, it may be a sync delay.

Suggested solution: If this persists, the skills may be in a different project. Check your project selector and ask your agent what project it published to.

Auto-registration is usually instant but can take a few seconds.

To make the skill appear in Discovery:

1. Wait 15 to 30 seconds after publish.
2. Ask your agent to refresh: "Show me available skills again."
3. Or refresh the Platform UI.
4. Your skill should appear with status Not scanned, moving to Not malicious once Xray finishes.

Suggested solution: If still missing after 30 seconds:

• Check the publish output for errors.
• Confirm SKILL.md metadata is valid.
• Ask your agent to try publish again.

Match the agent error message to one of the following suggested solutions.

Suggested solution:

If your agent says 'SKILL.md not found':

• Confirm the folder contains SKILL.md.
• Check the folder path.
• Ask your agent to verify the file exists.
• CLI: confirm with ls -la ./my-skill/SKILL.md.

If your agent says 'invalid metadata':

• Check required fields: slug (must match ^[a-z0-9][a-z0-9-]*$), version (semantic, for example, 1.0.0 not v1), description.
• Verify YAML syntax.
• Ask your agent to review: "Can you check my SKILL.md for errors?"
• CLI: check syntax directly.

If your agent says 'permission denied':

• You don't have write access to the repository.
• Contact your administrator.
• CLI: confirm credentials are current first: jf config show.

If your agent says 'connection failed':

• Check network and firewall.
• Verify Agent Guard is configured.
• Check JFrog credentials (may be expired).
• CLI path: confirm the Artifactory URL in jf config show is correct and Artifactory is reachable.

To retry publish:

Ask your agent for the full error message. Retry with your agent, or run:

jf agent skills publish ./my-skill

Publishing with the same name twice creates a new version. This is expected.

Each publication:

• Creates a new version from the version field
• Keeps all previous versions available
• Available in Discovery

You can install specific versions. For example, ask: "Install version 1.0.0 of my-skill."

Suggested solutions:

• To prevent duplicates, ensure unique version fields.
• Contact your administrator to verify the signature and confirm the publisher's public key is configured, then retry. An unsigned-skill warning during install is informational only. It doesn't block install if the skill's status permits it.
• If CLI is not configured: Add your server URL and credentials, then retry. For more information, see JFrog CLI Setup.

To troubleshoot when the agent cannot find a skill to install:

1. Verify the skill exists. Ask: "Is the my-skill skill available?" or "List all available skills."
2. With the CLI, copy the exact name from the Discovery View. Names are case-sensitive.
3. If the skill exists but can't install:
   • Status may be Suspicious or Malicious.
   • Ask your agent to show details.
   • Or it may still be scanning.

Suggested solution: Confirm you're in the correct project.

To review why installation is blocked:

1. Ask your agent: "Show me the details for my-skill and explain why it can't be installed" to see the Xray results.

If you believe it's incorrect, contact your administrator with skill name, version, current status, and reason needed.

Issue: Skill status blocks installation

Suggested solution: The skill is Suspicious or Malicious. Ask your agent for details, or wait if it is still scanning.

Issue: Skill version not found

Suggested solution:

• Version doesn't exist.
• Ask your agent: "What versions of my-skill are available?"
• Install latest without version.
• CLI: jf agent skills install my-skill (no version) or verify the version in the Discovery View.

Issue: Installation directory issue

Suggested solution:

• Your agent can't write to the directory.
• Check file system permissions.
• Restart your IDE.

To get more detail: Ask your agent for the full error message.

Once installed, your agent should recognize the skill automatically.

What to do when the agent does not invoke an installed skill automatically?

1. Confirm installation: Ask "Is the my-skill skill installed?"
2. Confirm it's relevant to your current task.
3. Ask explicitly: "Use the my-skill skill to accomplish this task."
4. If still fails:
   • Check the skill's SKILL.md for proper interfaces.
   • Ask your agent: "Can you show me what the skill does?"

Issue: Skill is corrupt

Suggested solution: Ask your agent to reinstall: "Uninstall and then reinstall the my-skill skill."

To fix:

1. Copy the exact skill name from the Discovery View. Names are case-sensitive.

2. Run the following command:

   Shell

   jf agent skills install <SKILL_NAME>

   Where:

   • <SKILL_NAME>: Exact skill name as shown in Discovery

   For example:

   Shell

   jf agent skills install my-skill

For more information, see Skills Repositories.

You specified a version that doesn't exist.

To fix:

1. Omit the version:

   Shell

   jf agent skills install my-skill

2. Or verify that the version exists in the Discovery View.

To fix:

1. Contact your administrator to verify the signature.
2. Check that the publisher's public key is configured.
3. Try again.

For more information, see Skills Repositories.

Whether it blocks install depends on whether the repository has Xray applied.

On a repository with no Xray applied, a skill can stay Not scanned indefinitely and remains installable throughout. That's expected.

On an auto-provisioned project repository (Xray applied by default), scanning usually finishes within minutes, and install is blocked until it does.

Issue: Not scanned persists much longer than expected on an Xray-applied repository

Suggested solution: Contact your administrator. It likely means Xray indexing isn't actually enabled on that repository.

Suspicious means Xray detected patterns that warrant review.

Issue: Because the skill is marked as Suspicious, your agent can't install it.

Suggested solution:

• Contact your administrator for details.
• They can review and decide to unblock or remove.
• Don't attempt workarounds. It's a safety measure.

Blocked means an administrator blocked it for security reasons.

Issue: Because the skill is marked as Blocked, your agent can't install it.

Suggested solution:

• Contact your administrator to understand why.
• They can unblock if appropriate.

A block in a shared repository affects all projects sharing it.

Malicious means Xray confirmed malicious code.

Issue: Because the skill is marked as Malicious, your agent can't install it.

Suggested solution:

• Don't attempt to use it.
• Contact your administrator for next steps.

What to do if you see stale versions, incorrect status, or mismatched info:

1. Refresh: Ctrl+R (Windows/Linux) or Cmd+R (Mac).
2. Clear cache: Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac), then refresh.
3. Wait for sync: Usually instant, sometimes up to a minute. Wait 30 to 60 seconds and refresh.

After refresh, information should match Artifactory.

Issue: The drawer doesn't open or is blank.

Suggested solution:

1. Close and click the card again.
2. Refresh the page (Ctrl+R / Cmd+R).
3. Clear browser cache and refresh.

Issue: Drawer is still blank after refresh.

Suggested solution: The skill's files may be corrupted. Contact your administrator to verify skill integrity and possibly republish.

Issue: Agent reports an error when inspecting a skill.

Suggested solution:

1. Confirm the skill exists in Discovery (may be deleted).
2. Ask your agent to list skills and confirm it's there.
3. Try again (may be temporary).
4. Ask your agent: "Can you show me details and any error messages?"

Issue: SKILL.md is corrupted.

Suggested solution: Contact your administrator. Details won't load until the skill is repaired or republished.