[FEATURE] Proposal: Treat Project Instructions as an Always-Active Skill

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

Background

Currently, project-wide guidance is typically provided through a dedicated INSTRUCTIONS.md file. At the same time, Claude Code already has the concept of reusable skills. Conceptually, however, project instructions are not fundamentally different from a skill. They are simply a reusable reasoning guide that should always be available. This creates two different mechanisms for storing very similar content.

The Problem

In practice, many projects duplicate information between:

• INSTRUCTIONS.md
• one or more skills
• external documentation

For example, projects often keep collaboration principles, documentation rules, reasoning style, modeling principles, or coding conventions inside INSTRUCTIONS.md, while related reusable procedures are implemented as skills. This separation introduces several problems:

• duplicated documentation,
• multiple sources of truth,
• forgotten updates,
• inconsistent behavior,
• uncertainty about where new guidance should be placed.

This issue becomes even more noticeable when the same project guidance is shared across multiple repositories or AI assistants. For example, some projects already maintain large standalone instruction documents such as https://github.com/maximiliamus/spec-kit-canon/blob/master/INSTRUCTIONS.md

These files effectively describe reusable reasoning behavior rather than a different kind of artifact.

Proposed Solution

Proposal

Instead of treating project instructions as a separate concept, consider modeling them as an always-active skill. For example:

.skills/
    main/
        SKILL.md

(or any equivalent built-in convention)

The main skill would be loaded automatically for every conversation, while all other skills would continue to be activated normally. This makes project-wide guidance simply another skill with a different loading strategy, rather than introducing a completely separate mechanism.

Benefits

• A single mechanism for reusable reasoning guidance.
• A single source of truth.
• Easier maintenance.
• Better modularity.
• Clear separation between always-active practices and task-specific practices.
• Projects can gradually extract independent topics from the main skill instead of continuously expanding a monolithic INSTRUCTIONS.md.

The loading behavior becomes the only difference:

• Main skill → always active.
• Other skills → activated when relevant.

Why "main"?

The proposed name intentionally avoids platform-specific terminology. It simply represents the project's primary reasoning context, similar to how main is commonly used as the primary entry point or primary branch in software development. This keeps the conceptual model simple:

• one reusable skill system,
• different activation strategies,
• no need for separate instruction-specific infrastructure.

I believe this would simplify both the mental model and the implementation while reducing documentation duplication across projects.

Alternative Solutions

_No response_

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

_No response_

Additional Context

I think it MUST be done with #80801