fix: add CLAUDE.md and skills reading instructions for subagents

[Perlover]

Problem

When standards_as_claude_code_skills: true is set in config.yml, subagents (implementer, tasks-list-creator, spec-writer, etc.) lose access to project coding standards and CLAUDE.md instructions.

Root Cause

According to Claude Code subagents documentation, subagents receive:

• Custom system prompt (from the agent definition file)
• Configured tools (inherited or specified)
• Auto-loaded skills (only if specified in skills: field)
• Separate context window

Critical findings:

1. CLAUDE.md is NOT inherited by subagents

   • The CLAUDE.md documentation states that memory files are "automatically loaded into Claude Code's context when launched"
   • However, there is no mention of subagents inheriting CLAUDE.md files
   • Subagents operate with their own separate context window

2. Skills require explicit configuration

   • Subagents documentation shows skills can be loaded via the skills: field in agent frontmatter:

     ---
     name: example-agent
     skills: skill1, skill2  # Optional - skills to auto-load
     ---

   • Agent-os agents do not include the skills: field, so skills are never loaded

3. Empty fallback in agent-os

   • The {{UNLESS standards_as_claude_code_skills}} block is skipped when skills mode is enabled
   • There's no {{IF standards_as_claude_code_skills}} alternative

Current Behavior

In agent files like implementer.md, standards are included conditionally:

{{UNLESS standards_as_claude_code_skills}}
## User Standards & Preferences Compliance

IMPORTANT: Ensure that the tasks list you create IS ALIGNED...

{{standards/*}}
{{ENDUNLESS standards_as_claude_code_skills}}

standards_as_claude_code_skills	Result
false	Standards embedded directly via {{standards/*}} ✅
true	Entire block skipped — agent receives nothing ❌

Impact

Subagents may:

• Use wrong commands (e.g., npm test instead of project-specific make test)
• Ignore project architecture patterns
• Write code that violates project conventions
• Miss critical instructions from CLAUDE.md

Expected Behavior

When standards_as_claude_code_skills: true, subagents should either:

Option A: Be instructed to manually read relevant files:

1. CLAUDE.md (if exists) for project-specific instructions
2. agent-os/standards/ files for coding standards
3. .claude/skills/ files for detailed patterns

Option B: Include the skills: field in agent frontmatter to auto-load relevant skills (though this is challenging since skill names are project-specific)

Affected Agents

• implementer.md
• tasks-list-creator.md
• spec-writer.md
• spec-shaper.md
• spec-verifier.md
• product-planner.md
• implementation-verifier.md

Environment

• agent-os version: 2.1.1
• Profile: default (affects all profiles using this pattern)

References

• Subagents - Claude Code Docs — documents subagent configuration including the skills: field for auto-loading skills
• Memory (CLAUDE.md) - Claude Code Docs — documents how CLAUDE.md is loaded (no mention of subagent inheritance)

[Perlover]

Hello everyone! At first, I made a fairly significant change and submitted a pull request, but then I found a simpler and more elegant solution. I analyzed the encoded executable of the Claude Code utility using the same Claude Code and discovered that Skill is indeed used in subagents, but only under certain conditions. Either "tools:" must explicitly specify that Skill should be used, or "tools:" must not be defined at all in the subagent headers, because the source code shows that agent-os includes this "tools:" header, but Skill is not present there.

Therefore, the simplest approach is to add Skill everywhere it may be needed for using abilities. Why did I decide to do this without special conditions for enabling the “Use standards as Skill” option? Because the programmer may intend for subagents to still load an additional Skill module written by the programmer specifically for the project or globally for the user space. That is why I believe Skill must always be present; otherwise, it simply will not use abilities when performing programming tasks.

I consider this a critical fix. For those who do not want to wait until the author approves these changes, you can use the following bash command to install my version of agent-os, which includes these minimal adjustments.

curl -sSL "https://raw.githubusercontent.com/Perlover/agent-os/fix/subagent-skills-and-claude-md/scripts/base-install.sh" \
    | sed 's|buildermethods/agent-os|Perlover/agent-os|g; s|/raw/main/|/raw/fix/subagent-skills-and-claude-md/|g; s|branch="main"|branch="fix/subagent-skills-and-claude-md"|g' \
    > /tmp/install-fixed.sh && bash /tmp/install-fixed.sh

[Perlover]

As proof that the original version of Agent-OS does not work with Skills while the patched version does, I created a test repository, verified it myself, and confirmed that this is exactly the case. Here is the link to the repository.

https://github.com/Perlover/agent-os-test-skills/

[CasJam]

@Perlover thanks for this and for the explanation 👍