feat(prompts): implement skill-based dynamic prompt architecture

[echobt]

Summary

This PR transforms the monolithic system prompt architecture into a modular skill-based system where the agent loads specialized skills on-demand based on task requirements. This reduces context window usage by only including relevant instructions.

Changes

New Files

• src/cortex-prompt-harness/src/prompts/builtin_skills.rs - Six built-in skills:

  • git: Version control operations, commits, PRs, branches
  • code-quality: Linting, testing, style matching
  • file-operations: Safe file handling, read-before-write patterns
  • debugging: Tier 1-4 failure protocol, error recovery
  • security: Secrets handling, input validation
  • planning: Cognitive architecture, task decomposition

• src/cortex-prompt-harness/src/prompts/base_agent.rs - Minimal base agent prompt with skill loading mechanism

Modified Files

• src/cortex-prompt-harness/src/prompts/mod.rs - Added exports for new modules
• src/cortex-engine/src/session/prompt.rs - Added skill-based prompt building functions
• src/cortex-engine/src/tools/handlers/skill.rs - Added built-in skill support to UseSkill handler

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Skill-Based Prompt                        │
│  ┌─────────────────┐    ┌────────────────────────────────┐  │
│  │ Minimal Base    │ +  │ On-Demand Skills               │  │
│  │ (~500 tokens)   │    │ (loaded based on task)         │  │
│  │ - Core identity │    │ - git, code-quality, debugging │  │
│  │ - Skill loading │    │ - security, file-ops, planning │  │
│  │ - Essential     │    └────────────────────────────────┘  │
│  │   rules         │                                        │
│  └─────────────────┘                                        │
└─────────────────────────────────────────────────────────────┘

How It Works

1. Agent receives a task
2. Agent analyzes task and calls load_skill(["git", "debugging"])
3. UseSkill handler loads built-in skills and injects them into context
4. Agent proceeds with task-specific guidance

Skill Loading Examples

• "Create a PR" → load_skill(["git"])
• "Fix this bug" → load_skill(["debugging", "code-quality"])
• "Add new feature" → load_skill(["planning", "code-quality", "file-operations"])

Benefits

• Reduced context usage: Only load relevant skills (~500 tokens base vs ~2000+ monolithic)
• Modular updates: Skills can be updated independently
• Clear organization: Instructions organized by domain
• Backward compatible: Original monolithic prompt still available

Testing

• 157 tests pass in cortex-prompt-harness
• 43 tests pass in cortex-engine (skill-related)
• All new functionality covered with unit tests

Verification

cargo check -p cortex-prompt-harness -p cortex-engine
cargo test -p cortex-prompt-harness --lib
cargo test -p cortex-engine --lib -- skill

[greptile-apps]

Greptile Overview

Greptile Summary

This PR successfully transforms the monolithic system prompt architecture into a modular skill-based system. The implementation adds six built-in skills (git, code-quality, file-operations, debugging, security, planning) that can be loaded on-demand based on task requirements, reducing context window usage from ~2000+ tokens to ~500 tokens base plus only relevant skills.

Key Changes:

• Added builtin_skills.rs with six comprehensive skill definitions, each with YAML frontmatter and detailed instructions
• Added base_agent.rs with minimal base prompt and skill recommendation logic based on keyword matching
• Enhanced prompt.rs with skill-based prompt building functions (build_system_prompt_with_skills, inject_skills, auto_detect_skills_from_message)
• Updated skill.rs to prioritize built-in skills over filesystem skills in the loading hierarchy
• Added USE_SKILL_BASED_PROMPT flag (default: true) for backward compatibility with monolithic mode

Architecture Benefits:

• Reduces initial context usage by only loading relevant instructions
• Enables modular updates to individual skills without touching the monolithic prompt
• Maintains backward compatibility with existing monolithic prompt
• Well-tested with 157 tests in cortex-prompt-harness and 43 tests in cortex-engine

Code Quality:

• Excellent test coverage across all new functionality
• Clean separation of concerns between prompt building and skill loading
• Proper error handling with graceful fallbacks for missing skills
• Case-insensitive skill name matching throughout
• Consistent YAML frontmatter format across all skills

Confidence Score: 5/5

• This PR is safe to merge with high confidence
• The implementation is well-architected with comprehensive test coverage (200+ tests), backward compatibility via feature flag, and no breaking changes to existing functionality. All skills are properly validated and the code follows Rust best practices.
• No files require special attention - all changes are well-tested and follow consistent patterns

Important Files Changed

Filename	Overview
src/cortex-prompt-harness/src/prompts/mod.rs	Added exports for new base_agent and builtin_skills modules with clean re-exports
src/cortex-prompt-harness/src/prompts/base_agent.rs	New minimal base prompt with skill loading mechanism, comprehensive tests, and skill recommendation logic
src/cortex-prompt-harness/src/prompts/builtin_skills.rs	Six built-in skills (git, code-quality, file-operations, debugging, security, planning) with YAML frontmatter and comprehensive documentation
src/cortex-engine/src/session/prompt.rs	Added skill-based prompt building functions with auto-detection and injection logic, backward compatible with monolithic mode
src/cortex-engine/src/tools/handlers/skill.rs	Enhanced skill handler to load built-in skills with priority over filesystem skills, comprehensive test coverage

Sequence Diagram

sequenceDiagram
    participant User
    participant Agent
    participant PromptBuilder
    participant SkillLoader
    participant BuiltinSkills
    
    User->>Agent: "Fix this bug and create a PR"
    Agent->>PromptBuilder: Request prompt construction
    
    alt Skill-based mode (USE_SKILL_BASED_PROMPT=true)
        PromptBuilder->>PromptBuilder: auto_detect_skills_from_message()
        Note over PromptBuilder: Detects: ["debugging", "git"]
        PromptBuilder->>PromptBuilder: build_system_prompt_with_skills()
        PromptBuilder->>BuiltinSkills: get_builtin_skill("debugging")
        BuiltinSkills-->>PromptBuilder: SKILL_DEBUGGING content
        PromptBuilder->>BuiltinSkills: get_builtin_skill("git")
        BuiltinSkills-->>PromptBuilder: SKILL_GIT content
        PromptBuilder->>PromptBuilder: inject_skills(BASE_PROMPT_WITH_SKILLS, skills)
        PromptBuilder->>PromptBuilder: strip_yaml_frontmatter()
        PromptBuilder-->>Agent: Base prompt + skill instructions (~1500 tokens)
    else Monolithic mode
        PromptBuilder->>PromptBuilder: build_system_prompt()
        PromptBuilder-->>Agent: CORTEX_MAIN_PROMPT (~2000+ tokens)
    end
    
    Agent->>Agent: Execute task with loaded skills
    
    opt Agent calls UseSkill tool
        Agent->>SkillLoader: UseSkill("security")
        SkillLoader->>SkillLoader: load("security")
        SkillLoader->>BuiltinSkills: is_builtin_skill("security")
        BuiltinSkills-->>SkillLoader: true
        SkillLoader->>BuiltinSkills: get_builtin_skill("security")
        BuiltinSkills-->>SkillLoader: SKILL_SECURITY content
        SkillLoader->>SkillLoader: parse_skill_md(content)
        SkillLoader->>SkillLoader: Register in SkillRegistry
        SkillLoader-->>Agent: Skill loaded with instructions
    end
    
    Agent-->>User: Task completed with appropriate skills

Loading

[greptile-apps]

_{5 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[echobt]

waiting for benchmark, don't merge