skill-maker

Files (12)

• SKILL.md
• anti-patterns.md · references/
• api-skill-patterns.md · references/
• architecture-patterns.md · references/
• consolidation-guide.md · references/
• description-guide.md · references/
• scripts-guide.md · references/
• spec-guide.md · references/
• xml-structure-guide.md · references/
• router-skill-xml.md · templates/
• router-skill.md · templates/
• simple-skill.md · templates/

SKILL.md (first lines)

<intake>

# Create, Audit, or Consolidate Skills

Create agent skills following the [Agent Skills open standard](https://agentskills.io/specification).

Skills in this repository ship as components of the root [Agent Plugin](https://agent-plugins.org/) (`plugin.json` at the repository root under `skills/<name>/`). Do not place a `plugin.json` inside a skill directory.

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.**
</intake>

<routing>

| 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 |

</routing>

## 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.

From redhat-developer/rhdh-users-agent-plugin, Apache-2.0.

More from redhat-developer/rhdh-users-agent-plugin