Skill CreatorSAFE

Open-source super AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: skill-creator
description: Create, install, or update skills in the workspace. Use when (1) installing a skill from a URL or remote source, (2) creating a new skill from scratch, (3) updating or restructuring existing skills. Always use this skill for any skill installation or creation task.
license: Complete terms in LICENSE.txt
---

# Skill Creator

This skill provides guidance for creating effective skills using the existing tool system.

## About Skills

Skills are modular, self-contained packages that extend the agent's capabilities by providing specialized knowledge, workflows, and tools. They transform a general-purpose agent into a specialized agent equipped with procedural knowledge.

### What Skills Provide

1. **Specialized workflows** - Multi-step procedures for specific domains
2. **Tool integrations** - Instructions for working with specific file formats or APIs
3. **Domain expertise** - Company-specific knowledge, schemas, business logic
4. **Bundled resources** - Scripts, references, and assets for complex tasks

### Core Principle

**Concise is Key**: Only add context the agent doesn't already have. Challenge each piece of information: "Does this justify its token cost?" Prefer concise examples over verbose explanations.

## Skill Structure

Every skill consists of a required SKILL.md file and optional bundled resources:

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)
```

### SKILL.md Components

**Frontmatter (YAML)** - Required fields:

- **name**: Skill name in hyphen-case (e.g., `weather-api`, `pdf-editor`)
- **description**: **CRITICAL** - Primary triggering mechanism
  - Must clearly describe what the skill does
  - Must explicitly state when to use it
  - Include specific trigger scenarios and keywords
  - All "when to use" info goes here, NOT in body
  - Example: `"PDF document processing with rotation, merging, splitting, and text extraction. Use when user needs to: (1) Rotate PDF pages, (2) Merge multiple PDFs, (3) Split PDF files, (4) Extract text from PDFs."`

**Body (Markdown)** - Loaded after skill triggers:

- Detailed usage instructions
- How to call scripts and read references
- Examples and best practices
- Use imperative/infinitive form ("Use X to do Y")

### Bundled Resources

**scripts/** - When to include:
- Code is repeatedly rewritten
- Deterministic execution needed (avoid LLM randomness)
- Examples: PDF rotation, image processing
- Must test scripts before including

**references/** - When to include:
- **ONLY** when documentation is too large for SKILL.md (>500 lines)
- Database schemas, complex API specs that agent needs to reference
- Agent reads these files into context as needed
- **NOT for**: API reference docs, usage examples, tutorials (put in SKILL.md instead)
- **Rule of thumb**: If it fits in SKILL.md, don't create a separate reference file

**assets/** - When to include:
- Files used in output (not loaded to context)
- Templates, icons, boilerplate code
- Copied or modified in final output

**Important**: Most skills don't need all three. Choose based on actual needs.

### What NOT to Include

Do NOT create auxiliary documentation files:
- README.md - Instructions belong in SKILL.md
- INSTALLATION_GUIDE.md - Setup info belongs in SKILL.md
- CHANGELOG.md - Not needed for local skills
- API_REFERENCE.md - Put API docs directly in SKILL.md
- USAGE_EXAMPLES.md - Put examples directly in SKILL.md
- Any other documentation files - Everything goes in SKILL.md unless it's too large

**Critical Rule**: Only create files that the agent will actually execute (scripts) or that are too large for SKILL.md (references). Documentation, examples, and guides ALL belong in SKILL.md.

## Installing a Skill

Install target directory: `<workspace>/skills/<name>/` (the `<workspace>` is from the "Workspace" section).

### Step 1 — Obtain skill content

| Source | Action |
|---|---|
| URL (single file) | Fetch content via curl or web_fetch |
| URL (zip/archive) | Download and extract to a temp directory |
| Local file (SKILL.md) | Read directly |
| Local archive (zip) | Extract to a temp directory |

### Step 2 — Identify and install

1. Locate the SKILL.md (may be at top level or inside a subdirectory)
2. Extract `name` from YAML frontmatter
3. Copy the **entire skill directory** (SKILL.md and all sibling files/folders such as `references/`, `scripts/`, `assets/`, etc.) into `<workspace>/skills/<name>/`
4. If an install/setup file exists (e.g. INSTALL.md), follow its instructions — the final result must still end up in `<workspace>/skills/<name>/`

## Skill Creation Process (from scratch)

1. **Understand** - Clarify use cases with concrete examples
2. **Plan** - Identify needed scripts, references, assets
3. **Initialize** - Run init_skill.py to create template
4. **Edit** - Implement SKILL.md and resources
5. **Validate** (optional) - Run quick_validate.py to check format
6. **Iterate** - Improve based on real usage

## Skill Naming

- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
- When generating names, generate a name under 64 characters (letters, digits, hyphens).
- Prefer short, verb-led phrases that describe the action.
- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).
- Name the skill folder exactly after the skill name.

## Step-by-Step Guide

### Step 1: Understanding the Skill with Concrete Examples

Skip this step only when the skill's usage patterns are already clearly understood. It re

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.