docs(agent-skills): document skill directories, entry files, and frontmatter

[tembo]

What changed

Rewrote the How it works section of features/agent-skills.mdx so it matches how Tembo actually discovers repository skills. The previous page told readers to "place skills in the dotfile directory" (.claude/, .codex/, .opencode/, .cursor/) with no mention of the required skills/<name>/ structure, entry filenames, or frontmatter — and its example SKILL.md had no frontmatter, so Tembo would silently skip it.

Docs added/updated

• Harness → skill directory table covering all six supported harnesses, including the previously undocumented .agents/skills location (used by Pi and Amp) and Cursor's .cursor/rules/<name>/SKILL.mdc.
• Skill file format section documenting the required YAML frontmatter and the constraints Tembo enforces: description required (≤1024 chars); name required in SKILL.md, must match the directory name, lowercase kebab-case, ≤64 chars; Cursor .mdc derives the name from the directory; entry file must be UTF-8 text under 1 MB or it is skipped.
• Fixed both example snippets to include valid frontmatter and a concrete file path.

Codepaths covered

• apps/api/src/agent/worker/skills.ts — getRepositorySkillEntry (path/regex for .agents|.codex|.claude|.opencode/skills/<name>/SKILL.md and .cursor/rules/<name>/SKILL.mdc) and parseSkillFrontmatter (name/description validation, kebab-case, length limits, 1 MB / binary guard).
• apps/api/src/agent/runtime/harness/*/definition.ts and .../harness/*/cli.ts — per-harness skillDir / entryFilename mappings for Claude Code, Codex, OpenCode, Cursor, Amp, and Pi.

Key knowledge gaps addressed

• The .agents/skills agent-agnostic location was entirely absent from the docs.
• Readers had no way to know skills need a skills/<name>/SKILL.md layout, that Cursor uses .cursor/rules with a .mdc entry file, or that frontmatter (name/description) is mandatory — the most common reasons a skill silently fails to load.

Verification & scope

• Every claim was verified against the source above; nothing was inferred.
• I also reviewed features/rule-files.mdx, which lists a rule-file precedence order, but found no in-repo resolver for those filenames (discovery is delegated to each harness). Evidence was inconclusive, so I left that page untouched rather than risk introducing an inaccuracy — keeping this a clean, focused, docs-only PR.
• No conflicts with main.

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

---

Note

Low Risk
Documentation-only changes to agent-skills guidance; no runtime or security impact.

Overview
How it works in features/agent-skills.mdx now describes skills as skills/<name>/ directories with a YAML frontmatter entry file, instead of vague “dotfile directory” guidance.

It adds a harness → directory → entry file table (including .agents/skills for Pi/Amp and Cursor’s .cursor/rules + SKILL.mdc), documents required frontmatter and validation (description, name rules for SKILL.md, Cursor naming, size/UTF-8 limits and silent skip), and updates the code-review and implementation examples with valid frontmatter and concrete paths.

^{Reviewed by Cursor Bugbot for commit 20effa4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[tembo]

Requesting review from @benja who has experience with the following files modified in this PR:

• features/agent-skills.mdx

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tembo	🟢 Ready	View Preview	Jul 24, 2026, 8:11 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tembo	🟡 Building	–	Jul 24, 2026, 8:10 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.