Skill Adopter

Skill Adopter

Adopt enterprise skills into a target project, wired for the specific AI agent(s) in use.

When to use

• Onboarding a new or existing project onto the enterprise skills catalog.
• Adding, switching, or updating AI agent configuration in a project.
• Refreshing stale agent configs that reference old paths or removed artifacts.
• Aligning a project with the current skills repository after structural changes.

Required flow

1. Detect — Identify the project's tech stack and active AI agent(s).
2. Select — Choose relevant skills from the enterprise catalog.
3. Generate — Produce or update agent-native configuration files.
4. Verify — Confirm the generated configs reference valid skill paths.

Step 1: Detect project context

Scan the target project root for:

Tech stack signals

AI agent signals

If no agent config is found, ask the user which agent(s) they use.

Step 2: Select relevant skills

Use the enterprise skills catalog (skills.md at the repository root, or scan skills/.curated/ and skills/.system/ directories) to select skills.

Automatic selection by stack

Interactive refinement

After automatic selection, present the list to the user:

Based on your project, I recommend these skills:

Always:
  ✓ git-commit-helper
  ✓ code-reviewer
  ✓ systematic-debugging

Stack-specific:
  ✓ guicedee-inject
  ✓ guicedee-vertx
  ✓ guicedee-persistence
  ✓ entityassist
  ✓ activitymaster

Optional:
  ○ senior-architect
  ○ test-driven-development
  ○ security-best-practices

Add or remove skills? (Enter to accept)

Step 3: Generate agent configuration

Generate the agent-native config files. See references/agent-config-formats.md for the complete format reference per agent.

Submodule path resolution

Determine the skills repository path relative to the project root:

• If the skills repo is a git submodule (e.g., rules/ or AIRules/), use that prefix.
• If skills are installed to $CODEX_HOME/skills/, use ~/.codex/skills/ paths.
• If the skills repo is in the same workspace, use the relative path.

All skill references in generated configs must use resolved, valid relative paths.

Generation rules

1. One config per agent — generate only for detected/requested agents.
2. Skill references use SKILL.md paths — point to the SKILL.md file, not the directory.
3. Curated vs system — include both tiers when relevant; label them in the config.
4. Keep configs idempotent — re-running the adopter on the same project updates existing configs without duplication.
5. Preserve user customizations — if an agent config already exists, merge new skill references; do not overwrite custom rules or instructions.

Per-agent output summary

Step 4: Verify

After generation, verify:

1. Every referenced skill path resolves to an existing SKILL.md file.
2. No config references old/removed paths (e.g., .claude/skills/rules-repo-conventions/).
3. The config file is syntactically valid for the agent.
4. If a skills.md exists in the project, it is consistent with the generated configs.

Report any unresolved paths as warnings.

Refresh mode

When called with "refresh" or "update" intent:

1. Read existing agent config files.
2. Extract currently referenced skill paths.
3. Check each path against the current skills repository structure.
4. Replace broken paths with correct current paths.
5. Add newly relevant skills that were not previously included.
6. Remove references to skills that no longer exist.

References

• references/agent-config-formats.md — complete config format templates for each AI agent.

Source: GuicedEE/ai-rules — distributed by TomeVault.