Skills Architecture

Spexso uses Claude Code's native skills system. Skills are not bundled with Spexso — they are installed by the developer per project using the standard .claude/skills/ directory. A separate flexso-sap-skills plugin exists for this and is actively recommended (advisory, never blocking) by the /spexso-setup and /spexso-start preflight checks when missing.

Skill Hierarchy and Priority

Layer	Purpose	Priority	Example
Agent definition	Process rules (how to review, when to test)	Highest — wins on conflict	"Run tests before implementation"
CLAUDE.md	Project conventions (patterns, structure)	High	"Use CAP Node.js, not Java"
Domain rulebooks .spexso/rules/	Project-tunable code quality rules per SAP domain	Above generic skills	"Use CQL, never SQL strings"; "Lazy-load UI5 fragments"
Project skills .claude/skills/	Generic domain knowledge	Medium	CAP patterns, UI5 conventions
Personal skills ~/.claude/skills/	Developer's personal workflows	Lowest	Preferred test patterns, editor macros

Domain rulebooks vs. skills

Skills are generic and external (shipped by plugins, shared across all Flexso projects). The domain rulebooks in .spexso/rules/ are project-specific and version-controlled in your repo — this is where a team encodes its own CAP/UI5 tips, tricks, and hard-won rules. Both the builder (before writing code) and the reviewer (when reviewing) load the rulebook matching the files in scope. When a rulebook rule and a generic skill suggestion conflict, the rulebook wins; CLAUDE.md and agent process rules still rank above the rulebook. Each rulebook is a pair — the spexso baseline {domain}.md plus the project's own {domain}.local.md, which wins on conflict. spexso init seeds and refreshes the baselines (typescript.md, cap.md, ui5.md, ux.md, test.md, abap.md, doctrine.md), never touches a .local.md file, and never clobbers a baseline the team edited by hand — see Baseline + local rules.

How Developers Add Skills

# Option 1: Create manually
mkdir -p .claude/skills/sap-ai-sdk
cat > .claude/skills/sap-ai-sdk/SKILL.md << 'EOF'
---
name: sap-ai-sdk
description: SAP AI SDK patterns for BTP. Use when building AI features,
  orchestrating LLM calls, or integrating SAP AI Core services.
---
# SAP AI SDK Patterns
- Always use @sap-ai-sdk/orchestration for LLM calls
- Use deployment IDs from AI Launchpad, never hardcode model names
- Handle token limits with chunking pattern...
EOF

# Option 2: Install the Flexso SAP skills plugin (recommended by setup/start preflight)
# /plugin install flexso-sap-skills@flexso-registry

# Option 3: Copy from another project
cp -r ../other-project/.claude/skills/react-patterns .claude/skills/

# Skills are auto-discovered — no registration needed
# Claude loads them on-demand when relevant (~100 tokens per skill in idle)

Collision Resolution Rule

Explicit in every agent definition

Every Spexso agent definition includes this header: "Agent process rules override skill suggestions when in conflict. Skills provide domain knowledge (what to use). Agent definitions provide choreography (how to work). These are orthogonal — if they collide, the agent definition wins."

Example Skill Compositions

Project type	Skills installed
CAP + Fiori Elements extension	cap-nodejs, fiori-elements, cds-modeling, xsuaa-auth
UI5 freestyle app	ui5-freestyle, ui5-tooling, odata-v4
React + CAP headless API	cap-nodejs, react-patterns, rest-api-design
AI extension with SAP AI Core	cap-nodejs, sap-ai-sdk, langchain-patterns