maotoumao/Cebian / skills/skill-creator
skill-creator
VerifiedCreate new Cebian skills, edit or improve existing ones, scaffold multi-file skill packages, and validate them against the agentskills.io specification. Use when the user wants to author, refactor, or debug a skill (including questions like "why isn't my skill firing"), declare metadata.permissions for scripts that call chrome.* APIs or inject code into pages, or rewrite a description for better trigger accuracy.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.8 KB |
| references/agentskills-spec.md | markdown | 6.9 KB |
| references/cebian-extensions.md | markdown | 8.0 KB |
| references/description-tuning.md | markdown | 5.8 KB |
| references/injection-patterns.md | markdown | 11.9 KB |
| references/runtime-api.md | markdown | 23.3 KB |
SKILL.md
View on GitHub---
name: skill-creator
description: >
Create new Cebian skills, edit or improve existing ones, scaffold
multi-file skill packages, and validate them against the agentskills.io
specification. Use when the user wants to author, refactor, or debug a
skill (including questions like "why isn't my skill firing"), declare
metadata.permissions for scripts that call chrome.* APIs or inject code
into pages, or rewrite a description for better trigger accuracy.
compatibility: >
Requires the Cebian VFS filesystem tools (fs_create_file, fs_edit_file,
fs_mkdir, fs_rename, fs_delete, fs_read_file, fs_list, fs_search),
ask_user, and run_skill (used to test any skill that ships scripts/).
metadata:
author: maotoumao
version: "1.0.0"
---
# Cebian skill-creator
A workflow for creating Cebian skills and improving them through iteration. The body below is the loop you follow; the L3 reference files are the facts you cite during each step.
## Hard rules
- **Before drafting any SKILL.md, you MUST `fs_read_file` [assets/skill-template/SKILL.md](assets/skill-template/SKILL.md) and copy its YAML frontmatter block (the `--- ... ---` header at the top) verbatim into the new file.** A SKILL.md without that YAML frontmatter is invalid and will not be indexed. Do not invent alternative formats — there is no `metadata.json`, no `package.json`, no separate manifest. All metadata lives inside the SKILL.md frontmatter.
- **Skill folder name must equal frontmatter `name` exactly.** Rules: 1–64 chars, lowercase `a–z`, digits, hyphens; no leading/trailing hyphen; no `--`. The validator does not currently reject invalid names — the skill will still index — but invalid names are not portable to other agentskills.io clients. Always follow the rules.
- **Do not invent permissions.** Only the values listed in [references/runtime-api.md](references/runtime-api.md) (`chrome.<ns>` from the whitelist, `page.executeJs`, `bgFetch[:<match-pattern>]`, `vfs.read`, `vfs.write`) are reachable. Anything else is silently dropped.
- **For "skill calls an HTTPS API" workflows, default to `bgFetch` + (when there's a binary artifact) `vfs.write` + return a markdown link.** Do **not** route API calls through `executeInPage` to "dodge CORS" — that exposes the API key to any script on the user's current page, and only works while they happen to be on a same-origin tab. The whole anti-pattern catalogue is in [references/injection-patterns.md](references/injection-patterns.md#anti-patterns) — read it before writing your first script-bearing skill.
- **Secrets live in `scripts/*.js`, never in `SKILL.md` body.** The agent reads the body on every invocation; anything in it ends up in the conversation log. Script file contents are only read when the agent explicitly `fs_read_file`s them, which is rare.
- **Freeze a step into `scripts/` when its correctness depends on exact code — selectors, schemas, ordering, constants — that would drift if re-derived from prose each turn; otherwise keep it as instructions. Empty `scripts/` or unused `metadata.permissions` entries are misleading and train users to dismiss permission prompts.**
- **Index cache rules.** Writes via `fs_create_file` / `fs_edit_file` / `fs_delete` under `~/.cebian/skills/` auto-invalidate the in-memory index, so the very next prompt dispatch sees the change (the system prompt is rebuilt each turn). `fs_mkdir` and `fs_rename` do **not** invalidate — after either, follow up with an `fs_edit_file` on `SKILL.md` to force a refresh before testing.
For all frontmatter rules, indexing semantics, and Cebian-specific `metadata.*` keys see [references/agentskills-spec.md](references/agentskills-spec.md) and [references/cebian-extensions.md](references/cebian-extensions.md).
## Workflow
### Step 0 — Is this even a skill?
Skills are not free. Before scaffolding anything, eliminate cheaper alternatives:
| Situation | Use this instead of a skill |
|---|---|
| An existing skill already covers the territory | The existing skill — extend it if the gap is small |
| Reusable text template the user wants to invoke by name | A prompt under `~/.cebian/prompts/<name>.md` |
| One-off action the agent can plan and execute in a single session | The native tools directly (`execute_js`, `chrome_api`, `read_page`, etc.) |
| A single browser-API call available via `chrome_api` | `chrome_api` directly |
| "Fetch this URL into VFS" — a one-off download with no API key or special pre/post-processing | `fs_save_url` directly (no permission prompt, URL is visible to the user) |
`fs_list ~/.cebian/skills` and check for overlaps before proceeding. See [references/injection-patterns.md](references/injection-patterns.md) for the decision matrix in detail.
If a skill is still the right answer, continue.
### Step 1 — Branch: new skill or improving an existing one?
Default to inferring intent from existing context (the user's request, attached recordings/files, the active tab). Only `ask_user` when a piece of information is **strictly required** to proceed and **genuinely missing** from context. Never ask to confirm something the user already said or implied.
#### Branch A — New skill
1. **Determine** (a) what the skill should do, (b) likely trigger phrasings, (c) output format, (d) whether scripts are needed and which `chrome.*` capabilities. Per the rule above, infer from context first; if anything is strictly required and unrecoverable, bundle every question into one `ask_user`.
2. **Choose a name** following the rules above. `fs_list ~/.cebian/skills` to check collisions.
3. **Draft the SKILL.md** starting from [assets/skill-template/SKILL.md](assets/skill-template/SKILL.md). Fill in `name`, `description` (see [references/description-tuning.md](references/description-tuning.md)), `metadata.author`, `metadata.version`, optionally `metadata.matched-url`, `metadata.permissions`, `compatibility`.
4. **Scaffold the directory** with `fs_mkdir` + `fs_create_file`. Add `references/`, `scripts/`, `assets/` only when the skill needs them.
5. Enter the **iteration loop** below.
#### Branch B — Improving / debugging an existing skill
1. **Read the current state.** `fs_read_file` the skill's `SKILL.md` and any `references/*` it cites.
2. **Diagnose** which layer is failing — this determines what to change:
| Symptom | Likely cause | Fix |
|---|---|---|
| Skill never triggers on prompts that should match | `description` undertriggers | Rewrite description; re-run the trigger eval |
| Skill triggers but agent ignores instructions | Body is unclear, contradictory, or buried under references | Tighten body; promote critical content out of L3 |
| Skill loads but agent picks wrong reference / misses one | Reference is mistitled or under-cited from body | Improve cross-reference language in body |
| `run_skill` fails or returns wrong shape | Script bug or wrong `metadata.permissions` (e.g. `bgFetch` URL not in declared pattern, `vfs` path escaping scope, missing whitelist method) | Re-read [references/runtime-api.md](references/runtime-api.md), fix script, re-test |
| Permission prompt fires every time | Declared permission set keeps changing across runs | Stabilize `metadata.permissions` |
| Skill returns huge JSON / base64 blob that bloats the conversation | Script `module.exports`-es binary or large text directly | Declare `vfs.write`, write the artifact to VFS, return a short markdown link or path — see [Anti-pattern #2](references/injection-patterns.md#2-returning-binary-data-via-moduleexports) |
| Skill leaks an API key into the conversation | Key embedded in `SKILL.md` body or passed via `args` | Move the key into the script file; agent never reads script content — see [Anti-pattern #3](references/injection-patterns.md#3-putting-an-api-key-in-the-skillmd-body) |
| Skill's API call works on one tab but fails on others | Using `executeInPage` to call a third-party API | Switch to `bgFetch:<match-pattern>` — see [Anti-pattern #1](references/injection-patterns.md#1-using-executeinpage-to-call-a-third-party-https-api) |
3. **Make the minimum edit** that addresses the diagnosis. Don't restructure unrelated parts.
4. Enter the **iteration loop** below.
### Step 2 — Iteration loop (both branches)
**First-pass skip:** if the user's request gave you enough to produce a complete, runnable skill in one shot, do so and present the result. Run the self-trigger eval and manual-run handshake below **only when the user asks to verify or reports an issue**.
Repeat until the user says it's good enough, or until both eval matrices below are clean:
#### A. Self-trigger eval
The agent can simulate the trigger surface without any infrastructure:
1. **Generate ~8 should-fire prompts** the user might realistically write to invoke this skill. Cover the synonyms and phrasings listed in `description`.
2. **Generate ~8 should-NOT-fire prompts** that are *near misses* — same domain, similar vocabulary, but actually answered by a different skill or no skill at all. Near misses are essential; "write a fibonacci function" is not a useful negative for a PDF skill.
3. For each prompt, simulate the agent's L1 decision: read **only** `name` + `description` + `metadata` (close your mental eyes to body and sources) and predict whether the skill would activate.
4. Tally:
| | Predicted fire | Predicted no-fire |
|---|---|---|
| Should fire | ✓ | ❌ undertrigger |
| Should NOT fire | ❌ overtrigger | ✓ |
5. If either off-diagonal cell is non-empty, rewrite the description per [references/description-tuning.md](references/description-tuning.md) and re-run. If the user prefers to skip the eval and just vibe, do that instead — this is guidance, not policing.
#### B. Manual run with the user
After the description-eval passes:
1. Tell the user to send a fresh message using one of the should-fire prompts.
2. Confirm in the message stream that the agent calls `fs_read_file` on the new `SKILL.md` before answering.
3. If the skill ships scripts: invoke `run_skill` with sample `args`. On first use a permission card appears inline (Deny / Allow once / Always allow this skill) — this is automatic, just call `run_skill` normally and let the user choose. After approval, the script runs; verify the return value matches what the body promises. See [references/runtime-api.md](references/runtime-api.md).
4. Inspect the agent's actual output. Two failure modes to watch:
- **Description level**: skill didn't load. Loop back to A.
- **Body level**: skill loaded but produced wrong output. Edit the body (clarify steps, add an example, move a key fact from a reference into the body).
#### C. Revise
Pick the most concrete piece of feedback from B and make one focused edit. Avoid sweeping rewrites mid-loop. Then loop back to A.
Exit the loop when:
- Description eval is clean AND a manual run produced output the user accepts, OR
- The user explicitly says "ship it".
## References
- [references/agentskills-spec.md](references/agentskills-spec.md) — the upstream agentskills.io spec: frontmatter fields, directory conventions, name rules, progressive-disclosure model.
- [references/cebian-extensions.md](references/cebian-extensions.md) — Cebian's private `metadata.*` keys (`matched-url`, `permissions`, `disabled`), what's enforced vs documentation-only, and storage layout.
- [references/runtime-api.md](references/runtime-api.md) — skill script execution: sandbox globals, the `chrome.*` whitelist, `page.executeJs` / `executeInPage`, the user-permission flow, error semantics.
- [references/injection-patterns.md](references/injection-patterns.md) — `executeInPage` vs `execute_js`, the cookie matrix, and when **not** to ship a skill.
- [references/description-tuning.md](references/description-tuning.md) — anatomy of a good description, before/after rewrites, anti-patterns.
- [assets/skill-template/](assets/skill-template/) — copy-paste starting point for a new skill.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |