Best Practices

Write effective, focused skills that agents follow consistently

Writing Effective Instructions

The quality of your skill depends on how clearly you communicate with the AI agent. Agents process your instructions literally — vague guidance produces inconsistent results.

Be Specific

# BAD — too vague
Write good tests.

# GOOD — concrete and actionable
When writing tests:
- Use descriptive names: test_<function>_<scenario>_<expected>
- Follow Arrange-Act-Assert pattern
- Mock external dependencies at the boundary
- Assert specific values, not just truthiness

Show Before/After Examples

Agents learn patterns best from concrete examples. Show the transformation you want:

## Input
```typescript
function getUser(id: any) {
  return db.query("SELECT * FROM users WHERE id = " + id);
}
```

## Expected output
```typescript
async function getUser(id: string): Promise<User | null> {
  const [user] = await db.query<User>(
    "SELECT * FROM users WHERE id = $1",
    [id]
  );
  return user ?? null;
}
```

Structure with Headers

Break your skill into logical sections using markdown headers. This helps both agents and human readers navigate the content.

# Skill Name

Brief overview — when and why to use this skill.

## Guidelines

Ordered rules the agent should follow.

## Examples

Concrete before/after code samples.

## Edge Cases

Special situations and how to handle them.

## Common Mistakes

Patterns to avoid and why.

Scope and Focus

One skill should do one thing well. A skill that tries to handle code review, testing, and documentation all at once will be inconsistent at all three.

Good skill scope examples:

• Focused: "Write unit tests for React components using Testing Library"
• Focused: "Review Python code for security vulnerabilities"
• Too broad: "Full-stack development helper"
• Too broad: "Do everything related to testing and deployment"

Naming and Metadata

Good metadata makes your skill discoverable:

• Name — Use lowercase, hyphenated identifiers (code-review, not Code Review Helper v2). Keep it short and descriptive.
• Description — One clear sentence. This shows in search results. Start with a verb: "Generate...", "Review...", "Convert...".
• Tags — Use common, lowercase terms. Check what tags existing skills use and reuse them for consistency.
• Version — Follow semver. Bump patch for wording fixes, minor for new sections, major for complete rewrites.

Agent Compatibility

Skills work across multiple agents, but each agent has different capabilities. Keep these differences in mind:

• Claude Code — Installs skills to ~/.claude/skills/. Supports all tool types. Best for complex multi-step workflows.
• Cursor — Uses .cursor/rules/. Works well with file-focused instructions.
• Codex — Uses .codex/ directory. Good for code generation tasks.

Testing Your Skill

Before publishing, test your skill thoroughly:

1. Validate the format — Run osk validate ./my-skill to catch frontmatter issues.
2. Install locally — Use osk install ./my-skill and try it with your agent on real tasks.
3. Run the audit — Use the audit page to check for security issues.
4. Test edge cases — Try your skill with unusual inputs or unexpected project structures to see how the agent handles them.
5. Get feedback — Share with a colleague and see if the agent produces consistent, useful output.

Common Pitfalls

• Too much context — Agents have limited context windows. Keep your skill concise and focused. Long skills dilute the important instructions.
• Conflicting instructions — "Always add comments" followed by "keep code minimal" creates confusion. Be consistent.
• Hardcoded paths — Avoid /Users/me/projects/.... Use relative paths or let the agent discover the project structure.
• Assuming environment — Don't assume specific tools, versions, or OS. Make prerequisites explicit in the description.