coilyco-flight-deck/agentic-os

Watch

Restore aosguard skill generation: one skill per wrapped entity, plus a concept skill #1028

New issue

Closed

opened 2026-08-12 17:26:51 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-12 17:26:51 +00:00

Member

Outcome

An agent session can discover what aosguard offers at the moment it needs it, without already knowing aosguard exists.

The incident that prompted this

During the 2026-08-12 coilyco-gaming/sirens-echo session I needed to reopen two Forgejo issues. The Forgejo MCP grants close, comment, create, and edit-title-or-body, with reopen absent. I concluded reopen was denied by absence and wrote that into three ticket comments as a Kai-or-ops action.

It was not denied. aosguard ops forgejo issue reopen exists and resolves to PATCH /repos/{owner}/{repo}/issues/{index}. Kai pointed it out.

The failure was retrieval, not discovery. coilyco-bridge/deploy/AGENTS.md states plainly that operator verbs live in AOSguard as aosguard ops <area>, and I had that file loaded. I read the sentence and did not recall it at the moment an MCP tool search came back empty. That distinction decides the shape below.

Recommended shape

One generated skill per wrapped entity, plus one hand-written concept skill.

The areas today: actions, aws, forgejo, forgejo-admin, forgejo-storage, kubectl, signoz, tailscale.

Why per-entity rather than one large skill

It matches the retrieval cue. A single aosguard skill only loads if the agent already suspects it needs aosguard, which is precisely what fails. aosguard-forgejo matches against the entity the agent is demonstrably working with all session.
Relevance. Eight areas in one document means most of it is noise for any given task. Tailscale verbs do not help while filing issues.
Generation and drift are per-spec. One generator run per area, drift detected per file, rather than a whole document regenerating on any change to any area.
It is the pattern already chosen. coilyco-gaming/sirens-echo#122 settled the same question for MCP guardfiles the same day: per-server generated skills plus one hand-written concept skill. Consistency is worth real money here.

Keep forgejo, forgejo-admin, and forgejo-storage as three skills rather than merging them. The split is presumably an authority boundary, and collapsing it in documentation would blur exactly what these skills exist to make legible.

What the concept skill must carry, since no spec contains it

Two things, both hand-written because they are not derivable from any single area's spec:

The rule that would have prevented the incident. When an expected verb is absent from an MCP surface, check whether the operator surface has it before concluding it is denied.
What aosguard is not. aosguard is generated by specgen in this repository. It is not ward, and its behaviour implies nothing about ward's grammar or cli-guard's method table.

That second point is not hypothetical caution. In the same session I filed coilyco-flight-deck/ward#1656 citing aosguard's method resolution as evidence about ward's internals, having inferred shared machinery from shared vocabulary — both carry "guard", both expose "verbs", and deploy/AGENTS.md introduces them in one paragraph as two halves of a single gating story. That claim was wrong and had to be withdrawn. A negative fact of this kind is exactly what a generated skill will never contain.

"Add (back)"

The framing of this request implies the capability existed before and was removed. Find out why before rebuilding it. If it was dropped for staleness, generation-on-build addresses that; if it was dropped for listing clutter, per-entity makes that worse rather than better and the decision deserves revisiting on its own terms.

Complete when

Each wrapped area has a generated skill describing its verbs, regenerated from the spec rather than hand-maintained.
A concept skill states what aosguard is, what it is not, and when to reach for it over an MCP surface.
Regeneration is verified, so a spec change that does not refresh the skills fails rather than going quietly stale.
Adding a new wrapped area produces its skill without a hand edit.

Open question for Kai

Kai raised one-big-skill versus one-per-entity and has not settled it. The recommendation above is mine, argued from the failure mode rather than from taste. The counter-argument for a single skill is listing economy — eight entries versus one — and it is not a strong one at this scale.

## Outcome An agent session can discover what `aosguard` offers at the moment it needs it, without already knowing aosguard exists. ## The incident that prompted this During the 2026-08-12 `coilyco-gaming/sirens-echo` session I needed to reopen two Forgejo issues. The Forgejo MCP grants close, comment, create, and edit-title-or-body, with reopen absent. I concluded reopen was denied by absence and wrote that into three ticket comments as a Kai-or-ops action. It was not denied. `aosguard ops forgejo issue reopen` exists and resolves to `PATCH /repos/{owner}/{repo}/issues/{index}`. Kai pointed it out. **The failure was retrieval, not discovery.** `coilyco-bridge/deploy/AGENTS.md` states plainly that operator verbs live in AOSguard as `aosguard ops <area>`, and I had that file loaded. I read the sentence and did not recall it at the moment an MCP tool search came back empty. That distinction decides the shape below. ## Recommended shape **One generated skill per wrapped entity, plus one hand-written concept skill.** The areas today: `actions`, `aws`, `forgejo`, `forgejo-admin`, `forgejo-storage`, `kubectl`, `signoz`, `tailscale`. ### Why per-entity rather than one large skill * **It matches the retrieval cue.** A single `aosguard` skill only loads if the agent already suspects it needs aosguard, which is precisely what fails. `aosguard-forgejo` matches against the entity the agent is demonstrably working with all session. * **Relevance.** Eight areas in one document means most of it is noise for any given task. Tailscale verbs do not help while filing issues. * **Generation and drift are per-spec.** One generator run per area, drift detected per file, rather than a whole document regenerating on any change to any area. * **It is the pattern already chosen.** `coilyco-gaming/sirens-echo#122` settled the same question for MCP guardfiles the same day: per-server generated skills plus one hand-written concept skill. Consistency is worth real money here. Keep `forgejo`, `forgejo-admin`, and `forgejo-storage` as three skills rather than merging them. The split is presumably an authority boundary, and collapsing it in documentation would blur exactly what these skills exist to make legible. ### What the concept skill must carry, since no spec contains it Two things, both hand-written because they are not derivable from any single area's spec: 1. **The rule that would have prevented the incident.** When an expected verb is absent from an MCP surface, check whether the operator surface has it before concluding it is denied. 2. **What aosguard is not.** aosguard is generated by specgen in this repository. It is **not** ward, and its behaviour implies nothing about ward's grammar or cli-guard's method table. That second point is not hypothetical caution. In the same session I filed `coilyco-flight-deck/ward#1656` citing aosguard's method resolution as evidence about ward's internals, having inferred shared machinery from shared vocabulary — both carry "guard", both expose "verbs", and `deploy/AGENTS.md` introduces them in one paragraph as two halves of a single gating story. That claim was wrong and had to be withdrawn. A negative fact of this kind is exactly what a generated skill will never contain. ## "Add (back)" The framing of this request implies the capability existed before and was removed. **Find out why before rebuilding it.** If it was dropped for staleness, generation-on-build addresses that; if it was dropped for listing clutter, per-entity makes that worse rather than better and the decision deserves revisiting on its own terms. ## Complete when * Each wrapped area has a generated skill describing its verbs, regenerated from the spec rather than hand-maintained. * A concept skill states what aosguard is, what it is not, and when to reach for it over an MCP surface. * Regeneration is verified, so a spec change that does not refresh the skills fails rather than going quietly stale. * Adding a new wrapped area produces its skill without a hand edit. ## Open question for Kai Kai raised one-big-skill versus one-per-entity and has not settled it. The recommendation above is mine, argued from the failure mode rather than from taste. The counter-argument for a single skill is listing economy — eight entries versus one — and it is not a strong one at this scale.

coilyco-ops commented

2026-08-12 17:28:25 +00:00

Author

Member

Decision: one skill per wrapped entity

Direction from Kai, 2026-08-12 session. The open question at the bottom of this issue is closed — per-entity, not one combined aosguard skill.

So the shape to build is the one recommended above: one generated skill per area, from actions, aws, forgejo, forgejo-admin, forgejo-storage, kubectl, signoz, tailscale, with forgejo, forgejo-admin, and forgejo-storage staying separate rather than merged.

Two things this decision does not settle

The concept skill. Kai chose between the two options I posed, and the hand-written concept skill was an addition to either. I am treating it as still in scope unless she says otherwise, because it carries the two facts no generated skill can contain: the rule about checking the operator surface before concluding a verb is denied, and the statement that aosguard is not ward. The incident this issue documents was caused by the absence of exactly those, not by the absence of a verb list. Say so if it should be dropped.

Why it was removed before. Unchanged from the body: "add (back)" implies this existed and was taken out. Worth finding the reason before rebuilding. If it went for listing clutter, per-entity is the direction that makes that worse, and the decision deserves a second look with that history in hand rather than being re-litigated after eight skills land.

Priority

Not stated. This is tooling rather than demo-track work, and the August 19 stream owns the week — treat it as unscheduled unless Kai says otherwise.

## Decision: one skill per wrapped entity Direction from Kai, 2026-08-12 session. The open question at the bottom of this issue is closed — **per-entity**, not one combined aosguard skill. So the shape to build is the one recommended above: one generated skill per area, from `actions`, `aws`, `forgejo`, `forgejo-admin`, `forgejo-storage`, `kubectl`, `signoz`, `tailscale`, with `forgejo`, `forgejo-admin`, and `forgejo-storage` staying separate rather than merged. ## Two things this decision does not settle **The concept skill.** Kai chose between the two options I posed, and the hand-written concept skill was an addition to either. I am treating it as still in scope unless she says otherwise, because it carries the two facts no generated skill can contain: the rule about checking the operator surface before concluding a verb is denied, and the statement that aosguard is not ward. The incident this issue documents was caused by the absence of exactly those, not by the absence of a verb list. Say so if it should be dropped. **Why it was removed before.** Unchanged from the body: "add (back)" implies this existed and was taken out. Worth finding the reason before rebuilding. If it went for listing clutter, per-entity is the direction that makes that worse, and the decision deserves a second look with that history in hand rather than being re-litigated after eight skills land. ## Priority Not stated. This is tooling rather than demo-track work, and the August 19 stream owns the week — treat it as unscheduled unless Kai says otherwise.

coilyco-ops added the

labels

2026-08-17 02:36:23 +00:00

coilyco-ops referenced this issue

2026-08-22 20:54:50 +00:00

Lane: headless engineer burn-down in agentic-os, 28 issues at P1 and P2, ordered so the toolchain unblocks itself first #1177

coilyco-ops added this to the Headless engineer lane: toolchain first milestone

2026-08-22 20:58:33 +00:00

coilyco-ops commented

2026-08-23 00:41:56 +00:00

Author

Member

Director prep. This issue asks "find out why before rebuilding it" and refuses to guess. I found it, and the answer bears directly on the recommended shape.

Why it was removed

f2ca3434  2026-07-25 19:55  kai  feat: generate aosguard skill
          + .agents/generated/aosguard/SKILL.md                 (12 lines)
          + .agents/generated/aosguard/references/commands.yaml (1399 lines)

d3ca47c4  2026-07-25 20:50  kai  fix: keep generated skill out of context catalog
          - both files

Fifty-five minutes. Not staleness, and not a considered retirement. The reason is in the subject line: the generated skill entered the context catalog and was pulled back out. The same commit reworked docs/aos-cli.md, added docs/aos-context-bundle.md, and moved the skill to ignored dist/skills/, so the capability was relocated rather than abandoned - it ships to the selected agent's skill root at launch instead of living in the tracked catalog.

The original was one skill with a 1399-line reference file, which is what made it a context-catalog problem.

What that does to the recommended shape

This issue names the branch itself:

If it was dropped for staleness, generation-on-build addresses that; if it was dropped for listing clutter, per-entity makes that worse rather than better and the decision deserves revisiting on its own terms.

It is the second one. And per-entity is ten entries now, not the eight this issue lists:

actions  aws  forgejo  forgejo-admin  forgejo-storage
kubectl  redis  signoz  tailscale  telegram

redis and telegram arrived after filing. So the proposal turns one catalog entry that was removed for being too much into ten, against a repo that currently tracks 15 skills total. Ten aosguard entries would be forty percent of the catalog.

By this issue's own test, that is the case where the decision deserves revisiting rather than the case where generation-on-build settles it.

What survives, and it is the valuable half

The retrieval diagnosis is right and is not affected by any of the above. I hit the same failure today: I went looking for a branch-protection verb, found none mounted, and had to walk --help three levels to establish that. Earlier I concluded Actions logs were unreachable because #970 said so, when aosguard ops forgejo action-run logs answers fine. Both are the retrieval problem, not a discovery problem.

The concept skill is the part that addresses it, and this issue argues that better than the per-entity part:

the rule that an absent MCP verb is not a denial until the operator surface is checked
aosguard is not ward, and its behaviour implies nothing about ward's internals

Neither is derivable from a spec, both are hand-written, and one skill is not a catalog problem.

Suggested

Take the concept skill now. It is one entry, it carries the two negative facts, and it fixes the incident this issue was filed for.
Reopen per-entity as its own decision, with the context-catalog cost stated, since d3ca47c4 is evidence that this exact cost has already been paid once and reversed.
If per-entity does happen, the ignored dist/skills/ path that d3ca47c4 moved the original to may already be the right home, since it reaches the agent without entering the tracked catalog.

**Director prep. This issue asks "find out why before rebuilding it" and refuses to guess. I found it, and the answer bears directly on the recommended shape.** ## Why it was removed ``` f2ca3434 2026-07-25 19:55 kai feat: generate aosguard skill + .agents/generated/aosguard/SKILL.md (12 lines) + .agents/generated/aosguard/references/commands.yaml (1399 lines) d3ca47c4 2026-07-25 20:50 kai fix: keep generated skill out of context catalog - both files ``` **Fifty-five minutes.** Not staleness, and not a considered retirement. The reason is in the subject line: the generated skill entered the context catalog and was pulled back out. The same commit reworked `docs/aos-cli.md`, added `docs/aos-context-bundle.md`, and moved the skill to ignored `dist/skills/`, so the capability was **relocated rather than abandoned** - it ships to the selected agent's skill root at launch instead of living in the tracked catalog. The original was one skill with a 1399-line reference file, which is what made it a context-catalog problem. ## What that does to the recommended shape This issue names the branch itself: > If it was dropped for staleness, generation-on-build addresses that; if it was dropped for **listing clutter**, per-entity makes that worse rather than better and the decision deserves revisiting on its own terms. It is the second one. And per-entity is **ten** entries now, not the eight this issue lists: ``` actions aws forgejo forgejo-admin forgejo-storage kubectl redis signoz tailscale telegram ``` `redis` and `telegram` arrived after filing. So the proposal turns one catalog entry that was removed for being too much into ten, against a repo that currently tracks **15 skills total**. Ten aosguard entries would be forty percent of the catalog. By this issue's own test, that is the case where the decision deserves revisiting rather than the case where generation-on-build settles it. ## What survives, and it is the valuable half The retrieval diagnosis is right and is not affected by any of the above. I hit the same failure today: I went looking for a branch-protection verb, found none mounted, and had to walk `--help` three levels to establish that. Earlier I concluded Actions logs were unreachable because `#970` said so, when `aosguard ops forgejo action-run logs` answers fine. Both are the retrieval problem, not a discovery problem. **The concept skill is the part that addresses it**, and this issue argues that better than the per-entity part: * the rule that an absent MCP verb is not a denial until the operator surface is checked * aosguard is not ward, and its behaviour implies nothing about ward's internals Neither is derivable from a spec, both are hand-written, and one skill is not a catalog problem. ## Suggested * **Take the concept skill now.** It is one entry, it carries the two negative facts, and it fixes the incident this issue was filed for. * **Reopen per-entity as its own decision**, with the context-catalog cost stated, since `d3ca47c4` is evidence that this exact cost has already been paid once and reversed. * If per-entity does happen, the ignored `dist/skills/` path that `d3ca47c4` moved the original to may already be the right home, since it reaches the agent without entering the tracked catalog.

coilyco-ops referenced this issue

2026-08-23 00:47:48 +00:00

Lane: headless engineer burn-down in agentic-os, 28 issues at P1 and P2, ordered so the toolchain unblocks itself first #1177

coilyco-ops referenced this issue

2026-08-23 00:49:30 +00:00

Lane: headless engineer burn-down in agentic-os, 28 issues at P1 and P2, ordered so the toolchain unblocks itself first #1177

coilyco-ops referenced this issue from a commit

2026-08-23 01:17:39 +00:00

feat(aosguard): one generated skill per wrapped area, plus a concept skill (#1028)

coilyco-ops referenced this issue from a pull request that will close it,

2026-08-23 01:17:59 +00:00

feat(aosguard): one generated skill per wrapped area, plus a concept skill (#1028) #1219