@codenhub/skills 0.0.2

package/src/agents-md-improver/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: agents-md-improver
+description: Audit and improve AGENTS.md files in repositories. Use when the user asks to check, audit, update, improve, or fix AGENTS.md files. Evaluate the target file against a quality rubric, output a report, then make targeted updates after approval.
+metadata:
+  short-description: Audit and improve AGENTS.md files
+---
+
+# AGENTS.md Improver
+
+Audit, evaluate, and improve `AGENTS.md` files across a codebase so future
+agent sessions have better project guidance.
+
+This skill can update `AGENTS.md` files. After presenting a quality report and
+getting user approval, it makes targeted improvements.
+
+## Tool Compatibility
+
+- Keep instructions tool-agnostic and avoid provider-specific wording.
+- When behavior differs across tools, resolve conflicts in this order: OpenCode > Claude Code > Codex CLI > Gemini CLI.
+
+## Workflow
+
+### Phase 1: Discovery
+
+Determine the target file before auditing anything:
+
+1. If the user explicitly names a file, use that file as the primary target.
+2. Otherwise, search for `AGENTS.md` files and default to the project root
+   `AGENTS.md` when it exists.
+3. Only inspect related instruction files such as `AGENTS_LONG.md` when the
+   user asks for them or they are necessary to explain the target file.
+
+Use the host environment's file search capability instead of assuming shell
+commands like `find` are available.
+
+**File Types & Locations:**
+
+| Type             | Location                    | Purpose                                  |
+| ---------------- | --------------------------- | ---------------------------------------- |
+| Explicit target  | User-provided path          | Highest-priority file to audit           |
+| Project root     | `./AGENTS.md`               | Primary shared project instructions      |
+| Package-specific | `./packages/*/AGENTS.md`    | Module-level guidance in monorepos       |
+| Subdirectory     | Any nested location         | Feature or domain-specific instructions  |
+| Related guides   | `AGENTS_LONG.md` or similar | Supplemental context only when requested |
+
+### Phase 2: Quality Assessment
+
+For each target `AGENTS.md` file, evaluate against the quality criteria. See
+[references/quality-criteria.md](references/quality-criteria.md) for detailed
+rubrics.
+
+**Quick Assessment Checklist:**
+
+| Criterion                         | Weight | Check                                                           |
+| --------------------------------- | ------ | --------------------------------------------------------------- |
+| Commands and workflows documented | High   | Are build, test, lint, and common operations present?           |
+| Architecture clarity              | High   | Can the agent understand the codebase structure and boundaries? |
+| Non-obvious patterns              | Medium | Are gotchas, quirks, and exceptions documented?                 |
+| Conciseness                       | Medium | Is the file dense and useful instead of verbose?                |
+| Currency                          | High   | Does it reflect the current codebase state?                     |
+| Actionability                     | High   | Are instructions concrete and executable?                       |
+
+**Quality Scores:**
+
+- **A (90-100)**: Comprehensive, current, actionable
+- **B (70-89)**: Good coverage, minor gaps
+- **C (50-69)**: Basic info, missing key sections
+- **D (30-49)**: Sparse or outdated
+- **F (0-29)**: Missing or severely outdated
+
+### Phase 3: Quality Report Output
+
+Always output the quality report before making any updates.
+
+Format:
+
+```text
+## AGENTS.md Quality Report
+
+### Summary
+- Files found: X
+- Average score: X/100
+- Files needing update: X
+
+### File-by-File Assessment
+
+#### 1. ./AGENTS.md (Project Root)
+**Score: XX/100 (Grade: X)**
+
+| Criterion | Score | Notes |
+|-----------|-------|-------|
+| Commands and workflows | X/20 | ... |
+| Architecture clarity | X/20 | ... |
+| Non-obvious patterns | X/15 | ... |
+| Conciseness | X/15 | ... |
+| Currency | X/15 | ... |
+| Actionability | X/15 | ... |
+
+**Issues:**
+- [List specific problems]
+
+**Recommended additions:**
+- [List what should be added]
+
+#### 2. ./packages/api/AGENTS.md (Package-specific)
+...
+```
+
+### Phase 4: Targeted Updates
+
+After outputting the quality report, ask the user for confirmation before
+updating anything.
+
+**Update Guidelines (Critical):**
+
+1. Propose targeted additions only. Focus on genuinely useful information:
+   - commands or workflows discovered during analysis
+   - gotchas or non-obvious patterns found in code
+   - package relationships that were not clear
+   - testing approaches that work
+   - configuration quirks
+
+2. Keep it minimal. Avoid:
+   - restating what is obvious from the code
+   - generic best practices already covered elsewhere
+   - one-off fixes unlikely to recur
+   - verbose explanations when a one-liner will do
+
+3. Show diffs. For each change, show:
+   - which `AGENTS.md` file to update
+   - the specific addition as a diff or quoted block
+   - a brief explanation of why this helps future sessions
+
+**Diff Format:**
+
+`````markdown
+### Update: ./AGENTS.md
+
+**Why:** The build command was missing, which makes it harder for future
+sessions to get started quickly.
+
+````diff
++## Quick Start
++
++```bash
++npm install
++npm run dev  # Start development server
++```
+````
+`````
+
+```
+
+### Phase 5: Apply Updates
+
+After user approval, apply changes using the host environment's editing
+capability. Preserve the existing content structure unless restructuring is part
+of the approved improvement.
+
+## Templates
+
+See [references/templates.md](references/templates.md) for `AGENTS.md`
+templates by project type.
+
+## Common Issues to Flag
+
+1. Stale commands: documented commands no longer work
+2. Missing dependencies: required tools or setup not mentioned
+3. Outdated architecture: directory structure or key files have changed
+4. Missing environment setup: required variables or configuration are absent
+5. Broken test commands: test scripts or workflows have changed
+6. Undocumented gotchas: non-obvious patterns are not captured
+7. Generic filler: the file contains broad advice instead of project-specific guidance
+
+## User Tips to Share
+
+When presenting recommendations, remind users:
+
+- Keep `AGENTS.md` concise and human-readable. Dense is better than verbose.
+- Prefer commands that are copy-paste ready.
+- Document project-specific patterns and gotchas, not generic engineering advice.
+- Separate shared project instructions from personal preferences when the host workflow supports it.
+- Revisit `AGENTS.md` after important workflow or architecture changes so it stays current.
+
+## What Makes a Great AGENTS.md
+
+**Key principles:**
+
+- Concise and human-readable
+- Actionable commands that can be copy-pasted
+- Project-specific patterns, not generic advice
+- Non-obvious gotchas and warnings
+- Current guidance that matches the repository as it exists today
+
+**Recommended sections** (use only what is relevant):
+
+- Commands (build, test, dev, lint)
+- Architecture (directory structure)
+- Key Files (entry points, config)
+- Code Style (project conventions)
+- Environment (required vars, setup)
+- Testing (commands, patterns)
+- Gotchas (quirks, common mistakes)
+- Workflow (when to do what)
+
+## Failure Modes To Handle
+
+- If no target file exists, say so clearly and ask whether to create one or use a
+  different file.
+- If several candidate files exist, explain the candidates and anchor the audit
+  to the user-requested file or the root `AGENTS.md` by default.
+- If a recommendation cannot be verified from the repository, label it as
+  uncertain instead of stating it as fact.
+- If the file is already high quality, say so explicitly and avoid editing for
+  the sake of editing.
+```

package/src/agents-md-improver/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AGENTS.md Improver"
+  short_description: "Audit and improve AGENTS.md files"
+  default_prompt: "Use $agents-md-improver to audit the target AGENTS.md file, score it, show the quality report, and propose only targeted high-value improvements before editing."

package/src/agents-md-improver/references/quality-criteria.md

@@ -0,0 +1,116 @@
+# AGENTS.md Quality Criteria
+
+## Scoring Rubric
+
+### 1. Commands and Workflows (20 points)
+
+**20 points**: All essential commands documented with context
+
+- Build, test, lint, and deploy commands are present when relevant
+- Development workflow is clear
+- Common operations are documented
+
+**15 points**: Most commands are present, some context is missing
+
+**10 points**: Basic commands only, little or no workflow guidance
+
+**5 points**: Few commands, many missing
+
+**0 points**: No commands documented
+
+### 2. Architecture Clarity (20 points)
+
+**20 points**: Clear codebase map
+
+- Key directories are explained
+- Module relationships are documented
+- Entry points are identified
+- Data flow is described where relevant
+
+**15 points**: Good structure overview, minor gaps
+
+**10 points**: Basic directory listing only
+
+**5 points**: Vague or incomplete
+
+**0 points**: No architecture info
+
+### 3. Non-Obvious Patterns (15 points)
+
+**15 points**: Gotchas and quirks are captured
+
+- Known issues are documented
+- Workarounds are explained
+- Edge cases are noted
+- Unusual patterns include a short explanation of why they exist
+
+**10 points**: Some patterns are documented
+
+**5 points**: Minimal pattern documentation
+
+**0 points**: No patterns or gotchas
+
+### 4. Conciseness (15 points)
+
+**15 points**: Dense, valuable content
+
+- No filler or obvious information
+- Each line adds value
+- No redundancy with other project docs unless the repetition is intentional and useful
+
+**10 points**: Mostly concise, some padding
+
+**5 points**: Verbose in places
+
+**0 points**: Mostly filler or restates obvious code
+
+### 5. Currency (15 points)
+
+**15 points**: Reflects the current codebase
+
+- Commands work as documented
+- File references are accurate
+- Stack and workflow details are current
+
+**10 points**: Mostly current, minor staleness
+
+**5 points**: Several outdated references
+
+**0 points**: Severely outdated
+
+### 6. Actionability (15 points)
+
+**15 points**: Instructions are executable
+
+- Commands can be copy-pasted
+- Steps are concrete
+- Paths are real
+- Guidance tells the reader what to do, not just what exists
+
+**10 points**: Mostly actionable
+
+**5 points**: Some vague instructions
+
+**0 points**: Vague or theoretical
+
+## Assessment Process
+
+1. Read the target `AGENTS.md` file completely.
+2. Cross-check with the actual repository:
+   - verify documented commands where practical
+   - check that referenced files and directories exist
+   - confirm architecture descriptions match the codebase
+3. Score each criterion.
+4. Calculate the total and assign a grade.
+5. List specific issues found.
+6. Propose concrete improvements.
+
+## Red Flags
+
+- Commands that would fail because of wrong paths, missing dependencies, or stale names
+- References to deleted files or folders
+- Outdated stack or workflow descriptions
+- Generic template content that was never customized for the project
+- Advice that is not specific to the repository
+- Placeholder text such as `TODO` that was never resolved
+- Duplicated guidance spread across multiple instruction files without a clear reason

package/src/agents-md-improver/references/templates.md

@@ -0,0 +1,255 @@
+# AGENTS.md Templates
+
+## Key Principles
+
+- **Concise**: Dense, human-readable content; one line per concept when possible
+- **Actionable**: Commands should be copy-paste ready
+- **Project-specific**: Document patterns unique to this project, not generic advice
+- **Current**: All guidance should reflect the actual codebase state
+
+---
+
+## Recommended Sections
+
+Use only the sections relevant to the project. Not every section is needed.
+
+### Commands
+
+Document the essential commands for working with the project.
+
+```markdown
+## Commands
+
+| Command             | Description              |
+| ------------------- | ------------------------ |
+| `<install command>` | Install dependencies     |
+| `<dev command>`     | Start development server |
+| `<build command>`   | Production build         |
+| `<test command>`    | Run tests                |
+| `<lint command>`    | Lint or format code      |
+```
+
+### Architecture
+
+Describe the project structure so the agent understands where things live.
+
+````markdown
+## Architecture
+
+```
+<root>/
+  <dir>/    # <purpose>
+  <dir>/    # <purpose>
+  <dir>/    # <purpose>
+```
+````
+
+### Key Files
+
+List important files that an agent should know about.
+
+```markdown
+## Key Files
+
+- `<path>` - <purpose>
+- `<path>` - <purpose>
+```
+
+### Code Style
+
+Document project-specific coding conventions.
+
+```markdown
+## Code Style
+
+- <convention>
+- <convention>
+- <preference over alternative>
+```
+
+### Environment
+
+Document required environment variables and setup.
+
+```markdown
+## Environment
+
+Required:
+
+- `<VAR_NAME>` - <purpose>
+- `<VAR_NAME>` - <purpose>
+
+Setup:
+
+- <setup step>
+```
+
+### Testing
+
+Document the testing approach and commands.
+
+```markdown
+## Testing
+
+- `<test command>` - <what it tests>
+- <testing convention or pattern>
+```
+
+### Gotchas
+
+Document non-obvious patterns, quirks, and warnings.
+
+```markdown
+## Gotchas
+
+- <non-obvious thing that causes issues>
+- <ordering dependency or prerequisite>
+- <common mistake to avoid>
+```
+
+### Workflow
+
+Document development workflow patterns.
+
+```markdown
+## Workflow
+
+- <when to do X>
+- <preferred approach for Y>
+```
+
+---
+
+## Template: Project Root (Minimal)
+
+````markdown
+# <Project Name>
+
+<One-line description>
+
+## Commands
+
+| Command     | Description   |
+| ----------- | ------------- |
+| `<command>` | <description> |
+
+## Architecture
+
+```
+<structure>
+```
+
+## Gotchas
+
+- <gotcha>
+````
+
+---
+
+## Template: Project Root (Comprehensive)
+
+````markdown
+# <Project Name>
+
+<One-line description>
+
+## Commands
+
+| Command     | Description   |
+| ----------- | ------------- |
+| `<command>` | <description> |
+
+## Architecture
+
+```
+<structure with descriptions>
+```
+
+## Key Files
+
+- `<path>` - <purpose>
+
+## Code Style
+
+- <convention>
+
+## Environment
+
+- `<VAR>` - <purpose>
+
+## Testing
+
+- `<command>` - <scope>
+
+## Gotchas
+
+- <gotcha>
+````
+
+---
+
+## Template: Package or Module
+
+For packages within a monorepo or distinct modules.
+
+````markdown
+# <Package Name>
+
+<Purpose of this package>
+
+## Usage
+
+```
+<import or usage example>
+```
+
+## Key Exports
+
+- `<export>` - <purpose>
+
+## Dependencies
+
+- `<dependency>` - <why needed>
+
+## Notes
+
+- <important note>
+````
+
+---
+
+## Template: Monorepo Root
+
+```markdown
+# <Monorepo Name>
+
+<Description>
+
+## Packages
+
+| Package  | Description | Path     |
+| -------- | ----------- | -------- |
+| `<name>` | <purpose>   | `<path>` |
+
+## Commands
+
+| Command     | Description   |
+| ----------- | ------------- |
+| `<command>` | <description> |
+
+## Cross-Package Patterns
+
+- <shared pattern>
+- <generation or sync pattern>
+```
+
+---
+
+## Update Principles
+
+When updating any `AGENTS.md`:
+
+1. **Be specific**: Use actual file paths and real commands from this project.
+2. **Be current**: Verify the guidance against the actual codebase.
+3. **Be brief**: One line per concept when possible.
+4. **Be useful**: Would this help a new agent session understand the project?