write-a-skill

Write a Skill

Create structured agent skills with proper documentation.

Upstream status

Superseded upstream by writing-for-agents. Kept here because find-skills, upskill, solo-skills, and openocta route to it.

When to use this skill

• Formalizing a workflow into a reusable, shareable skill
• Building new agent capabilities from scratch
• Documenting existing patterns so agents can discover and use them

Critical design principle

The description field is the only thing your agent sees when deciding which skill to load.

Write descriptions that:

• Clearly state what the skill does
• Include specific triggers: "Use when [context]"
• Have a 1024-character maximum
• Are precise enough that the agent knows whether to activate

Process

Phase 1 — Gather requirements

Understand:

• What task or workflow does this skill formalize?
• What are the trigger conditions (when should an agent activate this)?
• What are the boundaries (what does this skill NOT do)?
• What platforms should this work on?
• Does this overlap with existing skills?

Phase 2 — Draft the skill

Create SKILL.md as the core file. Keep it under 100 lines.

Split into additional files when:

• SKILL.md exceeds ~100 lines
• Content covers distinct domains users won't always need
• Examples would clutter the core instructions

Supported supporting files:

• REFERENCE.md — detailed reference content
• EXAMPLES.md — concrete examples
• scripts/ — deterministic utility scripts

Phase 3 — Review with user

Present the draft. Validate:

• Description accurately triggers on the right requests?
• Instructions are clear and complete?
• Boundaries prevent misuse?
• Supporting files are needed or is SKILL.md sufficient?

SKILL.md template (jeo-skills format)

---
name: skill-name
description: >
  One-paragraph description of what this skill does and when to use it.
  Include trigger conditions: "Use when [specific context]."
allowed-tools: Read Grep Glob Bash Write Edit
compatibility: >
  Platform and context compatibility notes. What it pairs with.
metadata:
  tags: tag1, tag2, tag3, tag4
  platforms: Claude, ChatGPT, Gemini, Codex
  version: "1.0"
  source: your-github/repo
---

# Skill Name

Brief intro paragraph.

## When to use this skill

- Condition 1
- Condition 2

## When not to use this skill

- Route-out 1 → use `other-skill`
- Route-out 2 → use `other-skill`

## Instructions

[Core instructions here]

Quality checklist

• Description is under 1024 characters
• Description includes "Use when [context]" trigger language
• SKILL.md is under 100 lines (or has justified split)
• When-not-to-use routes out to specific skills
• metadata.tags covers discoverable keywords
• No implementation details in the description (that's what the body is for)

Examples

• Example: Apply this skill to a small scope first, then scale to full scope after validation passes.

Best practices

• Keep outputs deterministic and auditable.
• Prefer small reversible changes over broad risky edits.
• Record assumptions explicitly.

References

• Project standards: .agent-skills/skill-standardization/SKILL.md
• Validator script: .agent-skills/skill-standardization/scripts/validate_skill.sh