Skill Authoring
House conventions for every SKILL.md in the canonical library.
Debian/Linux variant: ../../platforms/linux/skills/skill-authoring/SKILL.md.
Resolve the full library first
Repository scripts and registry files belong to the full library checkout, not
the installed copy of this skill. Use skill-router to locate that library:
standalone installations record it in ~/.config/theprawnskills/library.json;
the existing Windows setup uses the OneDrive root below. Resolve the repository
links in this document against that source checkout. Never look for maintenance
scripts under the host's .codex/scripts or .claude/scripts directories.
If the source checkout is unavailable, report the missing prerequisite and do
not invent a path or overwrite an installed skill to compensate.
Layout & Registry
- Canonical root:
<user-home>\OneDrive\01 SKILLS\.agents\skills - One folder per skill:
skills/<kebab-name>/SKILL.md(folder name =name) - Registry files at
.agentsroot:machines.toml,default-profile.toml,agents.toml,INDEX.md - Installed roots receive ONLY the default profile; canonical holds everything.
- opencode loads skills via the
~/.agentsjunction — never re-copy skills into.config/opencode/skills.
Frontmatter Contract
---
name: kebab-name # required, matches folder, <=64 chars
description: >- # required; WHAT it does + WHEN to trigger,
... # third person, front-load user phrasing/keywords;
# gate with "Use ONLY when..." if narrow
license: MIT
metadata:
author: Local setup
version: "1.0.0"
platform: "Codex, Claude, Cursor, OpenCode on Windows"
---
A weak description = a dead skill (never triggers) or a noisy one (always triggers). Write the trigger phrases users will actually type.
Body Standards
- Open with one-line purpose; then When To Use / When NOT To Use.
- Prefer tables over prose for checklists and field contracts.
- PowerShell examples (this is Windows); no bash-only syntax.
- No comments-as-content, no TODO stubs, no half-finished flows — say what is not supported explicitly.
- Cross-link with backticked skill names only if the target exists.
Windows + OneDrive Rules
- Never write into remote machines' canonical folders directly; OneDrive syncs the shared tree — concurrent writes cause conflict storms.
- Never run propagation while any machine's OneDrive shows pending/error state.
- Secrets never in SKILL.md, scripts/, or registry files.
Change Protocol
- New skill: create folder + SKILL.md, then update INDEX.md (repository index script) and router table if routing changes.
- Default-profile membership changes: edit
default-profile.toml, then run the repository profile installer (WhatIf first). - Deprecate: move folder to
_removed/<date>/, remove router/profile entries, regen INDEX. - Never
dotagents sync;dotagents installonly when agents.toml is known-good.
Quality Bar
Before finishing: frontmatter parses, name=folder, description >=40 chars with trigger words, body has no dangling skill refs, no secrets, INDEX regenerated.
Related Skills
skill-create- scaffold a new local skill through this convention setskill-cleanup,skill-remove- pruning flowsskill-judge- scoring rubric for finished skills
Backup
After any library change, commit and push to the private remote the private remote (see ENVIRONMENT.md at the .agents root for exact commands. OneDrive is transport, not a backup.
Machine-specific values in this document use privacy placeholders.