🦾 Skill MD

Executive Summary

Skill MD files (SKILL.md) are the core mechanism for teaching our AI agents (and human operators) how to perform specific procedures within the Funday repository. They condense complex operational knowledge into strict, actionable heuristics. This page defines the standard structure, tone, and constraints for writing highly effective skill documentation.

When to use / When NOT to use

Use When:

• Codifying a recurring, complex procedure (e.g., deploying a service, auditing a game).
• Distilling lessons learned from a difficult debugging session into a reusable pattern.
• Documenting strict rules for editing specific types of files (like these very Guru pages).
• Creating content for the .agents/skills/*/SKILL.md pattern.

When NOT to use:

• Writing general user-facing documentation or tutorials.
• Documenting API endpoints or class definitions (use standard code comments or API docs).
• Storing ephemeral session logs or scratchpad notes.

Rules

1. Mandatory Structure

Every skill document must follow this exact five-section structure:

1. Executive Summary (or Purpose): A concise explanation of what the skill does and why it exists.
2. When to use / When NOT to use: Clear boundary conditions.
3. Rules: The inviolable constraints and heuristics. Use strong modal verbs (MUST, NEVER).
4. Examples: Concrete, fenced code blocks showing the right (and sometimes wrong) way.
5. Failure Modes / Checks: How to verify success and common pitfalls.

2. Actionable Tone

Keep headings short. Write in directives, not suggestions. Instead of “It is recommended to check the logs,” write “Check the logs.”

3. Self-Contained Context

An agent must be able to read the SKILL.md file and apply the skill without needing to traverse multiple other documentation pages to understand the core concepts.

4. File Placement

Skill files should be placed in .agents/skills/<skill-name>/SKILL.md or, when adapted for the wiki, follow the *Guru.md naming convention in the skills/ directory.

Examples

Skill Structure Template

# 🦾 [Skill Name]
 
## Executive Summary
Briefly explain the skill's purpose and value.
 
## When to use / When NOT to use
**Use When:** Scenario A, Scenario B.
**When NOT to use:** Scenario C.
 
## Rules
### 1. [Rule Name]
[Rule Description using MUST/NEVER].
 
## Examples
### [Example Title]
```language
[Code or configuration]
```
 
## Failure Modes / Checks
1. **[Failure Name]**: [How to identify and fix].

Failure Modes / Checks

1. Fluff over Substance: The skill contains paragraphs of exposition but no actual rules or copy-pasteable examples.
2. Ambiguity: Using words like “maybe”, “sometimes”, or “try to” instead of strict heuristics.
3. Missing Validation: No instructions on how an agent can independently verify that they applied the skill correctly.
4. Context Dependency: The skill assumes the agent already knows a specific, undocumented command line tool.

Related Links

• OMP Plugins