About

Imported from akillness/jeo-skills (.agent-skills/write-a-skill/SKILL.md). Install upstream with npx skills add akillness/jeo-skills --skill write-a-skill. Copyright stays with the author.

Write a Skill

Name: write-a-skill
Author: akillness

Create structured agent skills with proper documentation.

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

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/akillness-jeo-skills-write-a-skill/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

akillness-jeo-skills-write-a-skill.ocm.jsonjson

{
  "ocm": "1",
  "id": "akillness-jeo-skills-write-a-skill",
  "kind": "skill",
  "name": "write-a-skill",
  "description": "Creates reusable SKILL.md-based agent skills through requirements, drafting, and user review; use to formalize a workflow or add a new agent capability.",
  "publisher": "akillness",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "skill-creation",
      "agent-skills",
      "documentation",
      "reusability",
      "skill-design",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Creates reusable SKILL.md-based agent skills through requirements, drafting, and user review; use to formalize a workflow or add a new agent capability."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/akillness/jeo-skills",
      "path": ".agent-skills/write-a-skill/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/akillness/jeo-skills/blob/HEAD/.agent-skills/write-a-skill/SKILL.md",
      "key": "akillness/jeo-skills/.agent-skills/write-a-skill/SKILL.md"
    },
    "compatibility": "Universal — creates skills compatible with Claude Code, Codex, Gemini CLI, and other agent platforms. The description field is the most critical element as it is what agents see when deciding to activ",
    "allowed_tools": [
      "Read",
      "Grep",
      "Glob",
      "Bash",
      "Write",
      "Edit"
    ]
  },
  "instructions": "# Write a Skill\n\nCreate structured agent skills with proper documentation.\n\n## When to use this skill\n\n- Formalizing a workflow into a reusable, shareable skill\n- Building new agent capabilities from scratch\n- Documenting existing patterns so agents can discover and use them\n\n## Critical design principle\n\n> The description field is the only thing your agent sees when deciding which skill to load.\n\nWrite descriptions that:\n- Clearly state what the skill does\n- Include specific triggers: \"Use when [context]\"\n- Have a 1024-character maximum\n- Are precise enough that the agent knows whether to act",
  "cost": {
    "context_tokens": 779
  }
}

Fetch it by URL: GET /api/v1/registry/akillness-jeo-skills-write-a-skill/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.