Skill Maker

Create, Audit, or Consolidate Skills

Create agent skills following the Agent Skills open standard.

What do you need to do?

1. Audit an existing skill — Review, improve, or debug a SKILL.md
2. Create a new skill — Interview, draft, and review from scratch
3. Consolidate skills — Merge multiple skills into fewer

Wait for response before proceeding.

| Response | Workflow | |----------|----------| | 1, "audit", "review", "check", "fix", "improve" | Audit Workflow (Step 1–4 in this file) | | 2, "create", "write", "build", "new", "draft" | Phases 1–5 (Interview → Draft → Description → Scripts → Review) in this file | | 3, "consolidate", "merge", "combine" | references/consolidation-guide.md — return to Phase 5 for final checklist |

Audit Workflow

Use this workflow when reviewing, improving, or debugging an existing skill.

Step 1: Locate and read the skill

Read the full SKILL.md and list all files in the skill directory (references/, scripts/, templates/, assets/).

Step 2: Run the audit checklist

Check each category. Note issues as you go.

Frontmatter:

• [ ] name matches the directory name, lowercase+hyphens, max 64 chars
• [ ] description is under 1024 chars, non-empty, third person
• [ ] description includes trigger phrases (not just a summary of what the skill does)
• [ ] description covers edge phrasings users would actually say

Structure:

• [ ] SKILL.md body is under 500 lines
• [ ] Essential principles are inline in SKILL.md (not only in a reference file)
• [ ] All referenced files exist (check every path in the SKILL.md)
• [ ] References are one level deep (no nested chains: A → B → C)

Content quality:

• [ ] No rigid ALWAYS/NEVER rules without reasoning (explain WHY)
• [ ] No explanations of things the agent already knows from training
• [ ] Steps are specific and verifiable (not "handle errors appropriately")
• [ ] Success criteria are observable and testable
• [ ] Examples use fake data where appropriate

Router pattern (if applicable):

• [ ] Intake question asks what the user wants before routing
• [ ] Router table maps commands to reference files
• [ ] All referenced workflow/reference files exist
• [ ] Essential principles are in SKILL.md, not only in sub-command references
• [ ] If skill has multiple semantic sections, consider XML tags for structure (see references/xml-structure-guide.md)

Scripts (if present):

• [ ] Scripts have shebangs, --help, and structured output
• [ ] No interactive prompts (all input via flags/env/stdin)
• [ ] Cross-platform paths (pathlib, no hardcoded separators)
• [ ] Error messages explain what went wrong and what to do

Read references/anti-patterns.md for the full catalog of common failures.

Step 3: Generate the report

Present findings grouped by severity:

1. Critical — skill won't trigger or produces wrong output
2. Important — structural issues, missing files, spec violations
3. Minor — style, conciseness, optimization opportunities

For each finding, state the issue, cite the specific line or section, and recommend a fix.

Step 4: Offer fixes

Ask the user which findings to fix. Apply changes surgically — don't rewrite sections that aren't broken. Run the Phase 5 review checklist on the modified skill before finishing.

Phase 1: Interview

Interview the user about every aspect of this skill until reaching shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Interview cadence

Ask one question at a time. Wait for the answer before asking the next. Adapt follow-ups based on what you learn. Each question should provide clear benefit toward building a better skill — cut questions the codebase can answer for you.

If a question can be answered by exploring the codebase, explore the codebase instead of asking.

Focus areas, roughly in order:

1. Purpose and audience. What task does this skill cover? What specific problem does it solve? What does the user do today without it?
2. Scope boundaries. What should this skill NOT do? What adjacent tasks belong to other skills?
3. Input/output. What does the user provide? What does the skill produce? Specific formats?
4. Edge cases. What goes wrong? Common mistakes? Gotchas for new users?
5. Success criteria. How do you know the skill worked correctly?
6. What can be scripted? Look for deterministic operations that should be code, not LLM instructions. Scripts are cheaper, faster, and more reliable.
7. References needed? Domain knowledge too large for SKILL.md that should live in separate files?
8. Existing patterns. Similar skills or workflows to draw from? Check the codebase.
9. Platform constraints. macOS, Windows, and Linux? Scripts must handle path separators, temp directories, and shell differences.
10. External services and APIs. Does the skill call external APIs or services? If yes, read references/api-skill-patterns.md — it covers credential handling, schema discovery, instance-specific values, and error placement.

Architecture decision tree

After the interview questions above, decide the architecture. Most skills are simple — only escalate when the answers demand it.

Question 1: How many distinct things can a user want to do?

• One specific thing → Simple skill (single SKILL.md, under 200 lines)
• Multiple things with shared principles → continue to Q2

Question 2: Is there shared domain knowledge across those operations?

• No, each operation is self-contained → Simple skill (or multiple separate simple skills)
• Yes, multiple operations share knowledge → Router skill (SKILL.md + references/)

Question 3: Does it cover a full lifecycle (build, debug, test, ship)?

• No → Router skill is sufficient
• Yes → Domain expertise skill (exhaustive references, full lifecycle workflows)

| What you're building | Pattern | |---|---| | "A skill that commits with a conventional message" | Simple | | "A skill that manages PRs — create, review, merge, close" | Router | | "A skill for building and shipping macOS apps" | Domain expertise | | "A skill that audits other skills" | Simple (upgrade to Router if it grows) |

For Router and Domain expertise patterns, also ask:

• Does the skill need project-level context? If every command needs the same background, design a context file pattern with a loader script.
• Are there mandatory setup gates? Steps that must pass before any work begins. Gates prevent generic output.
• Does behavior vary by task type? If so, design a register/mode system that classifies the task first, then loads different references.

Read references/architecture-patterns.md for implementation details of each pattern.

Consolidation signal check: If the interview reveals the new skill overlaps significantly with existing skills (shared scripts, cross-references, linear pipeline), consider consolidating instead of creating. Read references/consolidation-guide.md for the signals and workflow.

Do not proceed to Phase 2 until the user confirms the scope is complete.

Phase 2: Draft the SKILL.md

Write the skill following the spec. Read references/spec-guide.md for the full format reference before drafting.

Starter templates: Use templates/simple-skill.md for single-purpose skills, templates/router-skill.md for multi-command skills using markdown headings, or templates/router-skill-xml.md for multi-command skills using XML structure. Copy the template as a starting point, then customize.

Frontmatter

---
name: skill-name        # lowercase, hyphens, max 64 chars
description: |           # max 1024 chars — this is the ONLY triggering mechanism
  What the skill does. Use when [specific triggers].
  Also use when [additional triggers].
---

The description must be slightly "pushy" — agents tend to undertrigger. Include both what the skill does AND specific phrases/contexts that should activate it.

Body structure

Follow progressive disclosure — three loading levels:

1. Metadata (~100 tokens): name and description loaded at startup for all skills
2. Instructions (

What would you like to do?

1. Craft a feature — Build end-to-end
2. Audit code — Technical quality checks

Wait for response before proceeding.

| Response | Workflow | |----------|----------| | 1, "craft", "build" | references/craft.md | | 2, "audit", "check" | references/audit.md |

Back the router with a `scripts/command-metadata.json` as the single source of truth:

```json
{
  "craft": {
    "description": "Full build flow. Use when building a new feature end-to-end.",
    "argumentHint": "[feature description]"
  }
}

Setup gates (when applicable)

Non-negotiable checks before any file edits. Gates prevent generic output from missing context.

## Setup (non-optional)

| Gate | Required check | If fail |
|---|---|---|
| Context | Project config loaded via `python scripts/load_context.py` | Run the loader first |
| Config | Config file exists and is valid | Run `skill-name setup` |
| Command | Sub-command reference is loaded | Load the reference |
| Mutation | All gates above pass | Do not edit project files |

Register/mode system (when applicable)

When behavior varies by task type, classify first, then load different references:

## Register

Every task is **library** (published, API-stable) or **application** (internal, can break).
Identify before acting. Load the matching reference: [references/library.md] or [references/application.md].

Capability-gating

Steps that depend on optional environment capabilities (browser automation, specific CLI tools) must degrade gracefully:

### Automated Scan (Capability-Gated)

Run the automated scanner when ALL of these are true:
- The target files exist and are readable
- The required CLI tool is installed

If unavailable, state in one line that the step is skipped and why. Do not ask the user to install tooling.

Structured artifacts as handoffs

When one command produces output that another consumes, define the artifact structure explicitly. The producing command's reference defines the format; the consuming command's reference says what it expects:

### Plan Structure

**1. Summary** (2-3 sentences)
**2. Primary Goal**
**3. Approach**
...

Self-critique loops

For build/implementation commands, mandate inspect-and-fix passes with explicit exit bars:

### Critique and fix loop

After the first pass, write a short self-critique and patch. Repeat until no material issues remain:
1. Does it match the requirements?
2. Does it pass the [quality test]?
3. Check every expected scenario.
4. Check edge cases.

The exit bar is not "it works." It is: [explicit quality threshold].

Phase 3: Description Optimization

The description is the only thing agents see at startup. Read references/description-guide.md for the full optimization process.

Quick validation:

1. Write 5 should-trigger queries (different phrasings, including ones that don't name the skill directly)
2. Write 5 should-not-trigger queries (near-misses that share keywords but need different skills)
3. Check: would the description correctly distinguish these?
4. Revise if needed — broaden for missed triggers, narrow for false triggers
5. Verify under 1024 characters

For skills with sub-commands, the main description covers the skill broadly. Each sub-command's description in command-metadata.json is optimized separately for auto-trigger keyword matching.

Phase 4: Scripts

Read references/scripts-guide.md for the full guide.

Bias toward scripts. Every deterministic operation should be a script, not an instruction. Scripts are cheaper (no LLM tokens), faster (no reasoning), and more reliable (no hallucination).

For each piece of the skill's workflow, ask: "Could a script do this?" If yes, write the script.

Should be scripts:

• Validation (input format, required fields, schema compliance)
• File generation from templates
• Data extraction and transformation
• API calls with structured responses
• Setup and environment checks
• Output formatting
• Context loading (read project files, resolve paths, return JSON)
• Pin/unpin shortcuts (create/remove command aliases)
• Cleanup (remove deprecated files after skill updates)

Should stay as instructions:

• Deciding between architectural approaches
• Reviewing code for quality or style
• Explaining tradeoffs to the user
• Creative writing or design decisions
• Interview/discovery conversations

Key patterns:

• Python without dependencies: stdlib only, argparse for CLI parsing
• Python with dependencies: PEP 723 inline metadata with uv run
• All scripts: Structured output (JSON when piped), clear exit codes, descriptive --help

Context loader pattern

For skills that need project-level context, write a loader script:

The script should follow all standard patterns: argparse with --help, structured JSON output (pretty when interactive, compact when piped), clear exit codes (0 = found, 1 = missing), pathlib for cross-platform paths, and stdlib-only imports. See the "Context File System" section in references/architecture-patterns.md for a skeleton.

The SKILL.md references it: "Load context via python scripts/load_context.py. Consume the full JSON output. Never pipe through head, tail, or grep."

Phase 5: Review

Before presenting the final skill, verify against this checklist:

Basics

• [ ] name is lowercase, hyphens only, max 64 chars
• [ ] description is under 1024 chars and includes trigger phrases
• [ ] description is slightly pushy — covers edge phrasings that should activate the skill
• [ ] SKILL.md body is under 500 lines
• [ ] Instructions use imperative form

Architecture (if applicable)

• [ ] Sub-commands have a router table with clear routing rules
• [ ] command-metadata.json is the single source of truth for command descriptions
• [ ] Setup gates are defined with fail actions for each gate
• [ ] Register/mode system classifies before loading references
• [ ] Capability-gated steps degrade gracefully with one-line skip reasons
• [ ] Router/domain skills with distinct sections (intake, routing, principles) consider XML tags for clarity (references/xml-structure-guide.md)

References

• [ ] Domain knowledge split into references/ with clear "when to read" pointers
• [ ] Each reference is self-contained — no transitive loading (see spec-guide.md → Reference Architecture)
• [ ] Reference loading is conditional, not eager ("Read X if Y happens")
• [ ] Shared concerns (auth, config) extracted into their own reference, not embedded in a consumer
• [ ] Error handling lives in the reference for the tool that produces the error
• [ ] Multi-approach skills include a decision table routing to the correct reference
• [ ] No browser-only tools referenced (Postman, API consoles, OAuth login pages)

Scripts

• [ ] Scripts (if any) have shebangs, structured output, and --help
• [ ] Context loader returns JSON, handles missing files, resolves fallback paths
• [ ] Scripts are cross-platform (pathlib, tempfile, no hardcoded paths)
• [ ] Scripts are idempotent — safe to re-run

API/Service Skills (if applicable)

• [ ] Credential files are never read into context — passed via shell substitution only
• [ ] Credential setup is single-sourced in its own reference file
• [ ] Capability gate checks for credentials before attempting API calls
• [ ] API schema discovery is documented (OpenAPI download, GraphQL introspection, or live endpoints)
• [ ] API examples have been validated against the live endpoint
• [ ] Instance-specific values include programmatic discov

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: redhat-developer
• Source: redhat-developer/rhdh-skill
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.