# Skill Authoring > Use when creating, editing, or evaluating a skill in this collection — writes SKILL.md frontmatter and four sections, generates the Codex adapter, runs the validator, and tunes description triggering. The authoring half of using-skills (which routes/consumes). Triggers on "write a skill", "edit skill", "skill eval", "tune triggers", "写技能", "改技能", "技能评估". Not for routing to an existing skill (use… - **Type:** Skill - **Install:** `agentstack add skill-int2t05-engineering-skills-skill-authoring` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [int2t05](https://agentstack.voostack.com/s/int2t05) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [int2t05](https://github.com/int2t05) - **Source:** https://github.com/int2t05/engineering-skills/tree/main/skills/meta/skill-authoring ## Install ```sh agentstack add skill-int2t05-engineering-skills-skill-authoring ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Skill Authoring Create, edit, and evaluate skills in this collection. Every skill conforms to the anatomy in `references/skill-anatomy.md` and passes `scripts/validate-skills.sh`. This skill is the authoring half — `using-skills` routes work to existing skills; this one makes new ones or fixes existing ones. ## When to use - Creating a new skill (new SDLC phase gap, repeated task worth a skill) - Editing an existing skill's frontmatter, steps, or references - Tuning a skill's description triggers (false positives, false negatives, collision with another skill) - Evaluating a skill — does it fire when it should, stay distinct from neighbors, change agent behavior? - Triggers on "write a skill", "edit skill", "skill eval", "tune triggers", "写技能", "改技能", "技能评估" **Not for:** routing a task to an existing skill (use `using-skills`); designing an MCP server (out of scope, see official mcp-builder docs); writing project docs like PRD/README (use `spec`/`oss-polish`). ## Steps ### 1. Check the anatomy before writing Load [${CLAUDE_PLUGIN_ROOT}/references/skill-anatomy.md](${CLAUDE_PLUGIN_ROOT}/references/skill-anatomy.md) — the folder layout, frontmatter rules (name + description + optional disable-model-invocation only), the four body sections (When to use / Steps / Verify / References), the `**Output:**` convention, progressive disclosure (15-150 line SKILL.md, depth in `references/`), and the description hybrid format (`Use when…` + `Triggers on…` + exclusions, ≤1024 chars, no cross-skill phrase collisions). ### 2. Place the skill and wire the backbone - **Phase** — pick the phase by output type + consumer, not by method. A skill producing a design artifact for design consumers goes in 03-design even if it reuses research methods (see `design-research`). Method does not set phase; output and consumers do. - **Backbone** — every skill links `engineering-principles.md`. PM-side skills also link `product-principles.md`; UIUX skills also link `design-principles.md`. The validator enforces these (see `scripts/validate-skills.sh` `pm_skills`/`uiux_skills` lists — add the new skill there if it's PM or UIUX). - **Path** — `skills///SKILL.md` (kebab-case name, uppercase SKILL.md). ### 3. Write the description for routing, not features - **Name actions, not tools.** "Use when retrieving real design references" not "Use WebFetch on galleries." The model routes on user intent, not on the tool the skill happens to run. - **Hybrid format:** `Use when [intent]. [One sentence: what]. Triggers on "phrase1", "phrase2", "中文1" — also when user says "[natural cue]". Not for [exclusion] → use [other-skill].` - **No collision.** Quoted trigger phrases must be unique across all skills — the validator's collision check flags any shared phrase. Before finalizing, grep the phrase across `skills/`. - **Keep "Triggers on" literal** — the validator requires it; `gen-agents-yaml.py` cuts the description at that clause for the Codex adapter. ### 4. Write the four sections - **When to use** — 2-4 conditions + a `**Not for:**` boundary naming the adjacent skills (prevents routing collisions). This is load-bearing: every boundary pair in this pack was deliberate. - **Steps** — numbered, each independently verifiable. Push encyclopedic data into `references/.md` loaded on demand (progressive disclosure). Reference files over 100 lines get a `## Contents` ToC (see the anatomy's progressive-disclosure rule). - **Verify** — concrete evidence (file exists, no placeholders, count met), not "looks right". - **References** — `engineering-principles.md` (+ domain backbone) + skill-specific `references/`. Every `references/` link must resolve (dead-link check). - **Output** — declare `**Output:** ` only if the skill produces a doc/artifact. Behavior-only skills (implement, tdd, debugging) omit it. Every declared path must appear in `docs/skill-outputs.md` (validator syncs). ### 5. Generate the adapter + run the validator ```bash python scripts/gen-agents-yaml.py # generate agents/openai.yaml for every skill bash scripts/validate-skills.sh # schema + manifest-sync + collision + dead-links + domain-principles + Output-sync ``` Fix every FAIL before considering the skill done. The validator is the gate — a skill that doesn't pass doesn't ship. ### 6. Sync the discovery surface A new or renamed skill touches: `.claude-plugin/plugin.json` skills[] (the source), `docs/skill-outputs.md` (if the skill produces a doc), `AGENTS.md` routing table, `skills/meta/using-skills/SKILL.md` phase list, `skills/meta/using-skills/references/phase-tree.md`, and the `README.md` + `README.zh-CN.md` catalogs. The catalog ordering and the `research (general/market/tech-selection modes)` suffix are human-curated, so these are maintained by hand — but the validator now enforces them: the **presence check** fails if a manifest skill is missing from any of the five routing surfaces, and the **dynamic Output scan** fails if a declared `**Output:` path is missing from `docs/skill-outputs.md` (no hardcoded dict to update). A rename is a breaking change (the old invocation name disappears) — bump the version and call it out in the commit. ### 7. Evaluate — does it actually work? Three tiers (adapted from established skill-eval practice): - **Structural** (free, CI) — validator green. Already done in Step 5. - **Trigger & routing** (free, CI) — does the description fire on the right prompts and not collide? The collision check is the automated subset. For deeper routing eval, write ~3 positive + ~2 negative trigger prompts per skill and check the model routes correctly (defer to实战, like the Tier 2 framework). - **Behavioral** (tokens, on demand) — does an agent following the skill satisfy its `## Verify`? `bash scripts/run-eval.sh --skill ` runs the skill against real tasks with and without the skill loaded (RED-GREEN baseline) and grades the output. Every skill should have ≥3 cases (2 positive + 1 negative control) in `evals/cases/.json` before it's trusted. This is the real test; do it before trusting the skill. If a skill passes structural but fails behavioral, the SKILL.md is wrong even if the validator is green. Fix the skill, not the test. ## Verify - [ ] `scripts/validate-skills.sh` green (count, manifest-sync, collision, dead-links, domain-principles, Output-sync) - [ ] `gen-agents-yaml.py` generated the adapter with no drift - [ ] Description follows the hybrid format; quoted phrases unique across the pack (grep-confirmed) - [ ] Four sections present; `**Not for:**` names adjacent skills; `**Output:**` declared iff doc-producing - [ ] All discovery surface files synced (plugin.json, validator lists, skill-outputs, AGENTS, phase-tree, using-skills, README×2) - [ ] At least one behavioral check run against a real task (not just structural green); ≥3 eval cases in `evals/cases/.json` for skills that gate real work ## References - [${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md](${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md) — discipline for every skill (surface assumptions, verify don't assume, surgical scope). - [${CLAUDE_PLUGIN_ROOT}/references/skill-anatomy.md](${CLAUDE_PLUGIN_ROOT}/references/skill-anatomy.md) — the anatomy this skill enforces: folder layout, frontmatter, four sections, Output convention, progressive disclosure, description hybrid format, superset-of-official-spec note. - [references/eval-tiers.md](references/eval-tiers.md) — the three eval tiers (structural / trigger-routing / behavioral) in detail, with the prompt-template for routing eval. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [int2t05](https://github.com/int2t05) - **Source:** [int2t05/engineering-skills](https://github.com/int2t05/engineering-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-int2t05-engineering-skills-skill-authoring - Seller: https://agentstack.voostack.com/s/int2t05 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.