Global steering files (~/.kiro/steering/) not loaded into agent context

[bernard357]

Description

Global steering files placed in ~/.kiro/steering/ are not injected into the agent's context, despite the documentation stating they should apply to all workspaces.

Steps to reproduce

1. Create a steering file at ~/.kiro/steering/AGENTS.md with inclusion: always (or no inclusion key, which defaults to always)
2. Open any workspace
3. Start a new chat session
4. Ask the agent to list what steering files are loaded — the global file is absent
5. Verify by asking about a specific directive in the file — the agent is unaware of it

Additional issue: symlinks not followed

As a workaround, I created a symlink from .kiro/steering/AGENTS.md → ~/.kiro/steering/AGENTS.md in the workspace. This was also not loaded. Only a real file copy at .kiro/steering/AGENTS.md works.

Expected behavior

Per the Steering documentation:

Global steering files reside in your home directory under ~/.kiro/steering/, and apply to all workspaces.

Both of the following should work:

• Files in ~/.kiro/steering/ should be loaded into every session
• Symlinks in .kiro/steering/ pointing to valid files should be resolved and loaded

Actual behavior

• Global steering files are ignored entirely
• Symlinked workspace steering files are also ignored
• Only real (non-symlinked) files in .kiro/steering/ are loaded

Workaround

Copy the file directly into the workspace .kiro/steering/ directory (no symlink).

Environment

• macOS (darwin)
• Kiro IDE (latest as of May 2025)

[github-actions]

🤖 Potential Duplicate Detected

This issue appears to be similar to:

• #6401: Kiro IDE does not follow symlinks in ~/.kiro/skills/ — symlinked skills not available to agent (85% similar)
• #6166: Empty steering file causes all context files to fail loading (85% similar)
• #6060: Phantom steering files loaded from stale workspace index (85% similar)
• #5394: skill:// resources don't trigger on-demand loading based on description matching (85% similar)

What happens next?

• ⏰ This issue will be automatically closed in 3 days
• 🏷️ If this is not a duplicate, you can prevent automatic closure by adding a comment or reacting with 👎 to this message.
• 💬 Comment on the original issue if you have additional information

Why is this marked as duplicate?
Both report Kiro IDE not following symlinks in configuration directories - one for skills (/.kiro/skills/) and one for steering files (/.kiro/steering/). Same underlying symlink resolution issue affecting different Kiro features.

[github-actions]

This issue has been automatically closed as it appears to be a duplicate of #6401.

If you believe this is incorrect, please comment on this issue and a maintainer will review it.

[jwhittaker]

I'm getting this bug in the IDE, but I can't tell if it's because of symlinks bug: #6401

If I prompt the IDE that all of those things are there, it finds them. It suggested I write a "trigger": "SessionStart" hook to work around this. I've now built a few custom workflow mechanisms for Kiro over the weeks. But adding a hook here (to try and force what should be a default feature) is worth mentioning.

Why am I symlinking these things? Because then I can manage my own git repo for the various kiro artifacts and distribute them selectively across multiple workstations and projects. I can version my skills and copy them other places with a script instead of the bare 1970's Disk Operating System paradigm currently in place.

You know in Linux, where you have the /usr/bin dir with multiple symlink jumps:

lrwxrwxrwx 1 root root     7 2026-06-15 05:36 python -> python3
lrwxrwxrwx 1 root root    10 2026-06-15 05:36 python3 -> python3.14
-rwxr-xr-x 1 root root 14424 2026-06-15 05:36 python3.14

That's why the Kiro symlink issue is a pretty hot item.

This hook fires at the start of every session and injects those rules directly into context — no relying on the steering file inclusion mechanism to work correctly.

The honest answer to your question: The IDE's steering inclusion: always should handle this automatically. If it's not working (and based on this session, it clearly isn't reliably), the SessionStart hook is the workaround — it uses a mechanism (hooks) that demonstrably fires. It's a band-aid over what should be a platform feature, but it'll work.

The deeper issue is that the Kiro IDE's steering injection seems unreliable for global ~/.kiro/steering/ files. That might be worth filing as a bug with the Kiro team — your always-included steering files at the user level should be in-context from turn one without needing a hook to duplicate them.

[github-actions]

Thank you for your feedback! 🙏

The duplicate label has been removed and this issue has been sent back for maintainer review.

A maintainer will review this issue shortly.