aidokitwiki
User Docs Wiki

Scenario: Author a custom skill

Audience-User Status-Shipped v0.5

When to use #

You want to build a project-scoped, personal, or org-wide skill / hook / slash-command / MCP wrapper for your AI CLI workflow. Use this when the procedural knowledge you keep re-typing into the model should instead live as a reusable, auto-loaded skill.

At a glance #

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
flowchart LR
  classDef actor    fill:#ede9fe,stroke:#6d28d9,color:#1e1b4b,stroke-width:1.2px;
  classDef cli      fill:#dbeafe,stroke:#1d4ed8,color:#0c1f4a,stroke-width:1.4px;
  classDef adapter  fill:#cffafe,stroke:#0e7490,color:#083344;
  classDef pack     fill:#dcfce7,stroke:#15803d,color:#052e16;
  classDef core     fill:#fef9c3,stroke:#a16207,color:#422006;
  classDef artifact fill:#f1f5f9,stroke:#475569,color:#0f172a;
  classDef stop     fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,stroke-dasharray:4 3;
  classDef ok       fill:#ecfdf5,stroke:#047857,color:#064e3b;
  classDef external fill:#fff7ed,stroke:#c2410c,color:#431407;
  you(["you"]):::actor
  scaf["aidokit new skill"]:::cli
  edit["edit SKILL.md"]:::artifact
  trig["trigger from AI CLI"]:::external
  doc["docs/skills.md"]:::pack
  ok(["skill auto-loads"]):::ok
  you --> scaf --> edit --> trig --> doc --> ok

Step-by-step #

1. Scaffold #

aidokit new skill --kind <procedural|slash-command|hook|mcp-wrapper> --slug my-skill --audience <personal|project|org>

Expected: a new directory skills/my-skill/ under the project's engine directory (.claude/, .codex/, or .copilot/ depending on the adapter), containing a starter SKILL.md.

2. Edit the generated file #

Open the new file in your editor:

$EDITOR <engine-dir>/skills/my-skill/SKILL.md

Fill in the frontmatter (description, allowedTools) and the procedure body. The frontmatter is what drives auto-loading; keep it intact.

Expected: a SKILL.md with a non-placeholder description and at least one procedure step.

3. Trigger the skill from your AI CLI #

Open the AI CLI that matches your adapter:

If Claude Code

claude

If Codex

codex

If Copilot

gh copilot

Then phrase a request that should trigger the skill, or invoke /my-skill if it is a slash-command.

Expected: the CLI surfaces the skill (or runs it) when the trigger condition is met.

4. Document it #

Add a one-line entry pointing at the new skill folder in docs/skills.md.

Expected: teammates can discover the skill without grepping the engine directory.

5. (Optional) Publish via a stack-pack #

For org-wide reuse, package the skill inside a published @aidokit/stack-pack-*. Follow the author-a-stack-pack tutorial.

Common mistakes #

See also #