library-editing

Library Editing

Put a component where this project reads it, and wire it to the role that needs it.

When to Use

Two neighbours own the steps on either side of this one. Writing the component — its structure, its description, its validation scenario — is skill-template, and deciding that prose is the right mechanism at all is prompt-authoring. Proving the wiring worked is composition-verification; this skill stops at "the edit is made", it does not certify it arrived.

Procedure

1. Put the component in a root this project reads

Your own roots are flat — no layer directory under them:

<project>/libraries/{roles,traits,rules,skills}/<name>/     # project-local
~/.ai-hats/{roles,traits,rules,skills}/<name>/              # user-wide

Any further root listed in ~/.ai-hats/library_paths.yaml or under library_paths: in the project's ai-hats.yaml has the same shape. ~/.ai-hats/core/rules/foo/ resolves to nothing — the core/ / usage/ split exists only inside the shipped library. Roots layer last-wins, so a component whose name matches a shipped one overrides it.

Start a new component from a shipped one, not from memory. A rule is a bare rule.md; a skill is a SKILL.md (skill-template owns its shape); a trait is a config.yaml with name, composition (traits / rules / skills / apps) and injection; a role is that same config.yaml plus priorities, and is the usual unit of work in a project of your own. ai-hats list roles (and list traits / list rules / list skills) names the shipped ones — copy the closest and edit it, so the keys are right before the content is. ai-hats config status then tags each component of the active role with the layer it resolved from (built-in / global / project), which is how you confirm yours won.

2. Wire it — persistently, or for one session

Persistent, written into ai-hats.yaml (project) or ~/.ai-hats/customizations.yaml (global):

ai-hats config customize <role> --add-trait <name> --project
ai-hats config customize <role> --add-skill <name> --remove-skill <name> --global
ai-hats config customize <role> --injection-append "<text>"

Ephemeral, for this launch only — a role spec, and nothing is written:

ai-hats -r "dev-python + skill-engineer"           # quotes when spaces are used
ai-hats -r dev-python+skill-engineer               # compact form, same thing
ai-hats -r "dev-python - dev::shell + skill-engineer"

Reach for the role spec when you are testing whether a component changes behaviour at all. Persist it once the answer is yes — a spec nobody wrote down is a result nobody can reproduce.

3. The + / - grammar, and the two traps in it

The base role comes first, then operations. Both operators take exactly one component name.

• - is an operator only when surrounded by spaces. trait-base is one identifier; - trait-base removes it. A hyphenated name never splits.
• A removal resolves against the COMPOSED set, not against the role's own declaration: you can drop a rule a trait brought in, without editing the trait.
• A repeated operand, or a trailing + with nothing after it, is refused with a parse error rather than silently ignored.

The spec becomes a third overlay layer — [global, project, runtime] — so it wins over both persistent layers for that session.

4. Know when the edit takes effect

There is no sync command. Roles are composed fresh at every launch, so an edit to a component body, to ai-hats.yaml, or to a customization is live for the next session — including a component you just wrote by hand. ai-hats self init validates the config and refreshes the project scaffold; it is not how a composition change lands.

One exception. A skill's git gates are resolved at commit time from the composed role, but the .githooks/<event> dispatcher that runs them is a stub written only by ai-hats init / self init / self update / the first interactive launch — config customize never writes one. A gate under an event whose stub exists is live at the next commit; a gate on an event with no stub yet is inert until you run ai-hats self init once.

Never hand-copy component files into a provider's own directory. Those trees are materialized per session from the resolved library; a hand-made copy drifts from the source and never composes.

5. Then prove it arrived

An edit that the composer never resolved leaves the file looking perfect. Go to composition-verification before reporting the change landed.

Completion

• The component sits in a root this project actually reads.
• It is wired either persistently (and the command is recorded) or by an explicit role spec for a deliberately ephemeral test.
• The next launch is understood to be when it takes effect.
• Arrival is confirmed through composition-verification, not assumed.

Validation scenario (RED). An agent asked to give a working role the authoring craft writes a trait into ~/.ai-hats/core/traits/, mirroring the shipped library's layer layout. The path resolves to nothing, the composer reports no error, and the role is unchanged — while the file on disk looks exactly right. Step 1 prevents it; step 5 catches it if step 1 was skipped.

Anti-Patterns

• Mirroring the shipped core/ / usage/ layers inside your own root.
• Testing a component by editing the shipped library instead of overriding it by name from your own root.
• Leaving a promising role spec ephemeral, so the result cannot be reproduced.
• Writing - trait-base as -trait-base and wondering why the parse failed.
• Copying skill files into the provider's directory by hand.