[FEATURE] Subagent Configuration Enhancements: Native `@import` Support and Scope Isolation (Independent Rules/Skills)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

📌 Context and Pain Points

Currently, subagents in Claude Code lack robust configuration mechanisms for prompt reuse and scope isolation. This violates the software engineering DRY (Don't Repeat Yourself) principle and causes severe context pollution.

I am raising this issue to propose two core architectural upgrades for subagents. (Note: A similar request for @import was previously raised in #6899 but was closed by the stale bot. I am reopening the discussion with a more comprehensive architectural design).

The Current Developer Dilemmas:

1. No Clean Way to Reuse System Prompts: If multiple subagents need to share the same set of rules, developers must either copy-paste them into every .md file, or instruct the subagent to use the Read tool upon initialization. The latter is slow, wastes tokens, and completely bypasses Prompt Caching benefits.

The current community workaround—forcing the Main Agent to load the rules and pass them to the subagent as a User Prompt—is a very dirty hack. It severely pollutes the Main Agent's context window. Furthermore, because the rules are downgraded to a standard User Prompt, the LLM's adherence and stability drop significantly compared to a native System Prompt.

1. Forced Inheritance of Global Scope (Scope Pollution): Currently, subagents are forced to inherit all project-level rules and skills. This explicitly violates the Principle of Least Privilege. A subagent dedicated strictly to writing unit tests has no business seeing global UI design guidelines in its context window, nor should it possess the permissions or tools to mutate the database.

Proposed Solution

🚀 Proposed Architecture and Design

Part 1: Native @import Support in Subagent Profiles

Allow the use of the @import syntax directly within subagent configuration files (e.g., agents/{agent}.md), similar to how memory currently works in CLAUDE.md.

Mechanism:
When Claude Code instantiates a subagent, the underlying system should statically resolve all @import paths and compile their contents directly into the subagent's System Prompt before executing the API request.

Configuration Example (.claude/agents/security-reviewer.md):

name: security-reviewer
description: Performs code security audits.
tools: Read, Grep
---
You are a security audit expert.
@./.claude/rules/common-security-guidelines.md
@./.claude/rules/js-specific-rules.md

Part 2: Subagent-Specific Directories and Scope Isolation

This is an advanced architectural design. Allow subagents to exist as "directories" rather than just single files, granting them completely independent configurations, rules, and skills to completely eliminate global pollution.

Proposed Directory Structure:

.claude/
  agents/
    security-reviewer/
      AGENT.md          # Main config for this subagent
      rules/            # Local rules exclusively for security-reviewer
      skills/           # Local tools exclusively for security-reviewer

Proposed Isolation Flags in AGENT.md:

name: security-reviewer
inherit_global_rules: false   # Disables global inheritance: ignores project-level .claude/rules/
inherit_global_skills: false  # Disables global inheritance: strictly uses only its own skills directory or explicitly defined tools
---
[System Prompt block here]

💡 Why "Independent Rules & Skills" is Crucial:

1. Laser-Focused Context (Attention Mechanism): Let the subagent focus only on the rules it needs to see. Stripping away irrelevant global rules not only saves tokens but drastically improves the LLM's instruction adherence.
2. Converged Tool Selection (Reduced Hallucinations): When a subagent inherits dozens of global tools, its search space for "which tool to use" becomes unnecessarily large, leading to hallucinations or incorrect tool calls. Restricting it to dedicated, domain-specific skills makes its behavior much safer and more predictable (e.g., ensuring a testing agent cannot accidentally trigger deployment tools).
3. True "Plug-and-Play" Modularity: Developers could simply copy a configured subagent folder (containing its perfectly scoped prompts and tools) and paste it into another project, achieving true, portable agent modularity.

---

Thank you to the team for considering this architectural upgrade! I strongly believe that combining native @import with Scope Isolation will truly unlock the powerful potential of multi-agent collaboration in Claude Code.

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

_No response_

Additional Context

_No response_