# Skill Create > Create a new personal skill in dfrysinger/skills, enforcing HARDLINE authoring standards (frontmatter, naming, structure, size caps). Use when the user says "make this a skill", "create a skill for X", or when an agent recognizes a reusable procedure worth saving (per the auto-create trigger in copilot-instructions.md). For modifying an existing skill, use /skill-manage instead. Use when this capability is needed. - Skill: `tomevault-io/skill-create` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/skill-create` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/skill-create/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/skill-create --- > **Paths note:** All `~/code/skills/...` references below default to the public repo path; override via `$SKILLS_REPO_ROOT`. Same for `~/.copilot/skills/` (override `$SKILLS_LOCAL_ROOT`) and `~/.copilot/skill-state/skill-review/` (override `$SKILLS_STATE_DIR`). See the repo README "Forking and portability" section. # skill-create ## When to use - The user says "make this a skill", "create a skill for X", or similar. - You (the agent) just solved a non-trivial task with reusable steps and the user confirms it should become a skill. - You're following the auto-create trigger in `$HOME/.copilot/copilot-instructions.md` (see `## Skill self-learning`). Do **not** invoke this for one-off tasks, throwaway scripts, or facts that belong in memory (`store_memory`) rather than a reusable procedure. ## Two-root skill layout (where new skills go) There are two roots, with different authority: - **LOCAL native root** `~/.copilot/skills//` — agent-managed, mutable. Loaded directly by Copilot CLI (no plugin, no registry). It is a local git repo with NO remote (commits are reversible; nothing is ever pushed). This is the default home for new agent-created skills and for any skill the user is fine keeping personal/local. - **PUBLIC plugin repo** `~/code/skills/skills//` — curated, shared via the `dfrysinger/skills` plugin. Loads via `.claude-plugin/plugin.json` `.skills[]` (explicit allowlist). Use this only for skills the user wants published. The autonomous skill-review daemon never writes here. Layout is **flat**: `//SKILL.md`. No category subdirectories. Pick one short kebab-case name; class-level umbrella, not session-specific. If the user is ambiguous about where the skill should live, default to LOCAL. A user can later promote local→public with `skill-manage/scripts/promote-skill.sh`. ## HARDLINE authoring standards (non-negotiable) Lifted from Hermes Agent's `AGENTS.md` — these are the rules every skill must meet. The skill is **not done** until all eight pass. 1. **Description ≤ 1024 characters, includes "Use when…"** Frontmatter `description:` is the only thing the agent sees when picking a skill. State the capability in plain language, then a second sentence with concrete triggers. No marketing words ("powerful", "comprehensive", "seamless"). Don't repeat the skill name. Verify: ```bash awk '/^description:/{gsub(/^description: */,""); print length}' SKILL.md ``` 2. **Tools referenced in prose must be the ones Copilot CLI actually exposes.** Use names like `view`, `edit`, `create`, `grep`, `glob`, `bash`, `task`, `manage_schedule`, `web_fetch`, `ask_user`, `report_intent`. Do **not** name shell utilities the agent already has wrapped — `grep` → `grep` tool, `cat`/`head`/`tail` → `view`, `find`/`ls` → `glob`. Third-party CLIs are fair game inside `scripts/` but should not be the headline interaction surface. 3. **Platform gating.** Skills using macOS-only primitives (`security`, `osascript`, `launchctl`, `/Users/...` hardcoded paths, `pbcopy`) must say so in the SKILL.md `## Prerequisites` section. Default posture: try cross-platform first (Python `pathlib`, `tempfile.gettempdir()`, etc.); gate only when the dependency is genuinely OS-bound. 4. **Modern section order in SKILL.md body.** `# ` title, 1-3 sentence intro stating what it does (and what it does NOT do), then: - `## When to use` — concrete trigger conditions - `## Prerequisites` — required env vars, tools, files (if any) - `## Quick start` — minimal working invocation - `## Workflow` / `## Procedure` — step-by-step - `## Pitfalls` — known failure modes (optional but encouraged) - `## Verification` — how to confirm it worked (optional) Target ≤100 lines for simple skills, ≤200 for complex. Cut intro fluff, marketing prose, and re-explanations of env vars already in `## Prerequisites`. 5. **Scripts go in `scripts/`, references in `references/`, templates in `templates/`.** Don't expect the model to inline-write parsers or non-trivial logic every call — ship a helper script. Reference it from SKILL.md by path relative to the skill directory. 6. **Frontmatter shape.** ```yaml --- name: # lowercase, regex ^[a-z0-9][a-z0-9._-]*$, ≤64 chars description: <≤1024 chars, two sentences ending with "Use when…"> --- ``` Optional: `version`, `author`, `license`, `platforms: [macos]`. 7. **Name is filesystem-safe and globally distinct across BOTH roots.** Slug regex `^[a-z0-9][a-z0-9._-]*$`. Check for collisions everywhere: ```bash grep -lr "^name: $" \ ~/code/skills/skills/ ~/.copilot/skills/ \ ~/.copilot/installed-plugins/ 2>/dev/null ``` 8. **Size caps.** SKILL.md body ≤ 100k characters (~36k tokens). Individual supporting files ≤ 1 MiB. If you're over, split into `references/`. ## Procedure (LOCAL root — the default) This is the path the autonomous daemon uses and the right default for any new agent-created skill. NO git push, NO plugin.json registration. 1. **Gather** (use `ask_user` if anything is missing; never multiple-choice for @dfrysinger): - Skill `name` (kebab-case) - One-sentence what-it-does + one-sentence "Use when…" - Whether it needs scripts (deterministic ops) or references (long docs) 2. **Pre-flight collision check across BOTH roots:** ```bash ls -d ~/code/skills/skills/ ~/.copilot/skills/ 2>/dev/null \ && echo "COLLISION" ``` If collision, ask the user to pick a different name or confirm overwrite. Also run `~/code/skills/skills/skill-review/scripts/check-tombstone.sh ` — exit 0 means a curator tombstone exists and you must NOT recreate it. 3. **Create the directory:** ```bash mkdir -p ~/.copilot/skills//{scripts,references} ``` Only create the subdirs you'll actually populate. 4. **Author SKILL.md** following the modern section order (rule 4). 5. **Validate.** ```bash ~/code/skills/skills/skill-manage/scripts/validate-skill.sh \ ~/.copilot/skills//SKILL.md ``` 6. **Test scripts.** Sanity-run anything in `scripts/` to confirm it executes. 7. **Mark provenance** (only when this skill was created autonomously, not by hand): ```bash ~/code/skills/skills/skill-review/scripts/mark-agent-created.sh \ ``` 8. **Commit in the LOCAL repo only:** ```bash cd ~/.copilot/skills git add / git commit -m "skills/: Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" ``` There is no remote — nothing is pushed. 9. **Tell the user how to activate it:** - Run `/skills reload` in any open Copilot CLI session, or restart. - The skill loads automatically as `/` (native personal skill — no plugin entry needed). ## Procedure (PUBLIC repo — when the user asks for a shareable skill) Use only when the user explicitly wants the skill shared via the plugin. Do NOT default to this path for autonomous creation. 1. Steps 1–6 same as above, but with `~/code/skills/skills//` as the target dir. Skip step 7 (no `.agent-created` marker on a curated skill). 2. **Register the skill in `.claude-plugin/plugin.json`** (REQUIRED — skills are an explicit allowlist; an unlisted dir is silently ignored): ```bash ~/code/skills/skills/skill-manage/scripts/registry.sh register ``` 3. **Commit and push** the public repo: ```bash cd ~/code/skills git add skills// .claude-plugin/plugin.json git commit -m "skills/: Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" git push origin main ``` 4. **Refresh the plugin cache** so the new skill loads: ```bash git -C ~/.copilot/installed-plugins/_direct/dfrysinger--skills pull --ff-only ``` Then `/restart` (or `/skills reload` is not enough for plugin changes). If the skill already exists in the LOCAL root and you just want to publish it, use `~/code/skills/skills/skill-manage/scripts/promote-skill.sh ` instead — it moves, strips provenance, registers, and commits both repos. ## Pitfalls - **Forgetting that LOCAL and PUBLIC have different rules.** Local skills need no `plugin.json` entry and never get pushed. Public skills require registration and a plugin-cache refresh. Don't apply the public workflow to a local skill (you'll fail at `git push` since there's no remote). - **Description that doesn't trigger.** If your description doesn't include concrete keywords for when to load the skill, the agent will never pick it. Re-read rule 1. - **Skill that duplicates an existing capability.** Before creating, glob `~/code/skills/skills/**/SKILL.md` AND `~/.copilot/skills/**/SKILL.md` for overlap. Better to extend an existing skill via `skill-manage patch` than to create a near-duplicate. - **Auto-create spam.** The auto-create trigger in `copilot-instructions.md` is a *proposal* (Tier 1) or contained autonomous (Tier 2 daemon). The bar is: "would I want to invoke this same procedure again next month?" - **Vendoring third-party skills.** When importing externally-authored skills, copy them verbatim, pin the source commit, preserve the license, and add a `NOTICE.md` (see `~/code/skills/skills/NOTICE.md` for the existing example). ## Verification After completing the procedure, the new skill should: 1. Exist at `~/.copilot/skills//SKILL.md` (LOCAL) or `~/code/skills/skills//SKILL.md` (PUBLIC) 2. Pass `validate-skill.sh` with zero errors 3. For PUBLIC only: be listed in `.claude-plugin/plugin.json` `.skills[]` 4. Be committed in its owning repo 5. Appear as `/` after `/skills reload` (LOCAL) or `/restart` after plugin cache refresh (PUBLIC) If any of these fail, the skill is not done — fix and re-validate. --- > Source: [dfrysinger/skills](https://github.com/dfrysinger/skills) — distributed by [TomeVault](https://tomevault.io).