Skill creation and extraction workflows for reusable agent guidance.

version
0.6.3
GitHub stars
9

Install

/plugin install skill-authoring@agent-powerups

Run it inside Claude Code after adding the marketplace with /plugin marketplace add yeaight7/agent-powerups.

Contents

Discovered from source

Skills 2

Hard-Won Skill Extractor

This skill serves to document how to manually extract a useful learned skill into a reusable markdown file.

Core Principle

Reusable skills are not code snippets to copy-paste, but principles and decision-making heuristics that teach an agent HOW TO THINK about a class of problems.

The difference:

  • BAD (mimicking): "When you see ConnectionResetError, add this try/except block"
  • GOOD (reusable skill): "In async network code, any I/O operation can fail independently due to client/server lifecycle mismatches. The principle: wrap each I/O operation separately, because failure between operations is the common case, not the exception."

Quality Gate

Before extracting a skill manually, ALL three must be true:

  • "Could someone Google this in 5 minutes?" → NO
  • "Is this specific to THIS codebase?" → YES
  • "Did this take real debugging effort to discover?" → YES

Recognition Signals

Extract ONLY after:

  • Solving a tricky bug that required deep investigation
  • Discovering a non-obvious workaround specific to this codebase
  • Finding a hidden gotcha that wastes time when forgotten
  • Uncovering undocumented behavior that affects this project

What Makes a USEFUL Skill

  1. Non-Googleable: Something you couldn't easily find via search
  2. Context-Specific: References actual files, error messages, or patterns from THIS codebase
  3. Actionable with Precision: Tells you exactly WHAT to do and WHERE
  4. Hard-Won: Took significant debugging effort to discover

Anti-Patterns (DO NOT EXTRACT)

  • Generic programming patterns (use documentation instead)
  • Refactoring techniques (these are universal)
  • Library usage examples (use library docs)
  • Type definitions or boilerplate
  • Anything a junior dev could Google in 5 minutes

Manual Extraction Workflow

Step 1: Gather Required Information

  • Problem Statement: The SPECIFIC error, symptom, or confusion that occurred
  • Solution: The EXACT fix, not general advice
  • Triggers: Keywords that would appear when hitting this problem again
  • Scope: Almost always Project-level unless it's a truly universal insight

Step 2: Quality Validation

Reject skills that are:

  • Too generic
  • Easily Googleable
  • Vague solutions
  • Poor triggers

Step 3: Save Location

  • Project-level: .skills/<skill-name>.md - Default. Intended to be committed with the repo.

Step 4: Promote if reusable

If the extracted idea should become a maintained, shareable skill instead of a project-local note, switch to skill-authoring-guide and turn it into a proper skill folder with frontmatter, support files, and validation.

Required File Format

Every learned skill file MUST start with YAML frontmatter. Do not write plain markdown without frontmatter.

After the frontmatter, use a pure Markdown body with headings. Do not use XML-like tags such as <Purpose> or <Workflow> as default top-level structure; reserve XML-like delimiters for nested examples, quoted input, external documents, or machine-readable prompt payloads.

Minimum required frontmatter:

---
name: <skill-name>
description: <one-line description>
triggers:
  - <trigger-1>
  - <trigger-2>
---

Skill Body Template

---
name: <skill-name>
description: <one-line description>
triggers:
  - <trigger-1>
  - <trigger-2>
---

# [Skill Name]

## The Insight
What is the underlying PRINCIPLE you discovered? Not the code, but the mental model.

## Why This Matters
What goes wrong if you don't know this? What symptom led you here?

## Recognition Pattern
How do you know when this skill applies? What are the signs?

## The Approach
The decision-making heuristic, not just code. How should an agent THINK about this?

## Example (Optional)
If code helps, show it - but as illustration of the principle, not copy-paste material.

Verification

  • All three quality-gate questions hold: not Googleable in 5 minutes, specific to this codebase, took real debugging effort
  • The saved file starts with YAML frontmatter including name, description, and triggers
  • The body teaches the principle and recognition pattern — not copy-paste code
  • Anti-pattern content (generic patterns, library usage, boilerplate) was rejected, not extracted
  • Truly reusable insights were promoted via skill-authoring-guide instead of staying project-local

Skill Authoring Guide

Use this skill when creating or improving a reusable skill.

What Good Skills Do

  • Trigger reliably from name and description — the description must be specific enough to avoid false triggers.
  • Stay short in SKILL.md and move bulk detail into references/ or scripts/.
  • Teach a workflow or decision pattern, not just dump background information.
  • Include scripts or references only when they eliminate repeated work or prevent ambiguity.

Frontmatter Template

---
name: kebab-case-matching-directory-name
description: Use when [trigger condition]. Does [what it does]. [Optional: NOT for X.]
---

Body Format

Default to a pure Markdown body after the YAML frontmatter. Use headings such as ## Purpose, ## When to Use, ## Workflow, and ## Verification. Do not use XML-like tags such as <Purpose>, <Workflow>, or <Use_When> as normal top-level sections. XML-like tags are acceptable only when they strictly delimit nested examples, quoted input, external documents, or machine-readable prompt payloads.

Good description (specific, trigger-clear):

Use when designing or reviewing filesystem MCP access, path boundaries, allowed roots, and method allowlists.

Weak description (too broad, won't trigger reliably):

Helps with MCP things and file access.

Workflow

1. Define the job

  • What specific problem does this skill solve?
  • When should it trigger? (Be concrete — "when the user mentions X" or "when you're about to do Y".)
  • What should it explicitly NOT handle? State the boundary.

2. Write strong frontmatter

  • name must match the directory name exactly.
  • description must say what the skill does AND when to use it in one sentence.

3. Keep the body lean

  • SKILL.md should be readable in one focused pass — target 50–120 lines.
  • Use Markdown headings for top-level structure.
  • Move bulky reference material into references/.
  • Move deterministic scripts (validators, init scripts) into scripts/.
  • If SKILL.md exceeds 150 lines, split off the excess into a reference file.

4. Design progressive disclosure

  • SKILL.md: core workflow, when to use, safety constraints.
  • references/: detailed patterns, full checklists, long examples.
  • scripts/: automation helpers.

5. Validate before publishing

  • Check that every file path mentioned in the skill actually exists.
  • Remove any references/ links that point to non-existent files.
  • Verify the skill can be read in under 2 minutes.
  • Test the trigger: does the description reliably route to this skill for the intended use case?

Skill Length Guide

SectionTarget
Frontmatter description1 sentence, 15–30 words
SKILL.md body50–120 lines
Individual workflow steps1–3 lines each
References totalas needed, not in SKILL.md

Bundled Helpers

  • scripts/init_skill.py — scaffold a new skill directory
  • scripts/package_skill.py — package for distribution
  • scripts/quick_validate.py — check frontmatter and dead references

Use them as optional helpers if they fit your workflow.

Verification

  • The name field matches the skill directory name exactly
  • The description states the trigger condition and what the skill does in one sentence
  • The body reads in one focused pass — within the length guide, with bulk detail moved to references
  • Every file path mentioned in the skill exists; dead reference links were removed
  • The trigger was tested: the description reliably routes the intended use case to this skill

Related Skill

Use hard-won-skill-extractor when the challenge is turning a hard-earned session into a reusable skill candidate.

Sponsors

Details

Marketplace
yeaight7/agent-powerups
Source
plugins/skill-authoring
Category
Developer Tools
License
Apache-2.0
Keywords
skills, authoring, workflow, reuse, agents

More from yeaight7/agent-powerups

All 21