general-skill-creator

Files (18)

• LICENSE.txt
• SKILL.md
• analyzer.md · agents/
• comparator.md · agents/
• grader.md · agents/
• eval_review.html · assets/
• generate_review.py · eval-viewer/
• viewer.html · eval-viewer/
• schemas.md · references/
• __init__.py · scripts/
• aggregate_benchmark.py · scripts/
• generate_report.py · scripts/
• improve_description.py · scripts/
• package_skill.py · scripts/
• quick_validate.py · scripts/
• run_eval.py · scripts/
• score_trigger_results.py · scripts/
• utils.py · scripts/

SKILL.md (first lines)

# General Skill Creator

A skill for creating portable Agent Skills and improving them through realistic test runs.

Agent Skills are reusable instruction packages for coding agents. A portable skill should rely on the shared skill pattern: a `SKILL.md` file with frontmatter, concise instructions, and optional bundled resources such as `scripts/`, `references/`, `assets/`, and `evals/`.

## Core Loop

Work through this loop:

1. Understand the user intent and the target agent environments.
2. Confirm where the skill should be installed or authored.
3. Draft or edit the skill.
4. Create realistic test prompts.
5. Run the prompts with the skill and against a baseline.
6. Help the user review qualitative outputs and quantitative checks.
7. Improve the skill from the feedback.
8. Repeat until the skill is useful, portable, and lean.

Use the current coding agent's native capabilities for execution. If the environment has subagents, use them for independent runs. If the environment has headless execution, use it for repeatable test runs. Headless execution means a non-interactive agent run launched by CLI, SDK, API, or task runner, where the prompt, inputs, workspace, and output path are provided up front.

## Communicating With The User

Match the user's level of technical detail. Explain terms such as "eval", "assertion", "headless", and "baseline" when the user seems new to agent workflows.

Keep the user involved at the decisions that shape portability:

- Which agents or agent families should the skill support?
- Where should the skill live: repository, user-level skills folder, organization-managed folder, or a custom path?
- Should the skill be authored once in a canonical directory and copied or linked into agent-specific locations?
- Should test runs prioritize quality, trigger accuracy, speed, or reproducibility?

## Capture Intent

Start by extracting answers from the current conversation when available. Ask for missing details only when they change the skill design.

Capture these details:

1. What should this skill enable an agent to do?
2. Which user phrases, tasks, files, domains, or contexts should trigger it?
3. What output should the user expect?
4. Which tools, credentials, files, services, or local dependencies does it need?
5. Which coding agents, repositories, or workspaces should be able to use it?
6. Where should the skill be installed or authored?
7. Should you create test cases and run an evaluation loop?

For installation, prefer early confirmation. If the user has no preference, recommend a canonical repository-local skill directory when the workspace already has one. If the workspace has no convention, suggest `skills/<skill-name>/` for source control and let the active coding agent handle any environment-specific installation or discovery path.

## Write The Skill

Create or edit a directory with this shape:

```text
skill-name/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── evals/
```

Only create optional directories that the skill actually needs.

`SKILL.md` should contain:

- `name`: kebab-case identifier.
- `description`: trigger guidance written for skill discovery.
- `compatibility`: optional note for required tools, runtimes, credentials, or environment assumptions.
- Body instructions: the workflow the agent should follow.
- Resource pointers: when to read files from `references/`, when to run scripts, and how to use assets.

### Description Guidance

The `description` is the main discovery signal. Write it around user intent, task context, and trigger phrases. Include nearby cases where the skill should trigger even when the user omits the exact skill name.

Good descriptions answer:

- What task does the skill help with?
- Which user requests should trigger it?
- Which adjacent requests should also trigger it because the workflow is useful?
- Which dependency or domain constraints matter?

Keep the description specific enough to beat nearby skills in selection and broad enough to catch natural user phrasing.

### Progressive Disclosure

Use progressive disclosure:

1. Metadata stays small and always visible.
2. `SKILL.md` gives the core workflow.
3. Bundled resources hold long references, templates, scripts, schemas, examples, and generated assets.

Keep `SKILL.md` readable. Move long reference material into `references/` and point to it from the relevant section. Put deterministic or repetitive work into `scripts/` so future agent runs can reuse it.

### Portability Rules

Write skills for the current agent and future agents:

- Use generic terms such as "current coding agent", "subagent", "headless run", "workspace", "tool call", and "artifact".
- Describe what the agent must accomplish, then let the runtime decide which native mechanism, tool, API, or UI action to use.
- Put agent-specific invocation examples in a separate reference only when the user explicitly asks for them.
- Keep paths configurable. Ask for install location early and record the chosen path in the work notes or eval metadata.
- Prefer standard filesystem artifacts for generated outputs and review materials.
- Make telemetry optional. Capture tokens, duration, tool counts, and logs when the environment exposes them; leave fields empty when unavailable.

### Safety And Trust

Create skills whose contents match the user's stated intent. Refuse requests for skills that enable unauthorized access, credential theft, malware, covert data extraction, or deception. For sensitive workflows, include explicit user confirmation steps and clear handling of credentials or private data.

## Test Cases

After drafting the skill, create 2-3 realistic test prompts. Use real-world phrasing with enough context to exercise the skill.

Save test cases to `evals/evals.json`:

```json
{
  "skill_name": "example-skill",
  "evals": [

From jtsang4/efficient-coding, MIT.

More from jtsang4/efficient-coding