feat(cli): imporve cow cli and skill hub integration

agent/skills/config.py

@@ -139,6 +139,47 @@ def should_include_skill(
     return True
 
 
+def get_missing_requirements(
+    entry: SkillEntry,
+    current_platform: Optional[str] = None,
+) -> Dict[str, List[str]]:
+    """
+    Return a dict of missing requirements for a skill.
+    Empty dict means all requirements are met.
+
+    :param entry: SkillEntry to check
+    :param current_platform: Current platform (default: auto-detect)
+    :return: Dict like {"bins": ["curl"], "env": ["API_KEY"]}
+    """
+    missing: Dict[str, List[str]] = {}
+    metadata = entry.metadata
+
+    if not metadata or not metadata.requires:
+        return missing
+
+    required_bins = metadata.requires.get('bins', [])
+    if required_bins:
+        missing_bins = [b for b in required_bins if not has_binary(b)]
+        if missing_bins:
+            missing['bins'] = missing_bins
+
+    any_bins = metadata.requires.get('anyBins', [])
+    if any_bins and not has_any_binary(any_bins):
+        missing['anyBins'] = any_bins
+
+    required_env = metadata.requires.get('env', [])
+    if required_env:
+        missing_env = [e for e in required_env if not has_env_var(e)]
+        if missing_env:
+            missing['env'] = missing_env
+
+    any_env = metadata.requires.get('anyEnv', [])
+    if any_env and not any(has_env_var(e) for e in any_env):
+        missing['anyEnv'] = any_env
+
+    return missing
+
+
 def is_config_path_truthy(config: Dict, path: str) -> bool:
     """
     Check if a config path resolves to a truthy value.

agent/skills/formatter.py

@@ -2,7 +2,7 @@
 Skill formatter for generating prompts from skills.
 """
 
-from typing import List
+from typing import Dict, List
 from agent.skills.types import Skill, SkillEntry
 
 
@@ -51,6 +51,71 @@ def format_skill_entries_for_prompt(entries: List[SkillEntry]) -> str:
     return format_skills_for_prompt(skills)
 
 
+def format_unavailable_skills_for_prompt(
+    entries: List[SkillEntry],
+    missing_map: Dict[str, Dict[str, List[str]]],
+) -> str:
+    """
+    Format unavailable (requires-not-met) skills as brief setup hints
+    so the AI can guide users to configure them.
+
+    :param entries: List of unavailable skill entries
+    :param missing_map: Dict mapping skill name to its missing requirements
+    :return: Formatted prompt text
+    """
+    if not entries:
+        return ""
+
+    lines = [
+        "",
+        "<unavailable_skills>",
+        "The following skills are installed but not yet ready. "
+        "Guide the user to complete the setup when relevant.",
+    ]
+
+    for entry in entries:
+        skill = entry.skill
+        missing = missing_map.get(skill.name, {})
+
+        missing_parts = []
+        for key, values in missing.items():
+            missing_parts.append(f"{key}: {', '.join(values)}")
+        missing_str = "; ".join(missing_parts) if missing_parts else "unknown"
+
+        setup_hint = _extract_setup_hint(skill)
+
+        lines.append("  <skill>")
+        lines.append(f"    <name>{_escape_xml(skill.name)}</name>")
+        lines.append(f"    <description>{_escape_xml(skill.description)}</description>")
+        lines.append(f"    <missing>{_escape_xml(missing_str)}</missing>")
+        if setup_hint:
+            lines.append(f"    <setup>{_escape_xml(setup_hint)}</setup>")
+        lines.append("  </skill>")
+
+    lines.append("</unavailable_skills>")
+    return "\n".join(lines)
+
+
+def _extract_setup_hint(skill: Skill) -> str:
+    """
+    Extract the Setup section from SKILL.md content as a brief hint.
+    Returns the first few lines of the ## Setup section.
+    """
+    content = skill.content
+    if not content:
+        return ""
+
+    import re
+    match = re.search(r'^##\s+Setup\s*\n(.*?)(?=\n##\s|\Z)', content, re.MULTILINE | re.DOTALL)
+    if not match:
+        return ""
+
+    setup_text = match.group(1).strip()
+    lines = setup_text.split('\n')
+    hint_lines = [l.strip() for l in lines[:6] if l.strip()]
+    return ' '.join(hint_lines)[:300]
+
+
 def _escape_xml(text: str) -> str:
     """Escape XML special characters."""
     return (text

agent/skills/frontmatter.py

@@ -128,6 +128,7 @@ def parse_metadata(frontmatter: Dict[str, Any]) -> Optional[SkillMetadata]:
     
     return SkillMetadata(
         always=meta_obj.get('always', False),
+        default_enabled=meta_obj.get('default_enabled', True),
         skill_key=meta_obj.get('skillKey'),
         primary_env=meta_obj.get('primaryEnv'),
         emoji=meta_obj.get('emoji'),

agent/skills/loader.py

@@ -184,7 +184,6 @@ class SkillLoader:
         
         config_path = os.path.join(skill_dir, "config.json")
         
-        # Without config.json, skip this skill entirely (return empty to trigger exclusion)
         if not os.path.exists(config_path):
             logger.debug(f"[SkillLoader] linkai-agent skipped: no config.json found")
             return ""

agent/skills/manager.py

@@ -84,10 +84,10 @@ class SkillManager:
         """
         Merge directory-scanned skills with the persisted config file.
 
-        - New skills discovered on disk are added with enabled=True.
+        - New skills: use metadata.default_enabled as initial enabled state.
+        - Existing skills: preserve their persisted enabled state.
         - Skills that no longer exist on disk are removed.
-        - Existing entries preserve their enabled state; name/description/source
-          are refreshed from the latest scan.
+        - name/description/source are always refreshed from the latest scan.
         """
         saved = self._load_skills_config()
         merged: Dict[str, dict] = {}
@@ -95,13 +95,18 @@ class SkillManager:
         for name, entry in self.skills.items():
             skill = entry.skill
             prev = saved.get(name, {})
-            # category priority: persisted config (set by cloud) > default "skill"
             category = prev.get("category", "skill")
+
+            if name in saved:
+                enabled = prev.get("enabled", True)
+            else:
+                enabled = entry.metadata.default_enabled if entry.metadata else True
+
             merged[name] = {
                 "name": name,
                 "description": skill.description,
                 "source": skill.source,
-                "enabled": prev.get("enabled", True),
+                "enabled": enabled,
                 "category": category,
             }
 
@@ -157,69 +162,114 @@ class SkillManager:
         """
         return list(self.skills.values())
     
+    @staticmethod
+    def _normalize_skill_filter(skill_filter: Optional[List[str]]) -> Optional[List[str]]:
+        """Normalize a skill_filter list into a flat list of stripped names."""
+        if skill_filter is None:
+            return None
+        normalized = []
+        for item in skill_filter:
+            if isinstance(item, str):
+                name = item.strip()
+                if name:
+                    normalized.append(name)
+            elif isinstance(item, list):
+                for subitem in item:
+                    if isinstance(subitem, str):
+                        name = subitem.strip()
+                        if name:
+                            normalized.append(name)
+        return normalized or None
+
     def filter_skills(
         self,
         skill_filter: Optional[List[str]] = None,
         include_disabled: bool = False,
     ) -> List[SkillEntry]:
         """
-        Filter skills based on criteria.
-
-        Simple rule: Skills are auto-enabled if requirements are met.
-        - Has required API keys -> included
-        - Missing API keys -> excluded
+        Filter skills that are eligible (enabled + requirements met).
 
         :param skill_filter: List of skill names to include (None = all)
         :param include_disabled: Whether to include disabled skills
-        :return: Filtered list of skill entries
+        :return: Filtered list of eligible skill entries
         """
         from agent.skills.config import should_include_skill
 
         entries = list(self.skills.values())
 
-        # Check requirements (platform, binaries, env vars)
         entries = [e for e in entries if should_include_skill(e, self.config)]
 
-        # Apply skill filter
-        if skill_filter is not None:
-            normalized = []
-            for item in skill_filter:
-                if isinstance(item, str):
-                    name = item.strip()
-                    if name:
-                        normalized.append(name)
-                elif isinstance(item, list):
-                    for subitem in item:
-                        if isinstance(subitem, str):
-                            name = subitem.strip()
-                            if name:
-                                normalized.append(name)
-            if normalized:
-                entries = [e for e in entries if e.skill.name in normalized]
+        normalized = self._normalize_skill_filter(skill_filter)
+        if normalized is not None:
+            entries = [e for e in entries if e.skill.name in normalized]
 
-        # Filter out disabled skills based on skills_config.json
         if not include_disabled:
             entries = [e for e in entries if self.is_skill_enabled(e.skill.name)]
 
         return entries
-    
+
+    def filter_unavailable_skills(
+        self,
+        skill_filter: Optional[List[str]] = None,
+    ) -> tuple:
+        """
+        Find skills that are enabled but have unmet requirements.
+
+        :param skill_filter: Optional list of skill names to include
+        :return: Tuple of (entries, missing_map) where missing_map maps
+                 skill name to its missing requirements dict
+        """
+        from agent.skills.config import should_include_skill, get_missing_requirements
+
+        entries = list(self.skills.values())
+
+        # Only enabled skills
+        entries = [e for e in entries if self.is_skill_enabled(e.skill.name)]
+
+        normalized = self._normalize_skill_filter(skill_filter)
+        if normalized is not None:
+            entries = [e for e in entries if e.skill.name in normalized]
+
+        # Keep only those that fail should_include_skill (requirements not met)
+        unavailable = []
+        missing_map: Dict[str, dict] = {}
+        for e in entries:
+            if not should_include_skill(e, self.config):
+                missing = get_missing_requirements(e)
+                if missing:
+                    unavailable.append(e)
+                    missing_map[e.skill.name] = missing
+
+        return unavailable, missing_map
+
     def build_skills_prompt(
         self,
         skill_filter: Optional[List[str]] = None,
     ) -> str:
         """
-        Build a formatted prompt containing available skills.
-        
+        Build a formatted prompt containing available skills
+        and brief hints for unavailable ones.
+
         :param skill_filter: Optional list of skill names to include
         :return: Formatted skills prompt
         """
         from common.log import logger
-        entries = self.filter_skills(skill_filter=skill_filter, include_disabled=False)
-        logger.debug(f"[SkillManager] Filtered {len(entries)} skills for prompt (total: {len(self.skills)})")
-        if entries:
-            skill_names = [e.skill.name for e in entries]
-            logger.debug(f"[SkillManager] Skills to include: {skill_names}")
-        result = format_skill_entries_for_prompt(entries)
+        from agent.skills.formatter import format_unavailable_skills_for_prompt
+
+        eligible = self.filter_skills(skill_filter=skill_filter, include_disabled=False)
+        logger.debug(f"[SkillManager] Eligible: {len(eligible)} skills (total: {len(self.skills)})")
+        if eligible:
+            skill_names = [e.skill.name for e in eligible]
+            logger.debug(f"[SkillManager] Eligible skills: {skill_names}")
+
+        result = format_skill_entries_for_prompt(eligible)
+
+        unavailable, missing_map = self.filter_unavailable_skills(skill_filter=skill_filter)
+        if unavailable:
+            unavailable_names = [e.skill.name for e in unavailable]
+            logger.debug(f"[SkillManager] Unavailable skills (setup needed): {unavailable_names}")
+            result += format_unavailable_skills_for_prompt(unavailable, missing_map)
+
         logger.debug(f"[SkillManager] Generated prompt length: {len(result)}")
         return result
     

agent/skills/types.py

@@ -29,6 +29,7 @@ class SkillInstallSpec:
 class SkillMetadata:
     """Metadata for a skill from frontmatter."""
     always: bool = False  # Always include this skill
+    default_enabled: bool = True  # Initial enabled state when first discovered
     skill_key: Optional[str] = None  # Override skill key
     primary_env: Optional[str] = None  # Primary environment variable
     emoji: Optional[str] = None