aidd-upskill

A guide for creating, reviewing, and restructuring skills used by coding agents. It describes how to keep instructions clear, reusable, and matched to the kind of work that needs either fixed logic or judgment.

In plain words
What is it for?
It helps scaffold new skills, review existing ones, and refactor skills in the project's skill directories using structured instructions.
Why use it?
It helps avoid skills that are vague, repetitive, overly large, or difficult for an agent to follow. It also provides checks for deciding when shared instructions should become a separate reusable skill.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/paralleldrive/aidd/aidd-upskill
Any agent
npx skills add paralleldrive/aidd --skill aidd-upskill
Clone the repo
git clone --depth 1 https://github.com/paralleldrive/aidd

Made for: Claude Code, Codex.

Per session 36 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,022 The whole file, excluding the scripts and references it only reads on demand.
Security scan B 1 finding. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00036 $0.01022
Opus 5 $0.00018 $0.00511
Sonnet 5 $0.00007 $0.00204
Haiku 4.5 $0.00004 $0.00102

Measured 2d ago against content hash 6d4259ddb008, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade B, and why

aidd-upskill scanned grade B with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

The scan reads SKILL.md. This mod also ships 2 executable files (scripts/validate-skill.js, scripts/validate-skill.test.js), listed below but not scanned — reading those needs a real analyzer, not pattern matching.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Asks for rootmediumPrivilege escalation

A mod that escalates privileges can change anything on the machine, not only the project.

# my-skill-test.sudo import 'path/to/skill.md'
ai/skills/aidd-upskill/SKILL.md · 135 lines

How it starts

The opening of the file, as written. The whole thing — 135 lines — stays where its author put it; the contents beside it link to each section on GitHub.

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

  1. name + description — loaded at startup for all skills
  2. Full SKILL.md body — loaded on activation
  3. 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.

Read the full file on GitHub · 135 lines

Files

What ships with it

8 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 135 lines · 36 tokens per session scan B 6d4259ddb008

Subscribe to this mod's changes

aidd-upskill is a skill published in the GitHub repository paralleldrive/aidd (380 stars, last pushed 2mo ago), licensed MIT. It adds 36 tokens to every session and 1,022 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it B with 1 finding (asks for root). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other skills, from other repositories

copilotkit-integrations

Use when wiring an external agent framework (LangGraph, CrewAI, PydanticAI, Mastra, ADK, LlamaIndex, Agno, Strands, Microsoft Agent Framework, or others) into a CopilotKit application via the AG-UI protocol.

CopilotKit/CopilotKit · 61 tokens

a2ui-renderer

Render A2UI (Agent-to-UI declarative surfaces) in CopilotKit v2. Enable the runtime via CopilotRuntime({ a2ui: {...} }), then enable the provider via . Auto-activates via /info — do NOT manually pass renderActivityMessages. createA2UIMessageRenderer ships from @copilotkit/react-core/v2; low-level primitives…

CopilotKit/CopilotKit · 175 tokens

copilotkit-develop

Use when building AI-powered features with CopilotKit v2 -- adding chat interfaces, registering frontend tools, sharing application context with agents, handling agent interrupts, and working with the CopilotKit runtime.

CopilotKit/CopilotKit · 46 tokens

copilotkit-upgrade

Use when migrating a CopilotKit v1 application to v2 -- updating package imports, replacing deprecated hooks and components, switching from GraphQL runtime to AG-UI protocol runtime, and resolving breaking API changes.

CopilotKit/CopilotKit · 48 tokens

copilotkit-debug

Use when diagnosing CopilotKit issues -- runtime connectivity failures, agent not responding, streaming errors, tool execution problems, transcription failures, version mismatches, and AG-UI event tracing.

CopilotKit/CopilotKit · 42 tokens

adk-debug

Diagnoses misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model. Covers the adk run CLI and the adk web dev server with its session, trace, and debug HTTP endpoints. Use when an agent returns the wrong answer, ignores a tool or swallows a tool error, hangs…

google/adk-python · 191 tokens