# 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.

- Skill: `akillness/write-a-skill-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add akillness/write-a-skill-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/akillness/write-a-skill-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: akillness (https://skillmd.com/u/akillness)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/akillness/write-a-skill-2

---


# 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)

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