feat(skills): wire skill loading into workflow execution

[pocky]

Summary

• Implement F096: agent skills integration — workflows can now declare skills: in agent steps to inject deterministic domain knowledge (from SKILL.md files) into the agent's prompt context before execution
• Skills are discovered across 7 priority-ordered directories (.awf/skills/, .agents/skills/, .claude/skills/, XDG global, and their home-dir equivalents) with AWF_SKILLS_PATH env override; path-based explicit references are also supported
• awf validate now checks all skill references for existence and content, reporting skill_not_found, skill_missing_skillmd, and skill_empty_content codes at pre-runtime
• SKILL.md frontmatter is stripped; skill body is injected as a structured <skill_content> XML block (agentskills.io-compliant) with bundled resource enumeration, prepended before the user prompt

Changes

Application Layer

• internal/application/skill_loader.go: New ResolveAndFormatSkills function — resolves skill references (name-based and path-based), loads SKILL.md content, strips frontmatter, and formats as <skill_content> XML blocks with bundled resource listing
• internal/application/execution_service.go: Wire skillRepo field; inject resolved skill content into executeAgentStep before prompt resolution when step.Skills is non-empty
• internal/application/execution_setup.go: Call SetSkillRepository during service initialization

Infrastructure — Skills

• internal/infrastructure/skills/filesystem_repository.go: Expand discovery to cover all 7 standard directories (project + global for AWF, cross-client, and Claude Code compat tiers)
• internal/infrastructure/skills/frontmatter.go: Fix YAML frontmatter stripping to preserve metadata without leaking it into injected content

Infrastructure — Repository

• internal/infrastructure/repository/yaml_mapper.go: Map skills: YAML array to domain Step.Skills field; handle both string (name) and object (path:) references
• internal/infrastructure/repository/yaml_types.go: Add SkillRef YAML type supporting name and path forms

CLI — Validate

• internal/interfaces/cli/validate.go: Add skill validation pass — resolve all declared skills across all steps at validate-time, report missing directories, missing SKILL.md, and empty content

Domain

• internal/domain/workflow/validation_errors.go: Add skill_not_found, skill_missing_skillmd, skill_empty_content validation error codes

Test Utilities

• internal/testutil/builders/builders.go: Add skill-related builder helpers
• internal/testutil/mocks/mocks.go: Add MockSkillRepository for unit test injection

Tests

• internal/application/execution_service_skillwiring_test.go: Unit tests for skill wiring through ExecutionService
• internal/application/skill_loader_test.go: Comprehensive unit tests for ResolveAndFormatSkills (name resolution, path resolution, frontmatter stripping, resource enumeration, error cases)
• internal/infrastructure/repository/yaml_mapper_skill_test.go: YAML parsing tests for skill reference types (string and path forms)
• internal/infrastructure/skills/filesystem_repository_test.go: Discovery tests across all 7 tiers including XDG fallback paths
• internal/interfaces/cli/validate_skill_test.go: CLI validate command tests for skill validation errors and warnings
• tests/integration/skills/skills_functional_test.go: End-to-end functional tests for skill loading and injection
• tests/integration/skills/validate_command_skills_test.go: Integration tests for awf validate skill checks
• internal/domain/workflow/skill_test.go: Remove obsolete test stubs
• internal/domain/workflow/skill_validation_codes_test.go: Update for new validation code names

Documentation

• docs/user-guide/agent-steps.md: Full Agent Skills section — basic usage, skill references, discovery directories, SKILL.md format, injection format, validation table, limitations
• docs/user-guide/workflow-syntax.md: Add skills: field to agent step reference table and example block
• docs/reference/error-codes.md: Document USER.INPUT.MISSING_SKILL error code
• docs/reference/interpolation.md: Document {{.awf.skills_dir}} variable and skills discovery in local-before-global resolution
• docs/development/project-structure.md: Add infrastructure/skills/ and .awf/skills/ to directory tree
• docs/README.md: Link Agent Skills sub-section in navigation

Config

• .go-arch-lint.yml: Register infra-skills component with correct dependency allowlist
• CLAUDE.md: Add two new pitfall entries for frontmatter parsing and XDG fallback testing
• README.md: Add Agent Skills to feature list
• .gitignore: Ignore .agents directory

Test plan

• make test — all unit and integration tests pass with no race conditions (make test-race)
• make lint — zero lint violations including arch-lint
• awf validate <workflow-with-skills> — reports skill_not_found for missing skills and skill_empty_content warnings for empty SKILL.md files
• awf run <workflow> — agent step with skills: receives <skill_content> blocks prepended to prompt; verify with --dry-run or verbose output

Closes #346

---

Generated with awf commit workflow