Agent skills

Give Froe reusable instructions for the work you do often.

A skill starts here .agents/skills/test-review/SKILL.md

Start with one file.

Create .agents/skills/test-review/SKILL.md in your Workspace and copy the example below. No package installation or registration step is needed.

SKILL.md — complete example

---
name: test-review
description: Review automated tests for missing behavior coverage, brittle assertions, and failure cases. Use when the user asks to review tests or assess a test plan.
---

# Test review

1. Read the project instructions and test configuration.
2. Identify the behavior the changed code promises.
3. Read the relevant tests and compare them with that behavior.
4. Look for missing failure cases and assertions tied to internals.
5. Run the relevant tests using the project's existing tooling.

Report findings with file paths, the uncovered behavior, and a
concrete suggested test. If tests cannot run, explain why.
Do not edit files unless the user asks for changes.

name: Required. Use 1–64 lowercase letters, digits, or hyphens, with no leading, trailing, or consecutive hyphens. Match the directory name to the skill name for clarity.
description: Required, non-empty, and at most 1,024 characters. Explain what the skill does and when to use it. Froe shows this description to the model before it reads the instructions.
Markdown body: Write concrete steps, expected outputs, verification, and what to do if a prerequisite is missing. Keep the main workflow concise; point to supporting files when more detail is needed.
Supporting files: Optionally add references/, scripts/, or assets/ inside the skill directory. Reference them relative to SKILL.md, for example references/testing.md. They are not automatically loaded or executed.
Optional frontmatter: Froe also parses license, compatibility (up to 500 characters), metadata, and allowed-tools. These fields are not included in its skill summary. allowed-tools is parsed metadata, not an enforced tool allowlist or a grant of permission.

Put skills where Froe looks.

Froe discovers skills when a session starts. It scans immediate, non-hidden skill directories inside each root, reads their frontmatter, and keeps the first valid skill with each name.

Workspace roots: Scanned first, in this order: .agents/skills, .froe/skills, .claude/skills, .codex/skills, .cursor/skills, and .github/skills.
Additional directories: Directories authorized with --add-dir are scanned next, using the same six subdirectories. They take precedence over user skills.
User roots: Scanned last: ~/.agents/skills, ~/.froe/skills, ~/.claude/skills, ~/.codex/skills, and ~/.cursor/skills. If XDG_CONFIG_HOME is explicitly set and non-empty, Froe also scans $XDG_CONFIG_HOME/froe/skills.
Progressive loading: The model receives each discovered skill’s name, description, and file path. When a task matches the description, it is instructed to read the full SKILL.md with read_file before proceeding.
Access boundaries: Froe adds discovered user skill directories to its additional directories for file access and command sandboxing, including read and write access. Install only skills you trust. Skill instructions and allowed-tools do not remove ordinary approval checks.