write-a-skill
Creates reusable SKILL.md-based agent skills through requirements, drafting, and user review; use to formalize a workflow or add a new agent capability.
How do I install this agent skill?
npx skills add https://github.com/akillness/jeo-skills --skill write-a-skillIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill acts as a documentation assistant to help users formalize agent workflows into structured files. It does not contain any malicious code, external downloads from untrusted sources, or data exfiltration patterns.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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 contentEXAMPLES.md— concrete examplesscripts/— 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/akillness/jeo-skills/write-a-skill">View write-a-skill on skillZs</a>