accelint-skill-manager

What this skill does

# Skill Manager

## NEVER Do When Creating Skills

- **NEVER write tutorials explaining basics** - Assume Claude knows standard concepts, libraries, and patterns. Focus on expert-only knowledge.
- **NEVER put triggering information in body** - "When to use" guidance belongs ONLY in the description field. The body is loaded after activation decision.
- **NEVER dump everything in SKILL.md** - Use progressive disclosure: core workflow in SKILL.md (<500 lines ideal), detailed content in references/, loaded on-demand.
- **NEVER use generic warnings** - "Be careful" and "avoid errors" are useless. Provide specific anti-patterns with concrete reasons.
- **NEVER use same freedom level for all tasks** - Creative domains (design, architecture) need high freedom with principles. Fragile operations (file formats, APIs) need low freedom with exact scripts.
- **NEVER explain standard operations** - Assume Claude knows how to read files, write code, use common libraries. Focus on non-obvious decisions and edge cases.
- **NEVER include obvious procedures** - "Step 1: Open file, Step 2: Edit, Step 3: Save" wastes tokens. Include only domain-specific workflows Claude wouldn't know.
- **NEVER skip the anti-patterns section** — It's half of expert knowledge. A skill without "NEVER Do" is missing what makes it valuable: the mistakes experts learned the hard way.
- **NEVER write a vague description** — "A skill for X" causes false positives and missed activations. The description must include concrete trigger phrases users actually say.
- **NEVER mix creation and audit concerns** — Creating a skill, refactoring a skill, and auditing a skill are distinct workflows. Each has different inputs, outputs, and success criteria.

## Before Creating a Skill, Ask

Apply these tests to ensure the skill provides genuine value:

### Knowledge Delta Test
- **Does this capture what takes experts years to learn?** If explaining basics or standard library usage, it's redundant.
- **Am I explaining TO Claude or arming Claude?** Skills should arm agents with expert knowledge, not teach them concepts.
- **Is every paragraph earning its context space?** Token economy matters - shared with system prompts, conversation history, and other skills.

### Activation Economics
- **Does the description answer WHAT, WHEN, and include KEYWORDS?** Vague descriptions mean the skill never gets activated.
- **Would an agent reading just the description know exactly when to use this?** If unclear, the skill is invisible.

### Freedom Calibration
- **What happens if the agent makes a mistake?** High consequence = low freedom (exact scripts). Low consequence = high freedom (principles).
- **Is there one correct way or multiple valid approaches?** One way = prescriptive. Multiple ways = guidance with examples.

### Token Efficiency
- **Can this be compressed without losing expert knowledge?** References loaded on-demand save context.
- **Are there repetitive procedures that could become scripts?** Reusable code belongs in scripts/, not repeated in instructions.

## How to Use

This skill uses **progressive disclosure** to minimize context usage:

### 1. Start with the Workflow (SKILL.md)
Follow the 4-step workflow below for skill creation or refactoring.

### 2. Reference Implementation Details (AGENTS.md)
Load [AGENTS.md](AGENTS.md) for file system conventions, naming patterns, and structural rules.

### 3. Load Specific References as Needed
Each workflow step below notes which reference files to load. Only load what you need for the current step:
- Directory structure → [references/file-system.md](references/file-system.md)
- Description field conventions → [references/skill.md](references/skill.md)
- AGENTS.md patterns → [references/agents.md](references/agents.md)
- Progressive disclosure rules → [references/progressive-disclosure.md](references/progressive-disclosure.md)
- Reference file format → [references/references.md](references/references.md)
- Script conventions → [references/scripts.md](references/scripts.md)
- Asset guidelines → [references/assets.md](references/assets.md)
- CHANGELOG maintenance → [references/changelog.md](references/changelog.md)

**Do NOT load all references at once** — load only the ones relevant to your current step.

## Which Workflow Should You Follow?

Choose based on your task:

- **Creating a new skill from scratch** → Follow Skill Creation Workflow (Steps 1-4)
- **Improving an existing skill** → Jump to Step 4 (Edit the Skill)
- **Auditing a skill for quality** → Follow Skill Audit Workflow

## Skill Creation Workflow

To create or refactor a skill, follow the "Skill Creation Workflow" in order, skipping steps only if there is a clear reason why they are not applicable.

**Copy this checklist to track progress:**

```
- [ ] Step 1: Understanding - Gather concrete examples of skill usage
- [ ] Step 2: Planning - Identify reusable scripts, references, assets
- [ ] Step 3: Initializing - Check existing skills, create directory structure
- [ ] Step 4: Editing - Write agent-focused content with procedural knowledge and update CHANGELOG
```

Include what rules from this skill are being applied, and why, in your summary.

### Step 1: Understanding the Skill with Concrete Examples

Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.

To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.

Example: Building an image-editor skill, ask:
- "What functionality? Editing, rotating, other?"
- "Usage examples?"
- "Trigger phrases: 'Remove red-eye', 'Rotate image'—others?"

Ask 2-3 concrete questions first (functionality, examples, trigger phrases), then follow up based on their answers rather than front-loading all questions.

Conclude when there is a clear sense of the functionality the skill should support.

### Step 2: Planning the Reusable Skill Contents

To turn concrete examples into an effective skill, analyze each example by:

1. Considering how to execute on the example from scratch
2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly

Examples:
- `pdf-editor` skill for "Rotate this PDF" → store `scripts/rotate-pdf.sh` to avoid rewriting code each time
- `frontend-app-builder` for "Build a todo app" → store `assets/hello-world/` boilerplate template
- `big-query` for "How many users logged in today?" → store `references/schema.md` with table schemas

Analyze each concrete example to create a list of reusable resources: scripts, references, and assets.

### Step 3: Initializing the Skill

**MANDATORY**: Load [references/file-system.md](references/file-system.md) before creating directory structure.

**For new skills:** Copy the template in [assets/skill-template/](assets/skill-template/) as a starting point and customize it.

**For existing skills being refactored:** Skip directly to Step 4 — the skill already exists.

Before creating, check for existing skills that overlap:

```bash
ls -la .claude/skills 2>/dev/null || echo "No project skills found"
ls -la ~/.claude/skills 2>/dev/null || echo "No global skills found"
```

If relevant skills exist, mention them briefly: "I found [list] — should any of these be included or merged?"

Follow the conventions in [AGENTS.md](AGENTS.md) and reference files for directory structure and naming.

### Step 4: Edit the Skill

**MANDATORY**: Load [references/skill.md](references/skill.md) for description field conventions and frontmatter rules.

When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of an agent to use. Focus on including information that would be beneficial and non-obvious to an agent. Consider what procedural knowledge, domain-specific details, or reu