LearnNewsExamplesServices
Frontmatter
id9986
titledocs: add "Progressive Disclosure Skills" guide
stateClosed
labels
documentationenhancementai
assigneestobiu
createdAtApr 13, 2026, 8:51 PM
updatedAtApr 13, 2026, 9:14 PM
githubUrlhttps://github.com/neomjs/neo/issues/9986
authortobiu
commentsCount0
parentIssue9981
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtApr 13, 2026, 9:14 PM

docs: add "Progressive Disclosure Skills" guide

Closed v13.0.0/archive-v13-0-0-chunk-4 documentationenhancementai
tobiu
tobiu commented on Apr 13, 2026, 8:51 PM

Context

The Neo Agent OS uses a Progressive Disclosure pattern for agent skills — on-demand loaded instruction sets that minimize system prompt token bloat while giving agents specialized procedural knowledge. Seven skills exist today, but there is no documentation explaining:

  • What the skill pattern is and why it exists
  • How the three lifecycle skills compose into a workflow
  • How to create new skills
  • The token economics behind lazy loading vs. system prompt injection

Proposed Guide: learn/agentos/ProgressiveDisclosureSkills.md

Content Scope

  1. The Progressive Disclosure Pattern — YAML frontmatter contract, folder structure (SKILL.md, references/, assets/), trigger-based activation
  2. Token Economics — Why skills exist: system prompt budget. Loading a 4K-token workflow guide on-demand vs. bloating every session with all 7 skill payloads
  3. The Lifecycle Triad — How ticket-intake → pull-request → pr-review compose:
    • ticket-intake: Pre-Execution Reflection Gate (validation sweep, ROI calculation, rejection protocol)
    • pull-request: Post-Implementation Gate ("Stepping Back" reflection, branch mandate, Conventional Commits, state handoff)
    • pr-review: Quality Gate (evaluation metrics, graph ingestion tags, LGTM/Required Actions)
  4. Tactical Skills — neural-link (live inspection), unit-test (Playwright integration)
  5. The Meta-Skillcreate-skill bootstraps new skills with correct structure
  6. How Skills Compose with AGENTS.md — Skills are invoked by mandate rules in the root system prompt. The system prompt says when to invoke; the skill says how to execute.
  7. Adding New Skills — Step-by-step via the create-skill skill

Skill Inventory

Skill Type Purpose
ticket-intake Lifecycle Pre-execution validation gate
pull-request Lifecycle Post-implementation reflection + PR creation
pr-review Lifecycle Structured quality evaluation
neural-link Tactical Live application inspection sequences
unit-test Tactical Playwright test authoring patterns
ideation-sandbox Creative GitHub Discussion brainstorming
create-skill Meta Skill authoring guide

Registration

  • Add to learn/tree.json under Agent OS
  • Cross-link from Swarm Intelligence (execution phase)
  • Cross-link from Strategic Workflows (skill invocation patterns)

Acceptance Criteria

  • Guide created at learn/agentos/ProgressiveDisclosureSkills.md
  • Registered in tree.json
  • Cross-linked from Swarm Intelligence and Strategic Workflows
  • CodebaseOverview cross-reference updated

A2A Context

  • Parent: #9981 (Architecture formalization epic)
  • Sibling: #9983 (Swarm Intelligence — completed, PR #9984)
  • Sibling: Dream Pipeline ticket (created in same session)
  • Origin Session: 70334eab-72c9-44a6-8f48-0b6a96604f49
tobiu added the documentation label on Apr 13, 2026, 8:51 PM
tobiu added the enhancement label on Apr 13, 2026, 8:51 PM
tobiu added the ai label on Apr 13, 2026, 8:51 PM
tobiu added parent issue #9981 on Apr 13, 2026, 8:51 PM
tobiu assigned to @tobiu on Apr 13, 2026, 9:09 PM
tobiu referenced in commit db7121f - "docs: Author Progressive Disclosure Skills guide and register cross-links (#9986)" on Apr 13, 2026, 9:11 PM
tobiu cross-referenced by PR #9988 on Apr 13, 2026, 9:12 PM
tobiu referenced in commit 28f5557 - "docs: Author Progressive Disclosure Skills guide and register cross-links (#9986) (#9988)" on Apr 13, 2026, 9:14 PM
tobiu closed this issue on Apr 13, 2026, 9:14 PM
tobiu cross-referenced by PR #9989 on Apr 13, 2026, 9:16 PM
tobiu cross-referenced by PR #9990 on Apr 14, 2026, 12:16 AM