
skill-authoring
Skill creation and extraction workflows for reusable agent guidance.
- version
- 0.6.3
- GitHub stars
- 9
Install
/plugin install skill-authoring@agent-powerupsRun it inside Claude Code after adding the marketplace with /plugin marketplace add yeaight7/agent-powerups.
Contents
Discovered from sourceSkills 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
- Non-Googleable: Something you couldn't easily find via search
- Context-Specific: References actual files, error messages, or patterns from THIS codebase
- Actionable with Precision: Tells you exactly WHAT to do and WHERE
- 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
nameanddescription— the description must be specific enough to avoid false triggers. - Stay short in
SKILL.mdand move bulk detail intoreferences/orscripts/. - 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
namemust match the directory name exactly.descriptionmust say what the skill does AND when to use it in one sentence.
3. Keep the body lean
SKILL.mdshould 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.mdexceeds 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
| Section | Target |
|---|---|
| Frontmatter description | 1 sentence, 15–30 words |
SKILL.md body | 50–120 lines |
| Individual workflow steps | 1–3 lines each |
| References total | as needed, not in SKILL.md |
Bundled Helpers
scripts/init_skill.py— scaffold a new skill directoryscripts/package_skill.py— package for distributionscripts/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- software-engineeringv0.6.3
- spec-driven-developmentv0.6.3
- spec-quality-gatesv0.6.3
- tool-integrationsv0.6.3
- agent-evaluation-labv0.6.3
- agentic-systemsv0.6.3
- codebase-intelligencev0.6.3
- codebase-maintenancev0.6.3
- connected-appsv0.6.3
- context-efficiencyv0.6.3
- data-engineeringv0.6.3
- debugging-diagnosticsv0.6.3
- dev-vitalsv0.6.3
- documentation-systemsv0.6.3
- github-opsv0.6.3
- machine-learning-opsv0.6.3
- mcp-developmentv0.6.3
- memory-optimizationv0.6.3
- quality-gatesv0.6.3
- security-guardrailsv0.6.3