@jaybeeuu/agent-cortex 1.20.0

package/skills/productivity/validate-agent-dir/scripts/validate-agent-dir.ts

@@ -0,0 +1,127 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface Frontmatter {
+  name: string;
+  description: string;
+  tools: string[];
+  model?: string;
+  argumentHint?: string;
+  [key: string]: unknown;
+}
+
+export interface AgentDir {
+  name: string;
+  agentMdPath: string;
+  harnesses: Map<string, { frontmatter: Frontmatter; sections: string[] }>;
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  errors: string[];
+}
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const REQUIRED_FIELDS = ["name", "description", "tools"] as const;
+const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"] as const;
+
+// ─── Validation ───────────────────────────────────────────────────────────────
+
+export function validateFrontmatter(fm: unknown): ValidationResult {
+  const errors: string[] = [];
+
+  if (typeof fm !== "object" || fm === null) {
+    return { ok: false, errors: ["frontmatter must be an object"] };
+  }
+
+  const record = fm as Record<string, unknown>;
+
+  // Check required fields
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in record)) {
+      errors.push(`missing required field: ${field}`);
+    }
+  }
+
+  // Validate name
+  if (typeof record.name === "string" && record.name.trim() === "") {
+    errors.push("name must not be empty");
+  }
+
+  // Validate description
+  if (typeof record.description === "string" && record.description.trim() === "") {
+    errors.push("description must not be empty");
+  }
+
+  // Validate tools
+  if ("tools" in record) {
+    if (!Array.isArray(record.tools)) {
+      errors.push("tools must be an array");
+    } else if (record.tools.length === 0) {
+      errors.push("tools must not be empty");
+    } else if (!record.tools.every((t) => typeof t === "string")) {
+      errors.push("tools must be an array of strings");
+    }
+  }
+
+  // Check for unknown fields
+  const knownFields = new Set([...REQUIRED_FIELDS, ...KNOWN_OPTIONAL_FIELDS]);
+  for (const key of Object.keys(record)) {
+    if (!knownFields.has(key as any)) {
+      errors.push(`unknown field: ${key}`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateAgentDir(agentDirPath: string): ValidationResult {
+  const errors: string[] = [];
+
+  // Check agent.md exists
+  const agentMdPath = join(agentDirPath, "agent.md");
+  if (!existsSync(agentMdPath)) {
+    errors.push("missing agent.md");
+  }
+
+  // Check for at least one harness subdirectory with frontmatter.json
+  if (!existsSync(agentDirPath)) {
+    return { ok: false, errors: ["agent directory does not exist"] };
+  }
+
+  const entries = readdirSync(agentDirPath);
+  const harnessDirs = entries.filter((entry) => {
+    const fullPath = join(agentDirPath, entry);
+    return statSync(fullPath).isDirectory() && entry !== "node_modules";
+  });
+
+  if (harnessDirs.length === 0) {
+    errors.push("no harness subdirectories found (need at least one with frontmatter.json)");
+  }
+
+  // Validate each harness directory
+  for (const harnessDir of harnessDirs) {
+    const frontmatterPath = join(agentDirPath, harnessDir, "frontmatter.json");
+    if (!existsSync(frontmatterPath)) {
+      continue; // Skip directories without frontmatter.json
+    }
+
+    try {
+      const content = readFileSync(frontmatterPath, "utf-8");
+      const fm = JSON.parse(content);
+      const result = validateFrontmatter(fm);
+      if (!result.ok) {
+        for (const err of result.errors) {
+          errors.push(`${harnessDir}/frontmatter.json: ${err}`);
+        }
+      }
+    } catch (e) {
+      errors.push(`${harnessDir}/frontmatter.json: invalid JSON`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/skills/productivity/write-a-skill/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: write-a-skill
+description: "Create new agent skills with canonical anatomy, progressive disclosure, and reusable helpers. Use when the user says \"write a skill\", \"create a skill\", \"make me a skill\", or \"new skill\"."
+---
+
+# Write a Skill
+
+## When to use
+
+- The user asks to create a brand-new skill from scratch.
+- The user says "write a skill", "create a skill", "make me a skill", or "new skill".
+- A new capability needs to be packaged as a reusable skill with a deterministic workflow.
+
+## When NOT to use
+
+- Refactoring an existing skill to the anatomy template — use `refactor-skill` instead.
+- Minor copy-editing or typo fixes that do not need a full creation workflow.
+- Skills that are not intended to be reusable (one-off scripts, ad-hoc instructions).
+
+## Workflow
+
+### 1. Gather requirements
+
+Clarify the skill goal with the user. Ask what triggers users would actually say, what output the skill produces, and whether any deterministic helper scripts are needed.
+
+### 2. Draft from the anatomy template
+
+Read `docs/skills/skill-anatomy.md` as the source of truth. Follow the annotated template for section ordering and front-matter fields. Target ~150 lines for `SKILL.md` but stay under the 150-line hard cap.
+
+### 3. Apply voice and tone rules
+
+Write the body in imperative second-person: "Run X", "Check Y", "Report Z". Prefer positive framing over prohibitions. Add a one-sentence rationale for any non-obvious rule so the model can generalise from it. Avoid ALL-CAPS emphasis.
+
+### 4. Define front-matter fields
+
+Required: `name` (kebab-case), `description` (two sentences, second starts with "Use when", includes 2-4 quoted trigger phrases). Optional: `argument-hint`, `disable-model-invocation` when the skill requires them.
+
+### 5. Split supporting docs when appropriate
+
+Move long examples to `EXAMPLES.md`, output formats to `FORMAT.md`, and infrequently-needed edge cases to `REFERENCE.md`. Keep `SKILL.md` focused on the primary workflow.
+
+### 6. Run the review checklist
+
+Verify the final document against the verification checklist below before finishing.
+
+## Red Flags
+
+- **Writing without reading the anatomy template first** — The template defines section ordering, voice rules, and inclusion criteria for optional sections. Guessing leads to drift.
+- **Padding sections with generic content** — Every section must earn its place with content specific to the skill's purpose. Copying generic filler from the template placeholder text produces a weak skill.
+- **Skipping the trigger-phrase interview** — The description's trigger phrases are the main routing signal for the skill. Guessing what users say rather than asking produces a skill that is hard to invoke.
+
+## Cross-skill references
+
+- Use `refactor-skill` when the task is upgrading an existing skill rather than creating a new one.
+- Run `style-code` after writing to check that code conventions in any example snippets or bundled scripts are consistent.
+- Run `review-security` before committing to check for leaked secrets in examples or documentation.
+
+## Examples
+
+Input: "Write a skill that scans git diffs for secrets"
+Output: A new `skills/review-security/SKILL.md` with front matter, When to use, Workflow, and Verification checklist following the anatomy template.
+
+## Verification checklist
+
+- [ ] `docs/skills/skill-anatomy.md` was read before drafting
+- [ ] Required sections present: `## When to use`, `## Workflow`, `## Verification checklist`
+- [ ] Section order follows the anatomy template
+- [ ] Description uses two-sentence format with 2-4 quoted trigger phrases
+- [ ] Body uses imperative second-person voice with positive framing
+- [ ] Rationale sentences added for non-obvious rules
+- [ ] No ALL-CAPS emphasis
+- [ ] `SKILL.md` ≤ 150 lines (`wc -l skills/<name>/SKILL.md`)
+- [ ] Supporting docs split by purpose when `SKILL.md` exceeds ~150 lines
+- [ ] Cross-skill references point to `refactor-skill` for upgrades where relevant

package/skills/review/maintain-agent-docs/REFERENCE.md

@@ -0,0 +1,246 @@
+# Reference: Maintain Agent Docs
+
+Detailed templates, examples, and anti-patterns for AGENTS.md and docs/ maintenance.
+
+## AGENTS.md Template
+
+```markdown
+# AGENTS.md
+
+Instructions for agents working on this repository.
+
+## What This Project Is
+
+[One sentence describing the project's purpose.]
+
+## Commands
+
+[List exact commands agents will need. Put these early — agents perform best when
+they know what to run.]
+
+| Task | Command |
+|------|---------|
+| Install | `npm install` |
+| Build | `npm run build` |
+| Test (all) | `npm test` |
+| Test (single) | `npm test -- --grep "pattern"` |
+| Lint | `npm run lint` |
+| Type check | `npx tsc --noEmit` |
+
+## Project Structure
+
+[Directory map with purposes. Focus on stable structure, not individual files.]
+
+## Code Style
+
+[Conventions with concrete examples. Show a "good" snippet, not just rules.]
+
+## Testing
+
+[Frameworks, coverage expectations, where tests live, naming conventions.]
+
+## Git Workflow
+
+[Branch naming, commit conventions, PR process.]
+
+## Boundaries
+
+[What agents must NOT do. Be explicit.]
+
+- Never modify files in `vendor/` or `dist/`
+- Never commit secrets or credentials
+- Never delete migration files
+```
+
+## Section-by-Section Guidance
+
+### Commands
+
+The highest-impact section. Put it near the top.
+
+- Include exact flags and options, not just the base command
+- Show the single-file variants (e.g. how to run one test, lint one file)
+- If commands vary by environment, show a table
+
+**Good:**
+
+```markdown
+| Task | Command |
+|------|---------|
+| Test all | `pytest -v --tb=short` |
+| Test one file | `pytest tests/test_auth.py -v` |
+| Test with coverage | `pytest --cov=src --cov-report=term-missing` |
+```
+
+**Bad:**
+
+```markdown
+Run `pytest` to test.
+```
+
+### Project Structure
+
+Show what each top-level directory is for. Avoid listing every file — the structure
+changes; the purposes don't.
+
+**Good:**
+
+```markdown
+src/
+├── api/         # HTTP handlers and route definitions
+├── domain/      # Business logic, pure functions
+├── infra/       # Database, external service clients
+└── shared/      # Cross-cutting utilities and types
+```
+
+**Bad:**
+
+```markdown
+src/
+├── api/
+│   ├── routes.ts
+│   ├── middleware.ts
+│   ├── auth.ts
+│   ├── users.ts
+│   └── ...
+```
+
+### Boundaries
+
+Frame as "never" rules. Agents follow prohibitions more reliably than preferences.
+
+- Start each rule with "Never" or "Do not"
+- Be specific about paths and actions
+- Explain why if the reason isn't obvious
+
+### Code Style
+
+Show, don't tell. A short before/after example communicates more than a list of rules.
+
+**Good:**
+
+```markdown
+## Naming
+
+```ts
+// ✅ Use descriptive names; Boolean variables start with is/has/should
+const isAuthenticated = true;
+const hasPermission = checkAccess(user, resource);
+
+// ❌ Avoid abbreviations and generic names
+const auth = true;
+const flag = check(u, r);
+`` `
+```
+
+**Bad:**
+
+```markdown
+## Naming
+
+- Use descriptive names
+- Boolean variables should start with is, has, or should
+- Avoid abbreviations
+```
+
+## docs/ Organisation
+
+Keep docs/ flat and purpose-driven:
+
+```
+docs/
+├── architecture.md     # System design, module boundaries, data flow
+├── decisions/          # ADRs (Architecture Decision Records)
+│   ├── 001-use-postgres.md
+│   └── 002-event-sourcing.md
+└── runbooks/           # Operational procedures
+    ├── deploy.md
+    └── incident-response.md
+```
+
+- Each file should have one clear purpose
+- Prefer updating an existing file over creating a new one
+- Link from AGENTS.md into docs/ for detail — don't duplicate
+
+## Anti-Patterns
+
+| Anti-pattern | Why it's harmful | Fix |
+|---|---|---|
+| **Listing every file** | Goes stale immediately; wastes tokens | Describe directory purposes instead |
+| **"Be helpful"** | Too vague to change agent behaviour | Give specific instructions with examples |
+| **Duplicating README content** | Two sources of truth that drift apart | Reference README, don't copy it |
+| **No commands section** | Agents guess at commands, often wrong | Add exact commands with flags |
+| **Aspirational docs** | Describes what you wish the code did | Document current reality only |
+| **Monolithic AGENTS.md** | Everything in one file; bloats every conversation | Push detail to scoped files and docs/ |
+| **Kitchen-sink instructions** | Agent processes every line, even irrelevant ones | Only include what the code can't answer |
+| **Burying critical commands** | "Lost in the Middle" — attention drops with position | Put commands and boundaries first |
+
+## Progressive Disclosure In Practice
+
+### Why it matters
+
+AGENTS.md is loaded into every agent conversation. Benchmarks show:
+
+- Bloated context files reduce task success by 2-3% while increasing inference cost 20%+ (ETH Zurich, ICSE 2026)
+- Instructions at position 10 in a config file receive 27% less attention than position 1 (Stanford, "Lost in the Middle")
+- Agents process every instruction dutifully — even irrelevant ones — wasting attention budget
+
+**Treat AGENTS.md as a cache for ambiguity resolution**, not a comprehensive manual.
+
+### The three-tier hierarchy
+
+```
+Tier 1: AGENTS.md (root)                    ← always loaded
+  What the project is, build/test/lint commands, structure overview,
+  code style summary, git workflow, hard boundaries.
+  Target: under 100 lines.
+
+Tier 2: .instructions.md (scoped)           ← loaded when working in that path
+  Path-specific conventions, module-specific boundaries,
+  framework-specific patterns.
+  Example: src/api/.instructions.md with API-specific conventions.
+
+Tier 3: docs/ (on-demand)                   ← agent reads when needed
+  Architecture docs, ADRs, runbooks, detailed design documents.
+  Referenced from AGENTS.md but not inlined.
+```
+
+### Scoped `.instructions.md` example
+
+```markdown
+---
+applyTo: "src/api/**"
+---
+
+# API Module Instructions
+
+- All handlers return standardised error objects (see docs/architecture.md)
+- Use Zod for request validation; never trust raw input
+- Integration tests live alongside the handler files as `*.integration.test.ts`
+```
+
+### The audit question
+
+For every line in AGENTS.md, ask:
+
+> "Could an agent infer this by reading the code or running a command?"
+
+If yes — remove it. If it only applies to one area — move it to a scoped file. Only what resolves genuine ambiguity earns a place in the root file.
+
+### Sizing guide
+
+| File | Target | Rationale |
+|---|---|---|
+| AGENTS.md | < 100 lines | Always loaded; every line costs attention |
+| Scoped .instructions.md | < 50 lines each | Loaded per-path; keep focused |
+| docs/ files | No hard limit | Read on demand; depth is fine |
+
+## Drift Detection Heuristic
+
+When auditing, look for these signals that docs have drifted:
+
+1. **Commands that fail** — try running them; if they error, the docs are stale
+2. **Directories that don't exist** — referenced paths that have been renamed or removed
+3. **Technologies not in package.json/requirements.txt** — docs mention tools the project no longer uses
+4. **Missing new tooling** — project has added linters, formatters, or CI steps not reflected in docs
+5. **Contradictions** — AGENTS.md says one thing, a nested .instructions.md says another

package/skills/review/maintain-agent-docs/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: maintain-agent-docs
+description: "Audit and update AGENTS.md and docs/ to keep agent-consumed documentation accurate, specific, and drift-free. Use when user wants to review, update, or improve AGENTS.md, docs/, or other documentation that agents rely on."
+---
+
+# Maintain Agent Docs
+
+Keep AGENTS.md and docs/ accurate, specific, and in sync with the codebase. Also invoke the `style-documentation` skill — its philosophy governs what to document and when.
+
+## When To Use
+
+- After significant codebase changes (new tooling, renamed modules, changed workflows)
+- When agents are producing poor results due to stale or missing instructions
+- Periodic maintenance — or after major releases
+- When onboarding a new repo to agent-assisted workflows
+
+## Process
+
+### 1. Audit
+
+Scan the repository to build a picture of the current state:
+
+- Read existing AGENTS.md (root and any nested copies) and docs/ contents
+- Compare instructions against actual codebase: directory structure, runnable commands, conventions, tooling
+- Check context budget: is AGENTS.md under 100 lines? Is detail pushed to scoped files?
+- Flag issues, grouped by type:
+  - **Drift** — instructions that no longer match the codebase
+  - **Gaps** — important context missing entirely
+  - **Vagueness** — instructions too generic to be actionable
+  - **Bloat** — content that belongs in scoped files or docs/, not the root
+
+Present findings as a numbered list. Do NOT fix anything yet.
+
+### 2. Propose changes
+
+For each issue, propose a specific fix. Present all proposals for user review before applying.
+
+### 3. Apply changes
+
+After approval, update files following the quality principles below.
+
+## Context Budget
+
+AGENTS.md is injected into every agent conversation. Every line costs tokens and attention. Research shows bloated context files *reduce* task success while increasing cost 20%+ (ETH Zurich, ICSE 2026). Instructions buried past the first few sections receive significantly less attention ("Lost in the Middle", Stanford).
+
+**AGENTS.md is an index of expensive truths** — only include what the codebase cannot answer on its own. If an agent could infer it by reading the code, it does not belong here.
+
+### Progressive disclosure hierarchy
+
+Not everything belongs in the root file. Push detail to where it's needed:
+
+1. **AGENTS.md** (root) — project-wide truths: what it is, how to build/test/lint, structure overview, hard boundaries. Aim for under 100 lines.
+2. **Scoped `.instructions.md`** — path-specific guidance loaded only when the agent works in that area. Use `applyTo` globs to target file types or directories.
+3. **docs/** — deeper context (architecture, ADRs, runbooks) that agents can read on demand but shouldn't carry in every conversation.
+
+When auditing, ask: "Does this line resolve an ambiguity that the code alone cannot?" If not, move it down a level or remove it.
+
+## Quality Principles
+
+1. **Specificity over generality** — `npm test -- --coverage` not "run the tests"
+2. **Commands up front** — build, test, lint commands in the first section, with exact flags. Position 1 gets the most attention; use it.
+3. **Examples over explanations** — one code snippet > one paragraph of prose
+4. **Six core areas** — commands, testing, project structure, code style, git workflow, boundaries
+5. **Explicit boundaries** — state what agents must NOT do
+6. **Tech stack with versions** — "React 18, TypeScript 5.x, Vite" not "a React project"
+7. **Drift-resistant** — reference stable concepts (directory purposes, architectural decisions) over volatile details (file lists that change weekly)
+8. **Progressive disclosure** — push path-specific or rarely-needed detail into scoped files or docs/, not the root AGENTS.md
+9. **No duplication** — reference other docs, don't restate their content
+10. **Sparse and maintained** — every line must earn its place; a short accurate file outperforms a comprehensive stale one
+
+## Structure Checklist
+
+A well-maintained AGENTS.md covers:
+
+- [ ] What the project is (one sentence)
+- [ ] How to build, test, and lint (exact commands)
+- [ ] Project structure (directory map with purposes)
+- [ ] Code style and conventions (with examples)
+- [ ] Git workflow (branching, commit, PR conventions)
+- [ ] Boundaries (forbidden files, actions, patterns)
+- [ ] Testing approach (frameworks, coverage expectations)
+
+See [REFERENCE.md](REFERENCE.md) for templates, examples, and detailed section guidance.

package/skills/review/refactor-skill/EXAMPLES.md

@@ -0,0 +1,20 @@
+# Examples
+
+## Template comparison output shape
+
+The output of Step 2 (template comparison) drives the whole rewrite. Below is a compact before/after table showing what the comparison output looks like for a typical skill being refactored.
+
+```
+Skill: review-security
+
+| Dimension | Current state | Template says | Verdict |
+|---|---|---|---|
+| Front matter | name: review-security, no description field | name, description required | Partial — add description |
+| Description | Missing entirely | 2 sentences, Use when ..., 2-4 triggers | Missing — add |
+| When to use | Single sentence | Trigger phrases listed explicitly | Needs rewording |
+| Workflow | 2 prose paragraphs | Numbered steps with outcomes | Needs restructuring |
+| Verification checklist | Missing | Required section | Missing — add |
+| Line length | 45 lines | ~150 target, 150 hard cap | Under — room to expand |
+```
+
+The same structure applies to any skill. Dimensions that already align can be noted as "Aligned — no change needed", keeping the comparison honest rather than gap-focused.