Skill Authoring

Create skills that change agent behavior without repeating system guidance or loading a large playbook on every matching turn. Keep skills portable by separating shared behavior from harness-specific adapters.

When to Use

• Creating or editing non-project SKILL.md files under ~/.agents/skills/.
• Reviewing a skill for trigger quality, duplication, or token waste.
• Porting a skill between agent harnesses.

Do not use this for ordinary Markdown documentation, one-off task notes, or company-owned skills under ~/.agents/skills/projects/.

Ownership and placement

• Non-project directories under ~/.agents/skills/ are the open-source/private skill source tree; edit them directly with write or edit, preserving their category and existing conventions.
• ~/.agents/skills/projects/ is company-owned and remains a direct child of the skills root. Never create, edit, delete, or reformat files there from this skill.
• Shared skills may live under category directories such as core/, planning/, or operations/; category paths are organizational, not aliases. Preserve one canonical directory per skill and update references after moves.
• skill_manage creates skills in its managed store; it is not a substitute for editing this repository source tree.
• Before editing, read applicable AGENTS.md files and the target skill body.

Procedure

1. Check for an existing skill. Search by trigger, name, and behavior. Extend the closest skill instead of creating a duplicate. Done when one owner for the behavior is identified.
2. Define the trigger. State what user request activates the skill and what distinctive behavior it adds. Put the trigger in the first sentence of the description. Done when a non-matching request is easy to name.
3. Write valid frontmatter. Start at byte 0 with ---; include name and description; close with --- before a non-empty body. Use lowercase, hyphenated names and keep names ≤64 characters.
4. Write the smallest useful body. Keep always-needed rules in SKILL.md. Include actionable steps, relevant tool names, failure boundaries, and checkable completion criteria. Cut generic advice and duplicated system rules.
5. Progressively disclose detail. Move branch-specific commands, long examples, and reference material to references/, templates/, or scripts/; link them from the body and load them only when that branch is active.
6. Port carefully. Replace source-framework paths, tools, hooks, and APIs with capabilities that exist here. Never copy instructions that silently invoke unavailable tools or mutate unrelated state.
7. Validate. Run the checks below. Done means frontmatter parses, metadata is discoverable, no duplicate name exists, and the changed file is accounted for.

Low-token rules

• Description: one trigger-focused sentence; aim for ≤200 characters. The first 57 characters should still identify when to use the skill.
• Body: aim for ≤6,000 characters for a workflow skill; split larger branches instead of making every invocation pay for them.
• Prefer one strong rule over several paraphrases. Keep a pitfall only when it prevents a recurring failure.
• Avoid tool catalogs, generic "best practices," long rationale, and examples that do not change decisions.
• End ordered steps with observable completion criteria; this prevents premature completion more cheaply than extra prose.

Compact shape

# Skill title

## Overview
What behavior this skill makes reliable.

## When to Use
Triggers and counter-triggers.

## Procedure
Numbered actions with completion criteria.

## Pitfalls
Only recurring, concrete failures.

## Verification
Smallest checks that prove the skill is valid and its work is complete.

Validation

For a repository skill, run:

python3 - <<'PY'
from pathlib import Path
import re

p = Path("~/.agents/skills/<category>/<name>/SKILL.md").expanduser()
s = p.read_text()
assert s.startswith("---\n")
match = re.search(r"\n---\n", s[4:])
assert match, "unterminated frontmatter"
frontmatter = s[4:match.start() + 4]
assert re.search(r"^name:\s*[^\n]+$", frontmatter, re.M)
assert re.search(r"^description:\s*[^\n]+$", frontmatter, re.M)
assert len(s) <= 100_000
print(f"valid: {p} ({len(s)} chars)")
PY
python3 ~/.agents/skills/core/skill-orchestration/scripts/discover_skills.py \
  --root ~/.agents/skills --check

Also inspect the diff and confirm no unrelated skill or generated file changed.

Pitfalls

1. A managed skill store is separate from this source tree; edit repository files in place.
2. A copied skill can contain valid Markdown but invalid local tool names, paths, hooks, or delegation APIs.
3. A generic or late trigger makes the skill expensive and easy to misroute.
4. Adding detail without deleting replaced wording creates skill sediment.
5. A large body is not thoroughness; branch-specific detail belongs behind a reference link.

Verification checklist

• Existing skill ownership checked; no duplicate behavior added.
• Trigger is precise and front-loaded in description.
• Frontmatter starts at byte 0 and has required fields.
• Body is concise, actionable, and locally compatible.
• Branch-specific detail is progressively disclosed.
• Repository validation and discovery checks pass.
• Diff contains only intended skill changes.