orthogonal-skill-creator

# Skill Creator

## Setup

Read your credentials from ~/.gooseworks/credentials.json:
```bash
export GOOSEWORKS_API_KEY=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json'))['api_key'])")
export GOOSEWORKS_API_BASE=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json')).get('api_base','https://api.gooseworks.ai'))")
```

If ~/.gooseworks/credentials.json does not exist, tell the user to run: `npx gooseworks login`

All endpoints use Bearer auth: `-H "Authorization: Bearer $GOOSEWORKS_API_KEY"`


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

```markdown
---
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

```bash
# 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**
```markdown
## 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.