[Feature] Skill-aware agents — preload skills based on project stack

[davesleal]

Context

Skills are installed at the repo level (.claude/skills/, .agents/skills/) but agents don't know which skills apply to which project. A Swift iOS project needs different skills than a Next.js web project. Currently 26 skills installed:

Impeccable (21): adapt, animate, arrange, audit, bolder, clarify, colorize, critique, delight, distill, extract, frontend-design, harden, normalize, onboard, optimize, overdrive, polish, quieter, teach-impeccable, typeset

UI-Skills (5): baseline-ui, fixing-accessibility, fixing-metadata, fixing-motion-performance, frontend-design

Proposal

Skill mapping in projects.yaml

Each project declares which skills are relevant based on its stack:

projects:
  atmos:
    name: Atmos
    language: typescript
    platform: web
    skills:
      # Auto-detected from language/platform, or manually specified
      - frontend-design
      - baseline-ui
      - fixing-accessibility
      - fixing-motion-performance
      - fixing-metadata
      - overdrive
      - colorize
      - typeset
      - animate
      - harden
      - audit
      - optimize

  dayist:
    name: Dayist
    language: swift
    platform: ios
    skills:
      - audit
      - harden
      - optimize
      - polish
      - clarify

Auto-detection defaults

If no skills key in config, derive from language and platform:

Stack	Default skills
web / typescript / javascript	frontend-design, baseline-ui, fixing-accessibility, fixing-motion-performance, animate, colorize, typeset, overdrive, audit, harden, optimize
ios / swift	audit, harden, optimize, polish, clarify, critique
python / server	audit, harden, optimize, normalize
Any	adapt, distill, extract, onboard, clarify

Integration with Token Cart

• Pre-warm: On agent startup, load the skill manifest for the project. The agent's system prompt includes: "You have access to these skills: [list]. Invoke them when relevant."
• Token Cart pre-call: When enriching context, include relevant skill names so the agent knows what's available without re-reading the skill files.
• Observer/state keeper: The Haiku token cart tracks which skills were invoked during the session and includes this in the handoff — so the next turn knows what was already applied.

Skill invocation from Shellack

Agents should be able to invoke skills from within Slack:

@Shellack /audit the login form
@Shellack /fixing-accessibility src/components/Modal.tsx
@Shellack /overdrive the landing page hero

This means bot_unified.py needs to detect /skill-name patterns and route to the skill system.

Implementation

1. Add skills field to orchestrator_config.py loader (same pattern as features and team)
2. Add auto-detection defaults in a new tools/skill_mapper.py
3. Include skill manifest in ProjectAgent._build_system_prompt()
4. Track skill invocations in Token Cart handoff
5. Add /skill-name routing in bot_unified.py

Priority

Medium — improves agent quality for multi-stack workspaces.

[davesleal]

Refined approach: Architect-driven, not config-driven.

Global (always on): fixing-accessibility, audit, harden, clarify, optimize
Stack-specific: Architect consultant scans repo on bootstrap, produces skill manifest. No manual config needed.
Hard rule: Never load cross-stack skills. SwiftUI skills don't touch React projects.

Implementing now.