# Skillsaw Maintenance

> Analyze upstream specs (agentskills.io, Claude Code plugin/marketplace format) for changes, identify gaps in skillsaw's rule coverage, and create or update PRs to close those gaps. Use when performing periodic maintenance on the skillsaw linter.

- **Type:** Skill
- **Install:** `agentstack add skill-stbenjam-skillsaw-skillsaw-maintenance`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [stbenjam](https://agentstack.voostack.com/s/stbenjam)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [stbenjam](https://github.com/stbenjam)
- **Source:** https://github.com/stbenjam/skillsaw/tree/main/.opencode/skills/skillsaw-maintenance
- **Website:** https://skillsaw.org/

## Install

```sh
agentstack add skill-stbenjam-skillsaw-skillsaw-maintenance
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# skillsaw Maintenance

You are performing maintenance on the **skillsaw** linter. Your goal is to ensure
skillsaw stays current with upstream specifications and continues to pass all tests.

## Step 1: Analyze upstream specs for changes

Fetch and review the current versions of:

1. **agentskills.io specification** at https://agentskills.io/specification
   - Check for new required/optional frontmatter fields in SKILL.md
   - Check for changes to naming rules, directory structure, or evals format
   - Compare against what skillsaw currently validates in `src/skillsaw/rules/builtin/agentskills.py`

2. **Claude Code plugin format** at https://docs.claude.com/en/docs/claude-code/plugins-reference
   - Check for new required fields in plugin.json
   - Check for new command format requirements
   - Check for structural changes to plugin layout
   - Compare against `src/skillsaw/rules/builtin/plugin_structure.py` and `command_format.py`

3. **Claude Code marketplace format** at https://docs.claude.com/en/docs/claude-code/plugin-marketplaces
   - Check for new marketplace.json requirements
   - Check for changes to plugin registration or discovery
   - Compare against `src/skillsaw/rules/builtin/marketplace.py`

4. **Claude Code .claude/ directory** at https://code.claude.com/docs/en/claude-directory
   - Check for structure requirements, supported files, and conventions
   - Compare against `src/skillsaw/context.py` DOT_CLAUDE detection and discovery
   - Note: .claude/ is NOT a plugin — it has its own format distinct from plugins

5. **Claude Code hooks, MCP, agents, skills** formats
   - Hooks: https://docs.claude.com/en/docs/claude-code/hooks
   - MCP servers: https://docs.claude.com/en/docs/claude-code/mcp-servers
   - Skills and agents: https://docs.claude.com/en/docs/claude-code/skills
   - Review current docs for any format changes
   - Compare against the corresponding rule files in `src/skillsaw/rules/builtin/`

## Step 2: Identify gaps

For each spec change found, determine:
- Is there an existing rule that covers it? If so, does it need updating?
- Is a new rule needed? If so, what should it check and what severity?
- Would the change break backward compatibility? If so, how to handle it.

## Step 3: Implement spec gap fixes

For each gap identified in Step 2, create a separate PR:
- Create a new branch from main for the fix
- Implement the rule change or addition
- Write tests for any new or changed rules
- Run the full test suite: `pytest tests/ -v`
- Run formatting: `black src/ tests/`
- Test against ai-helpers: clone `openshift-eng/ai-helpers`, run `skillsaw` against it, ensure exit 0
- Open a PR with:
  - Title prefixed with `[Auto]` (e.g. `[Auto] Add license field validation`)
  - Description that includes: what changed, why, and the footer:
    `Generated by the [skillsaw-maintenance](https://github.com/stbenjam/skillsaw) skill.`

## Step 4: Validate backward compatibility

Before finalizing any change:
- Ensure `skillsaw` still passes clean on `openshift-eng/ai-helpers` with default config
  (agentskills rules are disabled in their config)
- Ensure no existing tests break
- New rules should default to `enabled: auto` or `enabled: false` — never force-enable
  a new rule that could break existing users

## Important constraints

- Never introduce breaking changes to the config format
- The `claudelint` CLI shim and `from claudelint import ...` must continue working
- Config discovery must continue finding `.claudelint.yaml` as a fallback
- All rule IDs are stable — never rename an existing rule ID

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [stbenjam](https://github.com/stbenjam)
- **Source:** [stbenjam/skillsaw](https://github.com/stbenjam/skillsaw)
- **License:** Apache-2.0
- **Homepage:** https://skillsaw.org/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-stbenjam-skillsaw-skillsaw-maintenance
- Seller: https://agentstack.voostack.com/s/stbenjam
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.