Problem

The real issue is a vicious cycle: Kimi Code CLI's system prompt template does not explain the SKILL.md format, so the agent writes invalid skills for users, which are then silently discarded by the parser.

The vicious cycle

1. User asks the agent to "help me write a skill".
2. The agent looks at the system prompt. The Skills section only says:

   "Each skill is either a self-contained directory with a SKILL.md file or a standalone .md file..."
   There is zero mention of YAML frontmatter, the required name / description fields, or the directory-vs-flat distinction.

3. The agent guesses the format and writes a SKILL.md that looks reasonable but lacks frontmatter, or lacks name / description.
4. packages/agent-core/src/skill/parser.ts enforces strict validation on directory skills:
   • Must start with --- frontmatter.
   • Frontmatter must contain both name and description.
5. When either check fails, scanner.ts catches the SkillParseError, logs a warning, and silently skips the skill.
6. The user has no idea the skill was ignored. On the next prompt the agent still cannot see the skill, because it was never loaded into SkillRegistry.

Concrete example

I asked Kimi to create two user-level skills. It produced:

• ~/.kimi-code/skills/ai-chat-summary/SKILL.md — no frontmatter at all, started with # AI 对话总结...
• ~/.kimi-code/skills/sync-xiaomi-photos/SKILL.md — had frontmatter, but missing the name field, only description

Both were discarded silently. The session's Current available skills listed only the built-in update-config.

Why this is worse than a plain parser bug

If the parser simply had a bug, fixing the parser would be enough. But here the agent itself is the author of the broken files, because the system prompt fails to teach it the correct format. Fixing only the parser without updating the system prompt means the agent will keep writing broken skills for users indefinitely.

Proposed fix

1. Update packages/agent-core/src/profile/default/system.md — Add a concise "Skill format" section that explains the optional YAML frontmatter block, the name / description / type / whenToUse fields, and the directory-vs-flat distinction.
2. Relax packages/agent-core/src/skill/parser.ts — Remove the strict name/description mandatory checks for directory skills. The code already has fallback logic (name ?? skillDirName, description ?? firstBodyLine) that is currently unreachable because of the early throw.

I have a branch ready with both changes if the maintainers agree with the approach.