Rename xe_forge.skills to xe_forge.tools with backward-compatible CLI migration

[mzweilin]

Summary

Rename the package path from src/xe_forge/skills to src/xe_forge/tools so naming aligns with agentic AI terminology (tools as callable capabilities), while preserving current user workflows.

Motivation

The current package is functionally a tool surface, but the term skills is overloaded in agent ecosystems. Using tools improves clarity for:

• Internal architecture and import paths
• Agent prompt/template language
• Future interoperability with tool-calling conventions

Current References

Primary wiring points today:

• Entry point script target: pyproject.toml
• Skill router and imports: init.py
• Internal imports to update: init.py
• Agent template command references: CLAUDE.md.j2
• Tool-runner template references: tool-runner.md.j2
• Script allowlist template references: settings.json.j2

Proposal

• Rename package directory from src/xe_forge/skills to src/xe_forge/tools.
• Update imports from xe_forge.skills.* to xe_forge.tools.*.
• Keep existing CLI command xe-forge-skill as a compatibility alias for at least one release cycle.
• Add new alias xe-forge-tool (optional but recommended).
• Update generated templates and docs to prefer xe-forge-tool language over time.

Scope

• Python package path and import updates
• Project script entry points
• Core templates under src/xe_forge/claude/templates
• Top-level docs that show command usage (README/VTUNE guidance)

Out of Scope

• Removing xe-forge-skill immediately
• Bulk cleanup of archived/generated workspace snapshots unless explicitly requested

Implementation Tasks

• Move src/xe_forge/skills to src/xe_forge/tools
• Update module imports in router and tool modules
• Update script target in pyproject.toml
• Add dual CLI script names (xe-forge-skill + xe-forge-tool) during transition
• Update wording in init.py equivalent after move
• Update agent templates:
  • CLAUDE.md.j2
  • tool-runner.md.j2
  • settings.json.j2
• Update user docs:
  • README.md
  • VTUNE.md
• Add/adjust tests for CLI entry points and import resolution

Backward Compatibility Plan

Phase 1:

• Keep xe-forge-skill fully functional.
• Introduce xe-forge-tool alias and document as preferred.

Phase 2:

• Emit deprecation notice for xe-forge-skill in a later release.

Phase 3:

• Remove xe-forge-skill only after downstream templates/workspaces are migrated.

Acceptance Criteria

• Both xe-forge-skill and xe-forge-tool execute successfully and route to the same handlers.
• No runtime import errors after package move.
• Generated Claude templates reference the preferred command naming.
• Documentation examples are updated and consistent.
• CI/tests pass for CLI and module imports.

Risks

• Breaking downstream automation that hardcodes xe-forge-skill.
• Missing references in generated workspace artifacts.
• Packaging regressions if script target/import path updates are incomplete.

Notes

A staged migration minimizes disruption while modernizing terminology for agentic workflows.

[mzweilin]

@sandlbn @danielfleischer what do you think?

[danielfleischer]

I think "tools" is the right concept, regardless of the misuse of "skills".

I wouldn't put too much emphasize of backward compatibility as "hooks" vs "tools" are only internal concepts, not really visible to the user who's not modifying this framework.

Just make sure both workflows are correct after renaming.