feat(skills): SkillRegistry, ClaudeAdapter, GeminiAdapter, skills:sync & skills:list commands

[bedus-creation]

Summary

Implements tasks #139, #140, and #141 — the core fastapi-startkit[skills] feature.

Task #139 — Skill Registry + Provider Discovery

• skills/registry.py: SkillRegistry scans only providers currently registered in the Application container. Each provider declares skills via a skills/ directory co-located with its provider.py. SKILL.md files are read and YAML front-matter (name, description) is parsed into a Skill dataclass.
• skills/provider.py: SkillsServiceProvider registers the registry under 'skills.registry' in the container and boots the CLI commands.

Task #140 — Adapter Layer (ClaudeAdapter + GeminiAdapter)

• skills/adapters/base.py: BaseAdapter ABC with render() and prune() — extensible for future Codex adapter.
• skills/adapters/claude.py: ClaudeAdapter writes idempotent .claude/skills/<name>/SKILL.md files with YAML front-matter. --prune removes directories for skills no longer in the registry.
• skills/adapters/gemini.py: GeminiAdapter splices a <!-- skills:start --> … <!-- skills:end --> block into GEMINI.md — never touches content outside the markers. Idempotent.

Task #141 — Cleo Commands

• skills:sync — resolves SkillRegistry, selects adapter(s) via --target (claude|gemini|all, default all), calls render(), optionally calls prune() when --prune is passed.
• skills:list — shows provider key, skill name, Claude/Gemini sync status (synced / pending), and truncated description for every discovered skill.

Test Plan

• 34 new pytest tests in tests/skills/ — all passing
  • test_registry.py — front-matter parsing, discovery, caching, get(), reset()
  • test_adapters.py — idempotency, prune, marker preservation (Gemini), append when no markers
  • test_commands.py — target routing, prune flag, unknown target error, status display
• Full test suite: 1296 passed, 0 failures (no regressions)

🤖 Generated with Claude Code

[bedus-creation]

Code Review — Conditional Approval (pending fix in PR #114)

PR #113 is well-structured and consistent with the existing provider/container patterns. All 34 tests pass. The architecture is correct and extensible.

✅ What looks good

• Architecture: SkillsServiceProvider follows the two-phase register/boot pattern correctly. Container key "skills.registry" is clear.
• SkillRegistry: Lazy discovery with caching, reset() for tests, get(name) convenience method — all good.
• ClaudeAdapter: Idempotent writes (only writes when content changes), correct prune logic (removes dirs not in the skill set), YAML front-matter format looks correct.
• GeminiAdapter: Marker-based approach preserves everything outside the managed block. Handles the case where markers don't exist yet by appending. Idempotent.
• BaseAdapter ABC: Clean extension point for future Codex or other adapters.
• YAML fallback: The _parse_frontmatter fallback parser when PyYAML is absent is minimal but sufficient for simple key: value front-matter. Good defensive coding.
• Test coverage: 34 tests covering registry parsing, discovery, caching, adapter idempotency, prune, and command routing.

🟡 One concern (minor, does not block this PR)

_skills_dir_for looks for skills/ next to the provider's module file. This is a correct and explicit contract. However, PR #114 places the canonical SKILL.md files in the wrong directories (next to the package root, not the provider module). This is a bug in #114, not here — but it's worth adding a note in the docstring to make the expectation unmistakable:

@staticmethod
def _skills_dir_for(provider) -> Path | None:
    """Return the ``skills/`` directory co-located with *provider*'s module file.

    For a provider defined in ``mypackage/providers/my_provider.py``, this
    returns ``mypackage/providers/skills/``.  Skills placed anywhere else
    (e.g. at the package root) will NOT be discovered.
    """

Verdict

Approve this PR on its own merits once PR #114 fixes its file placement bug. The contract is correct; the canonical SKILL.md files just need to move to the right location.

[bedus-creation]

Re-review — APPROVED ✅

Redesign confirmed correct. All 48 tests pass (34 skills + 14 new rules tests). F401 lint fix applied. Summary:

• SkillRegistry now reads from .ai/fastapi-startkit/skill/*/SKILL.md — clean centralized layout, no _skills_dir_for() hack needed
• RulesRegistry reads from rules/*.md — good separation
• SkillsServiceProvider.publishes() deploys stubs via artisan provider:publish --provider=skills
• provider:publish command confirmed to exist (console/publish_command.py)
• Rules commands (rules:sync, rules:list) are correctly implemented
• One real starter stub (fastapi-best-practices/SKILL.md) bundled in stubs/

Minor (non-blocking): _parse_frontmatter is exported from __init__.py despite its underscore naming convention suggesting it's internal. Not a blocker but may want to remove from __all__ to avoid users accidentally depending on it.

This PR is approved. Merge once PR #114 is fixed and rebased against the new layout.

[bedus-creation]

Architecture Note — Rules layout should nest inside skills (pre-merge change)

Updating my approval to flag one design issue before merge: the rules/ layout diverges from the Laravel Boost convention and should be corrected now, not as a follow-up.

Current vs. correct

Current PR #113:

.ai/fastapi-startkit/skill/fastapi-best-practices/SKILL.md   ← correct
rules/http-client.md                                          ← wrong location
rules/orm-queries.md                                          ← wrong location

Should match Laravel Boost:

.ai/fastapi-startkit/skill/fastapi-best-practices/
    SKILL.md
    rules/
        http-client.md
        orm-queries.md
        ...

Why this matters before merge

1. fastapi-best-practices/SKILL.md already references rules/http-client.md etc — they're one logical unit, they should be one physical unit
2. Prune/lifecycle: removing a skill naturally removes its rules; with rules/ at project root, rules become orphans
3. Single publish unit — artisan provider:publish --provider=skills delivers skill + rules together
4. Consistency with Laravel Boost — users coming from the Laravel ecosystem will look in the right place

Required changes to RulesRegistry

# Change scan path from:
RULES_BASE_PATH = Path("rules")                          # project root

# To:
SKILLS_BASE_PATH = Path(".ai") / "fastapi-startkit" / "skill"
# scan .ai/fastapi-startkit/skill/*/rules/*.md

Stubs to move

# From:
stubs/rules/http-client.md
# To:
stubs/.ai/fastapi-startkit/skill/fastapi-best-practices/rules/http-client.md

Adapters: no change needed

ClaudeRulesAdapter still writes to .claude/rules/<name>.md — flat output is correct regardless of source location. Same for Gemini.

---

Withdrawing approval until this is fixed. The code quality is good; this is purely a layout correction that should land in the same PR rather than a follow-up.

[bedus-creation]

Code Review — PR #113 CHANGES REQUIRED

Pytest passes (34 new tests, no regressions) — the implementation is solid. However Ruff blocks with 5 F401 unused import errors in test files:

1. tests/skills/test_adapters.py:7 — import pytest imported but unused — remove
2. tests/skills/test_commands.py:5 — from pathlib import Path imported but unused — remove
3. tests/skills/test_commands.py:185 — local from fastapi_startkit.skills.registry import Skill imported but unused — remove or use
4. tests/skills/test_registry.py:5 — import textwrap imported but unused — remove
5. tests/skills/test_registry.py:13 — Skill imported but unused — remove or use

All are auto-fixable: run uv run ruff check --fix tests/skills/ and re-push.

Verdict: BLOCKED — fix unused imports, then ready to approve