Agent skill

AIDD Skill Authoring Guide

Guides creating, reviewing or refactoring AI-Driven Development skills so each one stays minimal, composable and named around a single clear function.

MITAuto-check passedAgent Workflows

Install AIDD Skill Authoring Guide

skills CLI

$ npx skills add paralleldrive/aidd --skill aidd-upskill -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install paralleldrive/aidd aidd-upskill --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/paralleldrive/aidd.git skills-src && mkdir -p .claude/skills && cp -r skills-src/ai/skills/aidd-upskill .claude/skills/aidd-upskill && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "aidd-upskill" agent skill from https://github.com/paralleldrive/aidd/tree/main/ai/skills/aidd-upskill into .claude/skills/aidd-upskill/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aidd-upskill", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/paralleldrive/aidd/tree/main/ai/skills/aidd-upskill

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add paralleldrive/aidd --skill aidd-upskill -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install paralleldrive/aidd aidd-upskill --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/paralleldrive/aidd.git skills-src && mkdir -p .agents/skills && cp -r skills-src/ai/skills/aidd-upskill .agents/skills/aidd-upskill && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "aidd-upskill" agent skill from https://github.com/paralleldrive/aidd/tree/main/ai/skills/aidd-upskill into .agents/skills/aidd-upskill/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aidd-upskill", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add paralleldrive/aidd --skill aidd-upskill -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install paralleldrive/aidd aidd-upskill --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/paralleldrive/aidd.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/ai/skills/aidd-upskill .cursor/skills/aidd-upskill && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "aidd-upskill" agent skill from https://github.com/paralleldrive/aidd/tree/main/ai/skills/aidd-upskill into .cursor/skills/aidd-upskill/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aidd-upskill", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/paralleldrive/aidd.git --path ai/skills/aidd-upskill

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add paralleldrive/aidd --skill aidd-upskill -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install paralleldrive/aidd aidd-upskill --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/paralleldrive/aidd.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/ai/skills/aidd-upskill .gemini/skills/aidd-upskill && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "aidd-upskill" agent skill from https://github.com/paralleldrive/aidd/tree/main/ai/skills/aidd-upskill into .gemini/skills/aidd-upskill/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aidd-upskill", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install paralleldrive/aidd aidd-upskill

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add paralleldrive/aidd --skill aidd-upskill -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/paralleldrive/aidd.git skills-src && mkdir -p .github/skills && cp -r skills-src/ai/skills/aidd-upskill .github/skills/aidd-upskill && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "aidd-upskill" agent skill from https://github.com/paralleldrive/aidd/tree/main/ai/skills/aidd-upskill into .github/skills/aidd-upskill/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aidd-upskill", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add paralleldrive/aidd --skill aidd-upskill -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install paralleldrive/aidd aidd-upskill --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/paralleldrive/aidd.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/ai/skills/aidd-upskill .opencode/skills/aidd-upskill && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "aidd-upskill" agent skill from https://github.com/paralleldrive/aidd/tree/main/ai/skills/aidd-upskill into .opencode/skills/aidd-upskill/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "aidd-upskill", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: aidd-upskill
GitHub stars: 384
Token cost: ~1.1k tokens
SKILL.md length: 431 words
Files: 9 (incl. scripts, references)
Skills in repo: 35
Repo updated: Jun 12, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Guides creating, reviewing or refactoring AI-Driven Development skills so each one stays minimal, composable and named around a single clear function.

Works in 3 steps: name + description — loaded at startup… → Full SKILL.md body — loaded on activation → scripts/, references/, assets/ — loaded…
Scaffolding a brand-new AIDD skill under ai/skills/
SKILL.md covers Role, Process, Skill Structure and Progressive Disclosure, plus 2 more sections
Runs JavaScript scripts from its folder

What it does

Treats every skill as a function mapping input to output, and uses that lens to decide when two skills should share an extracted abstraction versus stay separate: when two skills compute the same underlying transformation, that shared piece gets named and hidden behind the skills that use it. Deterministic logic becomes a CLI tool or compiled bundle; logic that needs judgment stays an AI prompt written in natural language, with SudoLang syntax layered in only for constraints, commands and typed interfaces.

A skill follows a fixed progressive-disclosure shape: `name` and `description` loaded at startup, the full body loaded on activation, and `scripts/`, `references/` or `assets/` loaded only on demand. A bundled `validate-skill` script checks a new or edited skill against size and structure thresholds, and the guide's own two commands, `/aidd-upskill create` and `/aidd-upskill review`, scaffold a new skill or evaluate an existing one against these criteria.

When your agent uses it

Scaffolding a brand-new AIDD skill under ai/skills/
Reviewing an existing skill against the project's authoring criteria
Deciding whether two similar skills should share an extracted abstraction
Trimming a skill's SKILL.md body down by moving detail into references/

Example prompts

“Create a new skill called aidd-release-notes that drafts a changelog entry.”
“Review the aidd-pr-summary skill against our authoring guide.”
“These two skills both reformat a diff the same way — extract the shared logic.”

Requirements

Node.js, to run the bundled validate-skill script

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

name + description — loaded at startup for all skills
Full SKILL.md body — loaded on activation
scripts/, references/, assets/ — loaded on demand

What it can do on your machine

Read from SKILL.md and the folder at commit 9a7c8e3. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships 3 files in scripts/ (JavaScript), which the agent can run.
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

AIDD Skill Authoring Guide loads about 1.1k tokens when it runs, and up to ~2.6k if it reads all its reference files. Until then it costs about 37 tokens; SKILL.md has 431 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~37
When it runs · the whole SKILL.md, loaded when a task matches: ~1.1k
With references · SKILL.md plus every file in references/, read only if the agent opens them: ~2.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from paralleldrive/aidd at commit 9a7c8e3, republished under its MIT licence (© paralleldrive). 431 words, ~1,067 tokens.

Download SKILL.mdSave it as .claude/skills/aidd-upskill/SKILL.md (or your agent's skills folder). This skill also uses 8 other files; get the full folder from GitHub.

name: aidd-upskill
description: Guide for crafting high-quality AIDD skills. Use when creating, reviewing, or refactoring skills in ai/skills/ or aidd-custom/skills/.

aidd-upskill

Role

Expert skill author. Craft skills that are clear, minimal, and recomposable, giving agents exactly the context they need — nothing more.

Skill components: ai/skills/aidd-sudolang-syntax, ai/skills/aidd-please (provides RTC think())

SudoLang spec: Generated skills must use SudoLang syntax for constraints, commands, functions, composition pipelines, and any required typed interfaces, as needed.

Constraints { Prefer natural language in markdown format Use SudoLang interfaces, pattern matching, and /commands for formal specification (logic is deterministic) => CLI tool or compiled Bun bundle (logic requires judgment) => AI prompt (a candidate abstraction cannot be named) => it is not an abstraction yet (two or more skills share the same f) => extract a shared abstraction }

Commands { /aidd-upskill create [name] — scaffold a new skill at aidd-custom/skills/aidd-[name]/SKILL.md /aidd-upskill review [target] — evaluate a skill against the criteria in this guide }

This skill is itself an example of the structure it prescribes.

import references/types.md import references/process.md

Process

The createSkill and reviewSkill pipelines — including all step definitions — are defined in references/process.md (imported above). Read that file for the full authoring and review workflows.

Skill Structure

ai/skills/aidd-<verbOrRoleBasedNoun>/
├── SKILL.md          # Required: frontmatter + instructions
├── README.md         # Optional: what the skill is, why it's useful, command reference
├── scripts/          # Optional: CLI tools
├── references/       # Optional: detailed reference docs
└── assets/           # Optional: templates, data files

Progressive Disclosure

name + description — loaded at startup for all skills
Full SKILL.md body — loaded on activation
scripts/, references/, assets/ — loaded on demand

Keep SKILL.md concise — run validate-skill to check thresholds. Move reference material to references/. Use import $referenceFile to link it.

A Skill Is a Function

f: Input → Output

Every skill maps input context to output or action. Use this as the primary design lens.

Abstraction

Two skills sharing the same f should share the same abstraction:

Generalization: extract the shared f, name it, hide it
Specialization: expose only what differs as parameters

f: A → B
g: B → C
h: A → C   ← h hides B. This is a good abstraction.

"Simplicity is removing the obvious and adding the meaningful." — John Maeda

Show full SKILL.md (157 more words)Show less

The Function Test

What is f? Name it. If you can't name it, it's not an abstraction yet.
What varies? Those are the parameters — expose them.
What is constant? Those are the defaults — hide them.
Is f deterministic? See CLI vs. AI prompt in Constraints above.
Is the result independently useful and recomposable? If not, it's inlining, not abstraction.

Default Parameters

Use defaults wherever the default is obvious. Callers supply only what is meaningfully different. If every caller passes the same value, it's a default waiting to be named.

Eval Tests

Use Riteway AI to write eval tests for skill commands. The Riteway AI skill may be available as aidd-riteway-ai in your project's ai/skills/ directory.

Core principle: never mix thinking and effects in a single /command. Break commands into sub-commands or separate skills so every thinking stage is independently testable.

(command involves thinking + side effects) => split into sub-commands
(command is a pure thinking stage) => write an eval test
(command is a side effect only) => skip the test

Eval Test Structure

Tests are .sudo files using SudoLang syntax:

# my-skill-test.sudo

import 'path/to/skill.md'

userPrompt = """
<the prompt or command input being tested>
"""

- Given <context>, should <expected thinking output>
- Given <context>, should <expected thinking output>

Run with:

shell

riteway ai path/to/my-skill-test.sudo

Files

SKILL.md and 8 other files (scripts, references) in ai/skills/aidd-upskill of paralleldrive/aidd.

SKILL.md
README.md
index.md
references/index.md
references/process.md
references/types.md
scripts/index.md
scripts/validate-skill.js
scripts/validate-skill.test.js

Open the folder on GitHubat commit 9a7c8e3

Compare with similar skills

AIDD Skill Authoring Guide next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

AIDD Skill Authoring Guide compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
AIDD Skill Authoring Guide this skillparalleldrive/aidd	384	—	~1.1k	Automated safety check: Pass	MIT	3 mo ago
Claude Code Plugin Structureanthropics/claude-plugins-official	37k	10 repos	~3.4k	Automated safety check: Pass	Apache-2.0	yesterday
SkillAnything Skill GeneratorAgentSkillOS/SkillAnything	471	—	~1.9k	Automated safety check: Pass	MIT	6 mo ago
LubanLearnPrompt/luban-skill	957	—	~3.1k	Automated safety check: Pass	MIT	2 mo ago
Crush Builtin Skillscharmbracelet/crush	29k	—	~466	Automated safety check: Pass	Custom licence	yesterday
Build Cs Skillcodestable/CodeStable	1.1k	—	~3k	Automated safety check: Pass	None	1 mo ago

Similar skills

Claude Code Plugin Structure
anthropics/claude-plugins-official
Official
Explains the directory layout, plugin.json manifest and component organization of a Claude Code plugin, including auto-discovery and portable paths.
37k GitHub starsUsed in 10 repos~3.4k tokens
Agent WorkflowsAuto-check passed
SkillAnything Skill Generator
AgentSkillOS/SkillAnything
Generates a complete agent skill for a target tool, API, library or workflow through a seven-phase pipeline that ends with testing, tuning and packaging for several platforms.
471 GitHub stars~1.9k tokensUpdated 6 mo ago
Agent WorkflowsAuto-check passed
Luban
LearnPrompt/luban-skill
鲁班（Luban）——Skill打磨工坊。把一个"能用的Skill"打磨成"能被理解、能被安装、能被传播、能被验证、能持续进化"的公共Skill资产。
957 GitHub stars~3.1k tokensUpdated 2 mo ago
Agent WorkflowsAuto-check passed
Crush Builtin Skills
charmbracelet/crush
Explains how the Crush coding agent embeds builtin skills in its binary and how to add or edit one, including the discovery test and build commands.
29k GitHub stars~466 tokensUpdated yesterday
Agent WorkflowsAuto-check passed
Build Cs Skill
codestable/CodeStable
CodeStable skill authoring and evolution protocol. An agent skill from codestable/CodeStable.
1.1k GitHub stars~3k tokensUpdated 1 mo ago
Agent WorkflowsAuto-check passed
ShellLM Skill Author
laude-institute/headlong
Scaffolds new ShellLM skills with the right frontmatter, directory layout and agent-facing writing style, so an agent can extend its own capabilities.
1.2k GitHub stars~1.3k tokensUpdated yesterday
Agent WorkflowsAuto-check passed

Questions about AIDD Skill Authoring Guide

What does AIDD Skill Authoring Guide do?

Guides creating, reviewing or refactoring AI-Driven Development skills so each one stays minimal, composable and named around a single clear function. Treats every skill as a function mapping input to output, and uses that lens to decide when two skills should share an extracted abstraction versus stay separate: when two skills compute the same underlying transformation, that shared piece gets named and hidden behind the skills that use it. Deterministic logic becomes a CLI tool or compiled bundle; logic that needs judgment stays an AI prompt written in natural language, with SudoLang syntax layered in only for constraints, commands and typed interfaces.

When should I use AIDD Skill Authoring Guide?

AIDD Skill Authoring Guide fits situations like: scaffolding a brand-new AIDD skill under ai/skills/; reviewing an existing skill against the project's authoring criteria; deciding whether two similar skills should share an extracted abstraction; trimming a skill's SKILL.md body down by moving detail into references/.

How do I install AIDD Skill Authoring Guide in Claude Code?

Run `npx skills add paralleldrive/aidd --skill aidd-upskill -a claude-code`. Or copy the skill folder (ai/skills/aidd-upskill in paralleldrive/aidd) into .claude/skills/aidd-upskill in your project. Claude Code loads it when a task matches its description.

How do I install AIDD Skill Authoring Guide in Codex?

Run `npx skills add paralleldrive/aidd --skill aidd-upskill -a codex`. Or copy the skill folder (ai/skills/aidd-upskill in paralleldrive/aidd) into .agents/skills/aidd-upskill in your project. Codex loads it when a task matches its description.

Can I use AIDD Skill Authoring Guide in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add paralleldrive/aidd --skill aidd-upskill -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/aidd-upskill, .gemini/skills/aidd-upskill, .github/skills/aidd-upskill and .opencode/skills/aidd-upskill in your project.

What does AIDD Skill Authoring Guide need to run?

Going by SKILL.md and its folder, AIDD Skill Authoring Guide needs JavaScript for the scripts in its folder. Our summary lists: Node.js, to run the bundled validate-skill script.

Does AIDD Skill Authoring Guide access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is AIDD Skill Authoring Guide safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does AIDD Skill Authoring Guide use?

AIDD Skill Authoring Guide is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does AIDD Skill Authoring Guide use?

About 1.1k tokens (SKILL.md is roughly 4.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.5k tokens, read only when the agent opens those files.

What are the alternatives to AIDD Skill Authoring Guide?

Skills that share tags, products or a category with AIDD Skill Authoring Guide: Claude Code Plugin Structure (anthropics/claude-plugins-official, 37k stars), SkillAnything Skill Generator (AgentSkillOS/SkillAnything, 471 stars), Luban (LearnPrompt/luban-skill, 957 stars) and Crush Builtin Skills (charmbracelet/crush, 29k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains AIDD Skill Authoring Guide?

paralleldrive (a GitHub organization) maintains it in paralleldrive/aidd, which has 384 GitHub stars. The repository holds 35 skills in this directory. The repository was last updated on June 12, 2026.

Source: paralleldrive/aidd on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install AIDD Skill Authoring Guide

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

aidd-upskill

Role

Process

Skill Structure

Progressive Disclosure

A Skill Is a Function

Abstraction

The Function Test

Default Parameters

Eval Tests

Eval Test Structure

Files

Compare with similar skills

Similar skills

More from paralleldrive/aidd

Related

Questions about AIDD Skill Authoring Guide