Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

skill-creator

Generate a new skill from a plain-language description — decides invocation control, arguments, and context cost, then scaffolds, validates, and tests it

conorbronsdon · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add conorbronsdon/agent-context-os --skill skill-creator

About this skill


name: skill-creator description: Generate a new skill from a plain-language description — decides invocation control, arguments, and context cost, then scaffolds, validates, and tests it x-source: "maintainer-core/skills/skill-creator/SKILL.md" x-source-version: "d66f695"

skill-builder — Skills That Don't Rot

Takes a plain-language description of a task and produces a ready-to-ship agent skill. The design goal is skills that are cheap in ambient context and current with the skill spec — most skill generators fail on exactly those two axes: they don't know about arguments/argument-hint, never suggest disable-model-invocation, and write bloated descriptions that tax every session.

Modes

Parse $ARGUMENTS for a mode; default to new when the input is a description.

  • new <description> — scaffold a skill from scratch (the flow below).
  • review <path> — audit an existing SKILL.md against steps 1–3's decision points and run the validator (step 4). Report findings; don't rewrite unless asked.
  • migrate <path> — convert a legacy .claude/commands/*.md file into a skill directory: carry the frontmatter over, apply the review checklist, and place supporting content in the directory.

Before You Start

Read references/claude-code-frontmatter.md — a pinned, dated snapshot of the skill frontmatter spec, argument substitutions, and context-loading behavior.

Staleness policy: if the snapshot date is more than 3 months old, warn the user and continue with the pinned snapshot. Do not re-fetch or modify the reference mid-generation — updating the spec is a maintenance operation (agent-skill-builder's spec-drift CI watches for it), not a side effect of building a skill. Only update the snapshot when the user explicitly asks.

Also read the host repo's CLAUDE.md and existing skills — avoid duplicating a skill that already exists, and match local conventions.

Instructions

1. Clarify the skill

Ask (or infer from context):

  • Target runtime: Claude Code (default — full frontmatter feature set) or the portable Agent Skills core (name + description only; keep Claude-specific fields out or document them as optional extensions).
  • Name: lowercase, hyphenated. In Claude Code the directory name under .claude/skills/ is the command you type; frontmatter name is only a display label.
  • Who invokes it — the most important design decision:
    • User-only (side effects, or timing the user controls: publish, send, deploy, log) → disable-model-invocation: true. Bonus: the description is then not loaded into every session — zero ambient context cost.
    • Claude-only (background knowledge, not an action) → user-invocable: false.
    • Both (default) → the description must carry the trigger keywords, and it becomes a permanent per-session context cost. Make it earn that.
  • Arguments: does the user pass input on the command line? If yes: set argument-hint, and consume $ARGUMENTS (or $0/$1, or named arguments:) in the body. Don't make the model guess what the trailing text means.
  • Input/Output: what does it read (files, MCP data, live command output), what does it produce?
  • Tools: allowed-tools is a pre-approval grant (no permission prompts while active), not a restriction — scope entries tightly, e.g. Bash(git add *) not Bash. Use disallowed-tools to actually remove tools.
  • Where it runs: inline (default — shares conversation context) or context: fork + agent: for isolated, self-contained tasks. Fork only works when the body is an explicit task, not reference guidelines.
  • Data at load time: use dynamic context injection (!`command` at line start) to inline live data (a diff, a status file) before the model reads the skill.
  • Only set model/effort overrides with a specific reason. Use paths: for skills scoped to certain files.

2. Write the description — the context-budget step

  • 1–2 sentences, key use case first, third person, containing the words the user would actually say. Target ~250 chars; the listing truncates at 1,536.
  • Detail, steps, and edge cases go in the body — the body loads only on invocation, so it's nearly free until used. Never pad the description to be "thorough"; that's the anti-pattern that bloats every session.
  • If disable-model-invocation: true, the model never sees the description — write it for the human scanning the / menu, and keep it short.

3. Draft the SKILL.md

Frontmatter template — include only the fields this skill needs (all are optional; see the reference for the full table):

---
name: [skill-name]
description: [1-2 sentences, triggers first]
argument-hint: "[expected args, e.g. [issue-number] [format]]"   # only if it takes arguments
disable-model-invocation: true    # only for user-triggered workflows
allowed-tools: [tightly-scoped grants]   # only if prompts would be annoying
---

Body structure: short purpose line, "When to Use" bullets, numbered step-by-step instructions, explicit output format.

Quality checklist:

  • Steps, not paragraph prose; each step names the tool or command
  • Output format defined, not left ambiguous
  • Instructions written as standing rules — skill content stays in context for the rest of the session, so "do X once" phrasing goes stale; "always X when Y" doesn't
  • Body under 500 lines; long reference material moved to supporting files in the skill directory, linked from SKILL.md
  • No hardcoded IDs, paths, or credentials — use config files, env vars, or ${CLAUDE_SKILL_DIR} for bundled scripts
  • Confirmation gate on anything that changes external state (git push, API calls, file deletes)

4. Validate

If agent-skill-builder is ava

Read the complete source ↗