Skill silently dropped when description exceeds length limit — no warning or error

[Gurumi-glitch]

Summary

A Skill whose description frontmatter field exceeds an undocumented length limit is silently dropped from the session's skill list — it does not appear in the model's available skills, and no warning or error is emitted at session start. This makes the failure mode invisible and very costly to diagnose.

Environment

• kimi-code CLI: 0.28.0
• OS: Linux (WSL)
• Working dir: /home/gurumi/workspace-wartable-5e
• KIMI_CODE_HOME: unset (default ~/.kimi-code/)
• Provider: third-party (not a Kimi plan subscription) — confirmed unrelated (see investigation below)

Reproduction

1. Create a skill at ~/.kimi-code/skills/codebase-memory/SKILL.md (User scope) with this frontmatter:

   ---
   name: codebase-memory
   description: Use the codebase knowledge graph for structural code queries. Triggers on: explore the codebase, understand the architecture, what functions exist, show me the structure, who calls this function, what does X call, trace the call chain, find callers of, show dependencies, impact analysis, dead code, unused functions, high fan-out, refactor candidates, code quality audit, graph query syntax, Cypher query examples, edge types, how to use search_graph.
   ---

   (This description is 453 characters.)

2. Start a new kimi session.

3. Observe: the codebase-memory skill does not appear in the skill list. No warning is printed.

4. Edit the frontmatter to shorten the description to ~130 chars:

   description: Use the codebase knowledge graph for structural code queries (callers, callees, impact, dead code, architecture, Cypher).

5. Start a new session.

6. Observe: the skill now appears correctly.

Expected behavior

• Either: accept long descriptions (the docs only say "a one-line summary" with no stated length cap), or
• If there is a length limit: emit a clear warning/error at session start naming the offending skill file and the limit, instead of silently dropping it.

Actual behavior

Skill is silently dropped. The only way to discover the failure is to notice the skill is missing from the list and bisect the frontmatter by hand.

Investigation notes (what I ruled out)

• Not a scope/scan-path bug: the same file was also placed at .agents/skills/codebase-memory/SKILL.md (Project scope) — also dropped. Shortening the description fixed both scopes.
• Not a "manual mkdir" issue: Project-scope sibling skills (e.g. convex) created by tooling load fine; the scan logic itself works.
• Not a subscription/provider gate: Project-scope convex skills load normally under a third-party provider with no Kimi plan. The skill subsystem is active; only this specific file is rejected.
• Not a session-staleness issue: tested in a freshly started session.
• File format is valid YAML: name and description both present (required for directory-form SKILL.md per docs); the long description is a single line.

Docs reference

The Skills docs describe description as "a one-line summary" and mention a 240-char fallback for the body's first line when description is omitted in flat-form files — which hints at a length consideration, but no hard limit is documented for description, and no truncation or warning behavior is specified for the over-limit case.

Suggested fix

At minimum: log a warning naming the file and the exceeded limit when a skill is dropped during load. Ideally also: document the exact description length limit in the docs (and/or raise it — 240 chars is quite tight for a field the model uses to decide when to auto-invoke a skill).

Reproducibility

100% reproducible. Bisection between 453-char and 130-char description is the decisive variable.

[Gurumi-glitch]

Apologies for not using the bug report template on the initial submission — restating in the template structure for easier triage. (Full investigation notes are in the original description above.)

What version of Kimi Code is running?

0.28.0 (from kimi --version)

Which open platform/subscription were you using?

Z.ai (third-party provider via OpenAI-compatible protocol — not a Kimi plan subscription). Confirmed unrelated to the bug: Project-scope skills shipped by tooling (e.g. convex) load normally under this setup, so the skill subsystem is active. Only this specific skill file is rejected.

Which model were you using?

N/A — the bug is in the CLI's skill-loading layer at session start, before any model invocation. Reproduces regardless of model.

What platform is your computer?

Linux (WSL on Windows). KIMI_CODE_HOME unset (default ~/.kimi-code/).

What issue are you seeing?

A Skill whose description frontmatter field exceeds an undocumented length limit (~240 chars) is silently dropped from the session's skill list at startup. It does not appear in the model's available skills, and no warning or error is emitted — the only way to discover the failure is to notice the skill is missing and bisect the frontmatter by hand.

What steps can reproduce the bug?

1. Create ~/.kimi-code/skills/codebase-memory/SKILL.md (User scope) with this frontmatter:

   ---
   name: codebase-memory
   description: Use the codebase knowledge graph for structural code queries. Triggers on: explore the codebase, understand the architecture, what functions exist, show me the structure, who calls this function, what does X call, trace the call chain, find callers of, show dependencies, impact analysis, dead code, unused functions, high fan-out, refactor candidates, code quality audit, graph query syntax, Cypher query examples, edge types, how to use search_graph.
   ---

   (description is 453 chars)

2. Start a new kimi session.

3. Observe: codebase-memory does not appear in the skill list. No warning printed.

4. Shorten the description to ~130 chars:

   description: Use the codebase knowledge graph for structural code queries (callers, callees, impact, dead code, architecture, Cypher).

5. Start a new session.

6. Observe: skill now appears correctly.

Also confirmed the same file placed at .agents/skills/codebase-memory/SKILL.md (Project scope) is dropped too — fixing the description fixes both scopes, so it's not a scope-specific scan-path bug.

What is the expected behavior?

Either:

• Accept long descriptions (the docs only say "a one-line summary" with no stated length cap), or
• If there is a length limit: emit a clear warning at session start naming the offending skill file and the limit, instead of silently dropping it.

Additional information

• Root cause bisection: 453-char vs 130-char description is the decisive variable. 100% reproducible.
• Docs reference: the Skills docs describe description as "a one-line summary" and mention a 240-char fallback for the body's first line when description is omitted in flat-form files — which hints at a length consideration, but no hard limit is documented for description, and no truncation/warning behavior is specified for the over-limit case.
• Suggested fix: at minimum, log a warning naming the file and the exceeded limit when a skill is dropped during load. Ideally also document the exact description length limit (and/or raise it — 240 chars is tight for a field the model uses to decide when to auto-invoke a skill).
• Investigation notes ruling out other causes (scope/scan-path, manual mkdir, subscription gate, session staleness, YAML validity) are in the original issue description above.

[Gurumi-glitch]

Thanks @arimu1! both in claude code or codex parses the skill anyway that's why i never realized this was the issue, it became clear now!

For now i'll quote the skill description since that's the fastest way to resolve this for me!