feat(skills): two-tier loading with preloaded frontmatter

[exiao]

Summary

Two-tier skill loading: skills with preloaded: true in their YAML frontmatter show with full descriptions in the system prompt. Everything else is collapsed into category summaries (name + skill count + DESCRIPTION.md text). The model calls skills_list(category=...) to browse a category on demand.

Changes

agent/skill_utils.py

• Removed 60-char truncation in extract_skill_description() — descriptions are now shown in full

agent/prompt_builder.py

• Added preloaded field to _build_snapshot_entry() (read from frontmatter)
• Modified build_skills_system_prompt() to split into two sections:
  • Pre-loaded skills: shown individually with full descriptions
  • Skill categories: one line per category with count and DESCRIPTION.md summary
• Falls back to the existing full listing if no skills have preloaded: true (backward compatible)
• Updated tuple unpacking throughout to carry the new preloaded flag

SKILL.md frontmatter

---
name: my-skill
description: Full description shown in system prompt
preloaded: true
---

Token impact

Metric	Before	After
System prompt tokens	~6,100	~2,800
Skills model scans	266 entries	25 preloaded + 30 category summaries
Description quality	Truncated to 60 chars	Full text

Backward compatibility

• If no skills have preloaded: true, the existing full listing is used (no change)
• Snapshot cache format is extended (new preloaded key) — old snapshots are automatically invalidated by the manifest check

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 490baf049a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reinstate truncation for non-preloaded skill descriptions

extract_skill_description() now returns the full frontmatter description, but build_skills_system_prompt() still falls back to the legacy “list every skill” path when no skill has preloaded: true (see the if not has_any_preloaded branch). In the current tree, bundled skills do not set preloaded, so this fallback runs by default and now injects very long descriptions (many are hundreds of characters), which materially inflates the system prompt and token cost on every run. This is a regression from the previous capped behavior and undermines the intended prompt-size reduction.

Useful? React with 👍 / 👎.

[gemini-code-assist]

Code Review

This pull request introduces a preloaded flag for skills, allowing the system prompt to distinguish between skills shown individually and those grouped by category. It also updates tool names to PascalCase and stops truncating skill descriptions in the utility functions. The reviewer identified an opportunity to refactor the prompt generation logic to reduce code duplication between the new preloaded logic and the fallback path.

[gemini-code-assist]

This block introduces significant code duplication to handle the fallback case where no skills are preloaded. The logic for iterating through skills and formatting them is repeated in the if not has_any_preloaded: block.

This can be refactored to be more efficient and maintainable by processing all skills in a single loop and then constructing the final output based on whether any skills were preloaded. This avoids iterating over the skills multiple times and reduces duplicated code.

Here's a suggested refactoring:

        # Split skills into preloaded (shown individually) vs category-gated
        preloaded_lines = []
        category_counts: dict[str, int] = {}
        has_any_preloaded = False
        all_skills_lines_by_cat: dict[str, list[str]] = {}

        for category in sorted(skills_by_category.keys()):
            seen = set()
            all_skills_lines_by_cat.setdefault(category, [])
            for name, desc, preloaded in sorted(skills_by_category[category], key=lambda x: x[0]):
                if name in seen:
                    continue
                seen.add(name)

                category_counts[category] = category_counts.get(category, 0) + 1

                line = f"    - {name}: {desc}" if desc else f"    - {name}"
                all_skills_lines_by_cat[category].append(line)

                if preloaded:
                    has_any_preloaded = True
                    preloaded_lines.append(line)

        # If no skills have preloaded: true, fall back to showing everything
        if not has_any_preloaded:
            index_lines = []
            for category in sorted(all_skills_lines_by_cat.keys()):
                cat_desc = category_descriptions.get(category, "")
                if cat_desc:
                    index_lines.append(f"  {category}: {cat_desc}")
                else:
                    index_lines.append(f"  {category}:")
                index_lines.extend(all_skills_lines_by_cat[category])
            skills_block = "\n".join(index_lines)
        else:
            # Build category summary lines
            category_lines = []
            for category in sorted(category_counts.keys()):
                count = category_counts[category]
                cat_desc = category_descriptions.get(category, "")
                if cat_desc:
                    category_lines.append(f"    - {category} ({count} skills): {cat_desc}")
                else:
                    category_lines.append(f"    - {category} ({count} skills)")

            skills_block = (
                "  ## Pre-loaded skills (load with SkillView):\n"
                + "\n".join(preloaded_lines) + "\n\n"
                "  ## Skill categories (call skills_list(category=...) to browse):\n"
                + "\n".join(category_lines)
            )