common-skills/skills/meta-creator/SKILL.md

---
name: meta-creator
description: Creates and iteratively improves agent skills and custom agents. Use when a user wants to create a new skill, update an existing skill, create a new agent, or run eval-driven iteration. Triggers on phrases like "create a skill", "make a skill", "new skill", "update skill", "improve skill", "create an agent", "new agent", "update agent", "创建skill", "创建技能", "新建skill", "更新skill", "优化skill", "创建agent", "新建agent", "更新agent".
metadata:
  author: common-skills
  version: "1.0"
---

# Meta Creator

Create or update agent skills and custom agents. Skills conform to the [Agent Skills specification](references/skills-Specification.md). Agents conform to the [Kiro custom agent configuration](references/custom-agents-configuration-reference.md). For eval-driven iteration, follow the [eval methodology](references/skills-eval.md). For Kiro CLI configuration scopes, file paths, and conflict resolution rules, refer to the [Kiro CLI Chat configuration](references/kiro-cli-chat-configuration.md).

## References

- [skills-Specification.md](references/skills-Specification.md) — SKILL.md format, frontmatter rules, directory structure
- [skills-eval.md](references/skills-eval.md) — eval design, grading, iteration methodology
- [custom-agents-configuration-reference.md](references/custom-agents-configuration-reference.md) — Kiro agent JSON config fields
- [kiro-cli-chat-configuration.md](references/kiro-cli-chat-configuration.md) — Kiro CLI configuration scopes (global/project/agent), file paths, and conflict resolution priority

## Inputs

The user will provide one of:
- A description of what the new skill should do
- An existing skill directory to update or improve
- Eval results / feedback to incorporate into an existing skill

## Workflow

### 1. Gather Requirements

Ask the user (or infer from context):
- What does the skill do? When should it activate?
- What are 2–3 concrete example tasks it should handle?
- Any environment requirements (tools, packages, network)?

### 2. Create or Update `SKILL.md`

**Frontmatter rules:**
- `name`: lowercase, hyphens only, matches directory name, max 64 chars
- `description`: describes what it does AND when to use it; include trigger phrases; max 1024 chars
- Add `compatibility` only if the skill has real environment requirements
- Add `metadata` (author, version) for team skills

**Body content:**
- Write clear step-by-step instructions the agent will follow
- Include concrete examples of inputs and expected outputs
- Cover the 2–3 most important edge cases
- Keep under 500 lines; move detailed reference material to `references/`

### 3. Create `evals/evals.json`

Write at least 3 eval cases covering:
- A typical happy-path use case
- A variation with different phrasing or context
- An edge case (unusual input, boundary condition, or ambiguous request)

Each eval case must have:
- `id`: integer
- `prompt`: realistic user message (not "process this data" — use specific context)
- `expected_output`: human-readable description of what success looks like

Add `assertions` after the first eval run reveals what "good" looks like.

Format:
```json
{
  "skill_name": "<name>",
  "evals": [
    {
      "id": 1,
      "prompt": "...",
      "expected_output": "..."
    }
  ]
}
```

### 4. Create or Update `README.md` and Diagrams

After creating or updating a skill, create (or update) `skills/<name>/README.md` and generate two PlantUML diagrams:

**Architecture diagram** (`assets/architecture.puml`) — static component view:
- Show the skill's files and their roles (SKILL.md, references/, assets/, evals/)
- Show external dependencies (tools, APIs, databases, other files the skill reads/writes)
- Use `package` blocks to group related components; use `component`, `database`, `actor`

**Workflow diagram** (`assets/workflow.puml`) — dynamic sequence view:
- Show the interaction between the user, the skill, and any external systems step by step
- Use `participant` / `actor` and sequence arrows (`->`, `-->`)
- Include branching (`alt`/`opt`) for key decision points

**Convert to SVG:**
```bash
bash scripts/puml2svg.sh <name>
```
This requires Java and Graphviz. The PlantUML jar is resolved automatically from the VS Code extension; override with `PLANTUML_JAR=/path/to/plantuml.jar`.

**README structure:**
```markdown
# <skill-name>

One-line description.

## Architecture
![Architecture](assets/<name>-architecture.svg)

## Workflow
![Workflow](assets/<name>-workflow.svg)

## When to Use
...

## How It Works
...

## File Structure
...

## Evals
\`\`\`bash
python scripts/run_evals.py <name>
\`\`\`
```

### 5. Iterative Improvement (if eval results are provided)

When the user provides eval results, grading output, or human feedback:

1. Identify which assertions failed and why (read execution transcripts if available)
2. Distinguish between:
   - **Instruction gaps**: the skill didn't tell the agent to do something it should
   - **Ambiguous instructions**: the agent interpreted instructions inconsistently
   - **Wrong assertions**: the assertion was too strict, too vague, or checking the wrong thing
3. Propose targeted changes to `SKILL.md`:
   - Generalize fixes — don't patch for a single test case
   - Remove instructions that caused wasted work
   - Add reasoning ("Do X because Y") rather than rigid directives
4. Update `evals/evals.json` to fix broken assertions and add new cases for uncovered scenarios

### 6. Create or Update a Custom Agent (if requested)

When the user wants a new or updated Kiro agent (`.kiro/agents/<name>.json`):

**Required fields:**
- `name`: descriptive, matches the filename (without `.json`)
- `description`: what the agent does and when to use it
- `prompt`: concise system prompt; delegate detail to skill resources where possible
- `tools`: only include tools the agent actually needs
- `allowedTools`: read-only tools are safe to auto-allow; tools that write files or run commands should require confirmation (omit from `allowedTools`)

**Help/greeting response:** The agent's prompt file MUST include instructions to respond to greetings and help requests (e.g., "hi", "hello", "help", "你好", "帮助", "?") with a structured introduction covering:
- What the agent does (one-line summary)
- Key capabilities (bullet list)
- How the agent works step-by-step (execution flow)
- 2–3 concrete example prompts

Example prompt section to include:
```
When the user sends a greeting or help request (e.g., "hi", "hello", "help", "你好", "帮助", "?"), respond with:

---
👋 **<Agent Name>** — <one-line description>

**功能：**
- <capability 1>
- <capability 2>

**执行步骤：**
1. <step 1>
2. <step 2>
3. <step 3>

**使用示例：**
- `<example prompt 1>`
- `<example prompt 2>`
---
```

**Resources:**
- Use `skill://` for skills (lazy-loads, saves context)
- Use `file://` only for small reference docs needed at startup

**Output location:** `.kiro/agents/<name>.json`

**Prompt file:** Extract the prompt to `file://prompts/<name>.md` (relative to `.kiro/agents/`) and reference it as `"prompt": "file://prompts/<name>.md"` to keep the JSON clean.

**Skill install path:** Skills are installed under `.kiro/skills/<name>/`. Reference them as `skill://.kiro/skills/**/SKILL.md` (or a specific path). The `skill://` protocol loads only name/description metadata at startup and fetches full content on demand.

### 7. Post-Creation: Agent Setup (after creating a new skill)

After successfully creating a new skill, ask the user:

> "Do you want a dedicated agent to invoke this skill? If not, it will be available to the `g-assistent` agent by default."

- If **yes**: proceed with Step 5 to create a `.kiro/agents/<name>.json` for the skill.
- If **no**: inform the user that `g-assistent` will route to this skill automatically based on its `description` trigger phrases.

### 8. Post-Agent Checkpoint: Update install-agents.sh

After creating or updating any agent, check whether `scripts/install-agents.sh` needs updating:

1. Read `scripts/install-agents.sh` (if it exists in the repo root).
2. Check if the script handles:
   - Any `file://prompts/<name>.md` references — the script must copy prompt files to the target `prompts/` directory
   - Any new skill references that require special handling
3. If a gap is found, update `scripts/install-agents.sh` and tell the user what changed.
4. If no changes are needed, briefly confirm: "install-agents.sh is up to date."

## Output

- `skills/<name>/SKILL.md` — the skill file
- `skills/<name>/evals/evals.json` — eval cases
- `skills/<name>/README.md` — documentation with architecture and workflow diagrams
- `skills/<name>/assets/architecture.puml` + `architecture.svg` — static component diagram
- `skills/<name>/assets/workflow.puml` + `workflow.svg` — dynamic sequence diagram
- `.kiro/agents/<name>.json` — the agent config (only if user requests a dedicated agent)
- `.kiro/agents/prompts/<name>.md` — the agent prompt file (extracted from JSON)

If creating a new skill, also suggest the directory structure needed (scripts/, references/, assets/) based on the skill's requirements.

## Quality Checklist

Before finishing, verify:
- [ ] `name` matches the directory name exactly
- [ ] `description` includes both what it does and when to activate (trigger phrases)
- [ ] Body instructions are actionable, not vague
- [ ] At least 3 eval cases with varied prompts
- [ ] No eval prompt is too generic (e.g., "test this skill")
- [ ] SKILL.md is under 500 lines
- [ ] `README.md` exists with Architecture and Workflow sections
- [ ] `assets/architecture.puml` and `assets/workflow.puml` exist and SVGs are generated
- [ ] Agent prompt includes a greeting/help response with capabilities and example prompts (for new agents)