Skills and packs

Skills

An AgileFlow skill is a standard Agent Skill: a directory with a SKILL.md whose frontmatter has a name and a description. Providers read the name and description up front and load the body only when the skill is relevant (or when you invoke it by name).

Copydiagnosing-bugs/
├── SKILL.md                 # required: frontmatter + instructions
├── references/              # optional: loaded only when needed
├── scripts/                 # optional: deterministic helpers
├── evals/                   # AgileFlow eval scenarios (not installed into projects)
└── agileflow.skill.yaml     # AgileFlow packaging metadata

agileflow.skill.yaml holds packaging metadata that providers ignore:

Copyschema: 1
package:
  name: "@agileflow/diagnosing-bugs"
  version: "1.0.1"
activation:
  mode: auto                # or manual
requirements:
  commands: []              # e.g. [git, gh]
  network: none             # none | optional | required
capabilities:
  modifiesFiles: possible
  longRunning: false
  userInteraction: optional # none | optional | required (see below)
compatibility:
  agentSkills: true

userInteraction is a contract about substantive questions, not tool permission prompts:

• none: the skill is expected to complete without asking the user workflow questions.
• optional: the skill may meet legitimate product, design, or decision ambiguity where the user's input improves the result.
• required: interacting with the user is the point of the skill.

The contract decides whether the project's question preference adds an overlay to the skill.

How a skill is installed

The published package is the source; what lands in .agents/skills/<id> is the rendered skill. When AgileFlow renders a skill, it:

1. leaves out evals/;
2. sets the frontmatter name to the install id;
3. adds a notice after the frontmatter:

   Copy<!-- Managed by AgileFlow.
   Run `agileflow fork <id>` before customizing this copy. -->

4. adds the question preference overlay to skills whose userInteraction is optional or required, when a preference is set;
5. translates activation: manual for every provider (see Providers).

The result is deterministic. The lockfile records both hashes: integrity for the source package and renderedHash for the rendered directory. AgileFlow can therefore tell exactly whether you edited a skill (the directory no longer matches renderedHash), and whether only the render inputs changed (same integrity, new rendering), in which case sync re-renders clean skills.

Automatic and manual skills

• auto: the provider may load the skill when a request matches its description (for example diagnosing-bugs for "the login page crashes").
• manual: the skill changes the style of the interaction (for example interviewing-requirements), so it loads only when you invoke it by name, such as /interviewing-requirements in Claude Code or $interviewing-requirements in Codex.

Versions

Skills use semantic versioning independently of the CLI: patch for wording and eval improvements, minor for new optional capability, major for a behavioral contract change. agileflow.yaml holds a range such as ^1, so major changes are never installed by surprise.

Packs

A pack is a named list of skills with version ranges. It has no runtime, hooks, or agents. agileflow add @agileflow/github adds each skill in the pack to agileflow.yaml individually; after that, the pack plays no further role.

Copyname: github
version: 1
skills:
  - "@agileflow/filing-pr@^1"
  - "@agileflow/babysitting-pr@^1"
  - "@agileflow/resolving-conflicts@^1"

The official skills and packs are listed in Official skills.

Unmanaged skills

Skills you write yourself in .agents/skills/ without adding them to agileflow.yaml are unmanaged. AgileFlow never modifies or deletes them, and list and check show them as "left untouched". To track one, register it in place with agileflow add ./.agents/skills/<name>; it becomes locally owned.