orthogonal-sh/skill-creator

Skill Creator

Create modular, self-contained skill packages that extend agent capabilities.

Core Principle: Concise is Key

The context window is shared. Only add what the agent doesn't already know. Challenge every paragraph: "Does this justify its token cost?" Prefer concise examples over verbose explanations.

Skill Structure

skill-name/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Optional: executable code (deterministic tasks)
├── references/           # Optional: docs loaded on-demand
└── assets/               # Optional: files used in output (templates, images)

SKILL.md Format

---
name: skill-name
description: What it does + when to use it. This is the trigger mechanism.
---

# Skill Name

[Instructions for using the skill]

Frontmatter Rules

• name: lowercase, hyphens, under 64 chars (e.g., pdf-editor, gh-review-pr)
• description: Include BOTH what it does AND when to trigger. The body isn't loaded until after triggering, so all "when to use" info must be here.

Degrees of Freedom

Match specificity to task fragility:

| Freedom | Use When | Format | |---------|----------|--------| | High | Multiple valid approaches | Text instructions | | Medium | Preferred pattern exists | Pseudocode, parameterized scripts | | Low | Fragile/error-prone ops | Specific scripts, few params |

Creation Process

1. Understand - Gather concrete usage examples
2. Plan - Identify reusable scripts, references, assets
3. Initialize - Run orth skills init <name>
4. Implement - Write SKILL.md, add resources
5. Submit - Run orth skills submit <path>
6. Iterate - Test on real tasks, refine

Quick Start

# Create new skill
orth skills init my-skill

# Or with path
orth skills init my-skill --path ~/.openclaw/skills

# Submit to Orthogonal
orth skills submit ./my-skill

# Update existing skill
orth skills update <slug> ./my-skill

What NOT to Include

• README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
• Setup/testing procedures
• User-facing documentation
• Anything not needed for the agent to do the job

Progressive Disclosure

Keep SKILL.md under 500 lines. Split into reference files when approaching this limit.

Pattern: High-level guide with references

## Quick start
[Core workflow here]

## Advanced
- **Complex feature**: See references/feature.md
- **API details**: See references/api.md

Pattern: Domain organization

bigquery-skill/
├── SKILL.md (overview + navigation)
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md

Agent loads only the relevant reference file.