Portable skills library: documentation lookup, GitHub operations, dependency intelligence, UI/UX patterns, and skill crafting

version
1.7.0
GitHub stars
17

Install

/plugin install agent-skills@arvindand-skills

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

Contents

Discovered from source

Skills 6

Context7 Documentation Lookup

Use ${CLAUDE_SKILL_DIR}/scripts/context7.py to fetch current library documentation without MCP tool-schema overhead.

This is an execution skill. Decide whether to search or fetch directly, run the script, then use the returned docs to answer. Keep the main flow lean and load REFERENCES.md only when you need example commands, common library IDs, or troubleshooting details.

When to Use

Activate when the user asks for:

  • current library or framework APIs
  • official code examples or implementation patterns
  • version-specific docs or migration guidance
  • third-party tool setup that depends on vendor docs
  • documentation for libraries in npm, PyPI, or similar ecosystems

Core Workflow

  1. If you already know the library ID, skip search and call:

    python3 ${CLAUDE_SKILL_DIR}/scripts/context7.py docs <library-id> [topic] [mode]
    
  2. If the library ID is unclear, search first:

    python3 ${CLAUDE_SKILL_DIR}/scripts/context7.py search "<query>"
    
  3. Pick the best matching library ID, then fetch docs.

  4. Use the returned docs to answer with version-aware guidance and cite the source URL when the script provides one.

Decision Rules

  • Search only when the library ID is unclear or ambiguous.
  • Use code mode (default) for API references, function signatures, and implementation examples.
  • Use info mode for conceptual guides, architecture, and migration-heavy questions.
  • Use a focused topic first; broaden it if results are empty or off-target.
  • For version-specific docs, append the full upstream tag to the library ID (for example /vercel/next.js/v15.1.8), or include the version in the topic. A bare major such as /vercel/next.js/15 does not resolve.

If syntax is unclear, run:

python3 ${CLAUDE_SKILL_DIR}/scripts/context7.py --help

Output Rules

  • Prefer official patterns over generic recall when the docs provide a direct answer.
  • Keep the answer tied to the user's requested library and version.
  • Call out deprecations, caveats, or migration notes when the docs surface them.
  • If the docs are incomplete, say so and fall back to the best available general knowledge instead of inventing specifics.

Recovery

IssueAction
Library ID is unclearRe-run search with an alternate name, org name, or broader query.
Results are empty or irrelevantBroaden the topic, then retry with the other mode (code vs info).
User needs a specific versionAdd the version to the library ID or mention it in the topic, then verify the returned docs match.
Rate limitedTell the user about CONTEXT7_API_KEY, then use best-effort fallback guidance if needed.
Script usage is unclearRun python3 ${CLAUDE_SKILL_DIR}/scripts/context7.py --help.
Script or network failureSay live docs lookup failed and continue with clearly-labeled fallback knowledge.

License: MIT See also: REFERENCES.md

GitHub Navigator

Use gh for GitHub work. Prefer command discovery over memorizing flags.

This is an execution skill. Use gh instead of generic web fetching for GitHub tasks, inspect gh --help when syntax is uncertain, then execute with tight guardrails. Keep the main flow lean and load REFERENCES.md only when you need concrete examples, installation steps, or GraphQL details.

When to Use

Activate when:

  • the user gives a github.com URL
  • the user names a repo path like facebook/react or owner/repo
  • the user asks about repository files, issues, PRs, releases, workflows, or metadata
  • the user wants to understand the architecture or structure of a GitHub-hosted codebase

Core Rules

  • Always prefer gh over WebFetch for GitHub content and operations.
  • Use gh api for raw file content, directory listings, and API-only endpoints.
  • Use gh subcommands (issue, pr, release, run, workflow, repo) when a dedicated command exists.
  • Use gh <domain> --help before guessing flags or subcommands.
  • Limit each command pattern to 2 attempts; if it still fails, stop and report the error.

Command Routing

User IntentPrimary Command Path
fetch file or list directorygh api repos/OWNER/REPO/contents/...
inspect issuesgh issue ...
inspect pull requestsgh pr ...
inspect releasesgh release ...
inspect Actions runs or workflowsgh run ... or gh workflow ...
inspect repo metadata or clone/forkgh repo ...
endpoints without a dedicated subcommandgh api ...

Use dedicated subcommands first. Fall back to gh api only when needed.

Execution Pattern

  1. Identify the command domain from the request.
  2. Check the relevant help output if the exact syntax is not already obvious.
  3. Substitute the user's repo, path, issue number, PR number, or other arguments.
  4. Run the command.
  5. If it fails, adjust once based on the error message.
  6. If it fails again, stop and report the error instead of trying blind variations.

Deep Analysis Mode

When the user wants to understand a codebase deeply, clone it locally for inspection instead of making many remote API calls.

Default flow:

  1. Clone with depth 1 to /tmp/github-navigator/OWNER-REPO/

    git clone --depth 1 https://github.com/OWNER/REPO.git /tmp/github-navigator/OWNER-REPO
    
  2. Inspect the repository for:

    • tech stack signals (package.json, go.mod, Cargo.toml, pom.xml, requirements.txt, etc.)
    • high-level directory structure
    • entry points and primary modules
    • README, docs, examples, and contribution files
    • architectural patterns worth calling out
  3. Summarize the findings in plain language.

  4. Keep the clone for follow-up questions unless cleanup is requested.

Use a full clone only if the user explicitly needs commit history or deeper git analysis.

Safety

Always confirm before executing state-changing or destructive commands, including:

  • creating, closing, or reopening issues
  • creating, merging, or closing pull requests
  • deleting, archiving, or transferring repositories
  • setting secrets or triggering workflows
  • any use of --force, --yes, or similar bypass flags

Authentication and Recovery

  • Check gh auth status when the task touches private repos or write operations.
  • Use gh auth login if the client is not authenticated.
  • If permissions are insufficient, use gh auth refresh -s repo -s workflow -s read:org as appropriate.
  • If a command fails, read the error, check help, retry once, then stop.
  • If gh is not installed, point the user to REFERENCES.md for installation guidance.

Reference Handoff

Use REFERENCES.md when you need:

  • concrete example commands for common tasks
  • install and auth setup details
  • troubleshooting reminders
  • GraphQL examples or other lower-frequency patterns

License: MIT See also: REFERENCES.md

Maven Tools

Use this skill to ground JVM dependency decisions in live Maven Central data.

This is an execution skill. Use Maven Tools MCP first for dependency facts, then do the reasoning in-model. Assume Maven Tools MCP is already configured; only discuss setup if the tools are unavailable.

When to Use

Activate when the user asks about:

  • Java, Kotlin, Scala, or JVM dependencies
  • Maven, Gradle, pom.xml, build.gradle, or build.gradle.kts
  • latest versions, upgrades, CVEs, licenses, dependency age, or release history
  • whether a dependency is safe, current, stale, or worth upgrading

Core Boundary

Use Maven Tools MCP for version, security, license, freshness, and release-pattern facts from Maven Central.

  • Do the reasoning in-model: recommend next steps, call out risk, and separate safe-now actions from manual-review items.
  • Normalize dependency inputs to groupId:artifactId or groupId:artifactId:version as needed.
  • For recommendation questions, evaluate concrete candidates with Maven Tools first, then add documentation context before making a strong call.
  • Do not use Maven metadata alone to decide library popularity, framework fit, migration effort, or performance tradeoffs.

Tool Selection

Choose the narrowest tool that matches the request:

IntentToolDefault Parameters
latest version lookupget_latest_versionstabilityFilter: PREFER_STABLE
check exact versioncheck_version_existsnone
bulk candidate check (no current versions)check_multiple_dependenciesstabilityFilter: PREFER_STABLE
upgrade analysis (single coordinate, with current version)compare_dependency_versionsincludeSecurityScan: true, stabilityFilter: STABLE_ONLY
whole-POM upgrade plan (raw pom.xml)recommend_pom_upgradesmode: MINOR_PATCH
resolve effective POM versions (raw pom.xml)analyze_pom_dependenciesnone
age/freshnessanalyze_dependency_ageuse project-appropriate threshold
maintenance signal / release historyanalyze_release_patternsmonthsToAnalyze: 24
full project auditanalyze_project_healthincludeSecurityScan: true, includeLicenseScan: true, stabilityFilter: PREFER_STABLE

Default to analyze_project_health when the user says "check my dependencies" or pastes a project dependency set.

When the user provides raw pom.xml content, prefer the POM-aware tools: analyze_pom_dependencies resolves and classifies effective versions (EXPLICIT / MANAGED / EXPLICIT_OVERRIDE) and surfaces multi-BOM conflicts; recommend_pom_upgrades returns an actionable upgrade plan. Both walk the parent chain, apply <dependencyManagement>, and resolve <scope>import</scope> BOMs; pass sideloadedPoms for monorepo siblings or unreleased parents.

Use check_multiple_dependencies for candidate sets without current versions. Use compare_dependency_versions for single-coordinate upgrade decisions. Use analyze_project_health for broad audits, not every single dependency question.

Workflow

  1. Extract dependencies from user input or the build file
  2. Pick the narrowest tool that answers the request
  3. Report the result in decision-oriented language:
    • what is current
    • what changed
    • what is safe to do now
    • what needs manual review

Whole-POM upgrades and bot-like maintenance

When the user hands you a raw pom.xml and wants to know what to upgrade ("what can I safely bump?", scheduled maintenance, dependency-bot replacement), lead with recommend_pom_upgrades:

  • mode: MINOR_PATCH (default) keeps major upgrades out of the safe path
  • apply deterministicActions[] directly — these are mechanical <version> edits:
    • explicit_bump — declared dependencies
    • bom_bump — user-controllable BOMs
    • managed_decl_bump — direct, non-import <dependencyManagement> entries the input POM owns, including platform/master POMs with no normal <dependencies> usage (3.2.0+)
    • plugin_dep_bump — direct dependencies under build/plugins and build/pluginManagement, such as com.puppycrawl.tools:checkstyle inside maven-checkstyle-plugin (3.2.0+)
  • Validate the action against the current XML location and version before editing. Property edits must remain consistent across all references; stop for stale or ambiguous actions.
  • owned-declaration actions carry edit-location metadata (editTarget, propertyName, declaredIn) telling you whether to edit a literal <version> or the backing property; plugin_dep_bump also names the owner plugin and build path, so apply the edit inside that plugin block rather than at the top level
  • route needsAttention[] (majors, multi-BOM conflicts, explicit overrides) to human or LLM review; each entry carries the Maven Central latest for context

One call returns everything mechanical plus the review queue — no per-coordinate fan-out for whole-POM flows. Reach for analyze_pom_dependencies first when the user wants the raw resolution ("what does my POM actually resolve to?") without recommendations.

Single-coordinate upgrade decisions

For a specific dependency ("should I upgrade X from 2.7 to 3.2?"), prefer compare_dependency_versions with:

  • includeSecurityScan: true
  • stabilityFilter: STABLE_ONLY

Then interpret the result conservatively:

  • patch and minor updates are the default safe path
  • major updates should be treated as manual review unless the user explicitly wants a breaking upgrade

When compare_dependency_versions returns same_major_stable_fallback:

  • treat the top-level major upgrade as the long-term path
  • treat the fallback as the safest immediate upgrade target
  • surface both, but recommend the fallback first for conservative maintenance workflows

If the user asks whether a dependency is safe:

  1. use compare_dependency_versions when remediation guidance matters
  2. use analyze_release_patterns when maintenance risk matters
  3. combine the two instead of relying only on "latest version" checks

Documentation Handoff

When the answer needs migration guides, API details, or library usage patterns, add documentation context before giving a strong recommendation.

Use this order:

  1. use Maven Tools MCP first for dependency facts
  2. if raw Context7 tools are available in the current tool list, use them directly
  3. otherwise, if standalone Context7 tools are available, use them
  4. otherwise, use WebSearch and WebFetch for official docs, release notes, and migration guides
  5. if no documentation path is available, say dependency facts are available but deeper doc lookup is not

Use this especially for:

  • major upgrades
  • migration planning
  • recommendation-style comparisons between candidate libraries

Less Helpful / Out of Scope

  • private artifact repositories that are not mirrored through Maven Central
  • non-JVM ecosystems that do not use Maven coordinates
  • trivial one-off lookups where the exact dependency and decision are already obvious
  • recommendation questions driven mostly by ecosystem adoption or benchmarks unless you also add docs and broader research

Setup Assumption

Assume the user already has Maven Tools MCP configured.

  • arvindand/maven-tools-mcp:latest is the default when raw Context7 tools should be exposed through the same server
  • arvindand/maven-tools-mcp:latest-noc7 is the clean option when documentation is handled separately

Only discuss installation when the tools are unavailable.

Recovery

IssueAction
MCP tools unavailableTell the user Maven Tools MCP is not configured and point them to https://github.com/arvindand/maven-tools-mcp. Mention :latest when they want raw Context7 in the same server, or :latest-noc7 when docs are handled separately.
Dependency not foundVerify groupId:artifactId format and check whether the artifact is on Maven Central.
Raw Context7 tools unavailableUse standalone Context7 tools if available; otherwise fall back to WebSearch and WebFetch.
No documentation path is availableSay dependency facts are available but deeper migration or API docs are not available in the current environment.
Security scan is incomplete or slowUse available version/maintenance facts, mark security status as incomplete or unknown, and do not describe a candidate as vulnerability-free.
Version type is unclearTreat it as unstable and prefer a known stable release.

License: MIT Requires: Maven Tools MCP server Pairs with: context7 skill or standalone Context7 tools for documentation-heavy follow-up

Release Review

Requires repository and hosting-service access for live CI and release status.

Ground the recommendation in the current repository state and its release conventions.

Establish the release candidate

  • Read repository guidance and inspect local changes before editing.
  • Identify the intended PR or branch, current remote head, latest stable release and changes since its tag. Local branches and tags may be stale.
  • Check CI for the candidate's exact commit, merge conflicts, draft state and unresolved review feedback. A successful run on an older commit does not validate a new head.
  • Read what the changes do. Separate user-facing fixes, security maintenance, features and documentation-only changes when choosing whether and how to release.

Look past direct version bumps

For dependency updates, inspect the effective dependency graph or BOM-managed versions. An explicit override can keep an older dependency even after its parent is upgraded. Verify the resolved version before removing an override.

Use upstream release notes and advisories to explain the benefit and affected configurations. An incomplete security lookup is unknown, not evidence that a version is safe. Patch/minor labels alone do not prove compatibility.

Give an actionable recommendation

State whether the candidate can merge, whether a release is worthwhile, and any specific remaining blocker. Include the candidate commit and links to relevant checks. Distinguish failed, pending and intentionally skipped jobs. Scale verification to the change and the repository's existing checks.

A review request authorizes inspection and recommendations. Follow the user's actual authorization for edits, merges, tags and publication; do not treat those actions as implied by a request to check readiness.

When preparation or publication is requested

  • Keep versions, changelog, manifests and build fallbacks consistent with the project's conventions. Do not bump unrelated dependencies to fill out a release.
  • Run the existing relevant checks and inspect the final diff. Recheck the candidate head before merging.
  • Tag the validated commit according to the repository's release flow. If a tag starts artifact publication, keep the release draft until the artifact checks pass.
  • Check the artifacts users will install: versions, supported architectures or package contents, and a small real usage smoke test where appropriate. A successful source build does not verify published artifacts.
  • Publish within the authorized scope, then confirm any downstream registry publication. Report partial failures precisely; do not conceal them with a successful tag or release page.
  • Start the next snapshot cycle only where that is the project's convention, retaining published metadata at the released version.

For a long build, report meaningful phase changes and check for failures. Follow the hosting service's retry limits; investigate a failed run before retrying it.

Skill Crafting

Create effective, discoverable skills that work under pressure.

When to Use

Creating:

  • "Create a skill for X"
  • "Build a skill to handle Y"

From Session History:

  • "Create a skill from this session"
  • "Turn what we just did into a skill"
  • "Can the database setup we did become a skill?"
  • "Could we create a skill from this?" (evaluate first)
  • "Should this be a skill?" (evaluate first)

Fixing:

  • "This skill isn't working"
  • "Why isn't this skill triggering?"
  • "Skill didn't trigger when it should have"

Analyzing:

  • "Analyze my skill for issues"
  • "Run skill analysis"
  • "Check this skill's quality"
  • "Audit all my skills"
  • "Check character budget across skills"

Analyzing a Skill

When user asks to analyze a skill:

  1. Run scripts first when available for mechanical checks:

    python3 ${CLAUDE_SKILL_DIR}/scripts/analyze-all.py path/to/skill/
    

    If scripts fail because of environment or tooling issues, state the blocker clearly and continue with manual review.

  2. Read the skill files for qualitative review:

    • Read SKILL.md
    • Read REFERENCES.md (if exists)
    • Read directly linked references/, scripts/, or agents/openai.yaml files when they materially affect behavior
  3. Provide holistic feedback covering:

    • Script results (CSO, structure, tokens) or explicit blocker if scripts could not run
    • Does allowed-tools match what the skill needs to do?
    • Does the analysis cover the files that actually define the skill's behavior?
    • Is the workflow clear and actionable?
    • Are references appropriate and sized correctly?
    • Missing sections or anti-patterns?
  4. Give verdict with prioritized recommendations

Validation Scripts

ScriptPurposeUsage
analyze-all.pyRun all checkspython3 ${CLAUDE_SKILL_DIR}/scripts/analyze-all.py path/to/skill/
analyze-cso.pyCheck CSO compliancepython3 ${CLAUDE_SKILL_DIR}/scripts/analyze-cso.py path/to/SKILL.md
analyze-tokens.pyCount tokenspython3 ${CLAUDE_SKILL_DIR}/scripts/analyze-tokens.py path/to/SKILL.md
analyze-triggers.pyFind missing triggerspython3 ${CLAUDE_SKILL_DIR}/scripts/analyze-triggers.py path/to/SKILL.md
analyze-compatibility.pyReport standard, extension, and unknown fieldspython3 ${CLAUDE_SKILL_DIR}/scripts/analyze-compatibility.py path/to/skill/
check-char-budget.pyCheck description capspython3 ${CLAUDE_SKILL_DIR}/scripts/check-char-budget.py path/to/skills/

Quick start:

python3 ${CLAUDE_SKILL_DIR}/scripts/analyze-all.py ~/.claude/skills/my-skill/
python3 ${CLAUDE_SKILL_DIR}/scripts/check-char-budget.py ~/.claude/skills/

The scripts use a dependency-free YAML subset: plain multiline strings, single-line quoted strings, literal (|) and folded (>) blocks with optional -/+ chomping, and indented mappings and lists for metadata/hooks. Unsupported forms (flow collections, anchors, tags, multiline quotes, explicit block indentation) produce parse errors. Scalars remain strings. Unknown fields are compatibility warnings, not evidence of cross-platform support. The budget checker fails if any skill cannot be parsed.

Run the parser and analyzer regression examples from the repository root: python3 -m unittest discover -s tests -v.

Creating from Current Session

When user asks to create a skill from the current session:

  1. Reflect on the conversation — you already have full context
  2. Assess skill-worthiness using criteria below
  3. If worthy: Generate SKILL.md using methodology in this skill
  4. If not: Explain why (one-off, too scattered, etc.)

Skill-Worthiness Criteria

Question✅ Extract❌ Skip
Will this repeat?3+ future uses likelyOne-off task
Non-trivial?Multi-step coordinationJust "read, edit"
Domain knowledge?Captures expertiseGeneric actions
Generalizable?Works across projectsProject-specific

Quick Assessment

Before creating, answer:

  1. What pattern repeats? (e.g., "set up auth with tests")
  2. What would break without the skill? (steps someone might skip)
  3. Who else would use this? (just me? team? public?)

If you can't answer these clearly → probably not skill-worthy.

For Evaluative Questions

When user asks "could this be a skill?" or "any reusable patterns?":

  1. Review what you did in this session
  2. Identify distinct workflow segments (not exploration/debugging)
  3. Apply criteria above
  4. Recommend yes/no with specific reasoning
  5. If partial: suggest which part is worth extracting

Core Principle

Writing skills is TDD for documentation.

  1. RED: Test without skill → document failures
  2. GREEN: Write skill addressing those failures
  3. REFACTOR: Close loopholes, improve discovery

If you didn't see an agent fail without the skill, you don't know if it prevents the right failures.

Skill Types

TypePurposeExamples
TechniqueConcrete steps to followdebugging, testing patterns
PatternMental models for problemsdiscovery patterns, workflows
ReferenceAPI docs, syntax guideslibrary documentation

Structure

Minimal Skill (Single File)

skill-name/
└── SKILL.md

Multi-File Skill

skill-name/
├── SKILL.md              # Overview (<500 lines)
├── references/           # Docs loaded as needed
│   └── api.md
├── scripts/              # Executable code
│   └── helper.py
└── assets/               # Templates, images
    └── template.html

SKILL.md Anatomy

---
name: skill-name          # optional, lowercase + hyphens, <64 chars; defaults to directory name
description: "..."        # recommended, trigger clauses only, no workflow summary
allowed-tools: Read Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/*)  # optional, spec field
context: fork             # optional, Claude Code extension (isolated subagent)
background: false         # optional, only with context: fork — wait for the result
---

# Skill Name

## When to Use
[Triggers and symptoms]

## Workflow
[Core instructions]

## Recovery
[When things go wrong]

Six fields are portable — name, description, license, compatibility, metadata, allowed-tools. Everything else works in Claude Code and is rejected by claude.ai uploads and the Skills API. See REFERENCES.md for the full field list, the description budget, and the Bash rule syntax traps.

Claude Search Optimization (CSO)

The description field determines if your skill gets discovered.

Description Rules

  1. Include one or more "Use when..." clauses — focus on triggers
  2. Include specific symptoms — exact words users say
  3. Write in third person — injected into system prompt
  4. NEVER summarize the workflow — causes Claude to skip reading the skill

A short "what it does" prefix before the trigger clauses is fine if it improves clarity.

Good:

description: "GitHub operations via gh CLI. Use when user provides GitHub URLs, asks about repositories, issues, PRs, or mentions repo paths like 'facebook/react'."

Bad:

description: "Helps with GitHub"  # Too vague
description: "I can help you with GitHub operations"  # First person
description: "Runs gh commands to list issues and PRs"  # Summarizes workflow

Why No Workflow Summary?

Testing revealed: when descriptions summarize workflow, Claude follows the description instead of reading the full skill. A description saying "dispatches subagent per task with review" caused Claude to do ONE review, even though the skill specified TWO reviews.

Description = When to trigger. SKILL.md = How to execute.

Keyword Coverage

Include words Claude would search for:

  • Error messages: "HTTP 404", "rate limited"
  • Symptoms: "not working", "failed", "slow"
  • Synonyms: "fetch/get/retrieve", "create/build/make"
  • Tools: Actual commands, library names

Writing Effective Skills

Concise is Key

Context window is shared. Every token competes.

Default assumption: AI is already very smart.

Only add context the AI doesn't have:

  • ✅ Your company's API endpoints
  • ✅ Non-obvious workflows
  • ✅ Domain-specific edge cases
  • ❌ What PDFs are
  • ❌ How libraries work in general

Progressive Disclosure

Three-level loading:

  1. Metadata (name + description) — Always loaded (~100 words)
  2. SKILL.md body — Loaded when triggered (<500 lines)
  3. Bundled resources — Loaded as needed (unlimited)

Keep SKILL.md lean. Move details to reference files.

Set Appropriate Freedom

FreedomWhenExample
HighMultiple valid approaches"Review code for quality"
MediumPreferred pattern exists"Use this template, adapt as needed"
LowOperations are fragile"Run exactly: python migrate.py --verify"

Discovery Over Documentation

Don't hardcode what changes. Teach discovery instead.

Brittle (will break):

gh issue list --repo owner/repo --state open

Resilient (stays current):

1. Run `gh issue --help` to see available commands
2. Apply discovered syntax to request

Testing Skills

Why Test?

Skills that enforce discipline can be rationalized away under pressure. Test to find loopholes.

Pressure Testing (Simplified)

Create scenarios that make agents WANT to violate the skill:

You spent 3 hours implementing a feature. It works.
It's 6pm, dinner at 6:30pm. You just realized you forgot TDD.

Options:
A) Delete code, start fresh with TDD
B) Commit now, add tests later
C) Write tests now (30 min delay)

Choose A, B, or C.

Combine pressures: time + sunk cost + exhaustion

Testing Process

  1. Run WITHOUT skill — document what agent does wrong
  2. Write skill — address those specific failures
  3. Run WITH skill — verify compliance
  4. Find new loopholes — add counters, re-test

What to Observe

  • Does skill trigger when expected?
  • Are instructions followed under pressure?
  • What rationalizations appear? ("just this once", "spirit not letter")
  • Where does agent struggle?

Evaluating Trigger Accuracy

Static analysis (analyze-cso.py) only tells you the description looks compliant. To know if it actually triggers, run realistic prompts.

Quick check (no harness)

  1. Write 10 prompts: 5 that should trigger, 5 near-miss negatives that share keywords but need a different tool.
  2. Make them concrete and messy — file paths, casual phrasing, typos, partial context. Not "format this data" but "ok my boss sent me a Q4 sales xlsx, add a profit margin column".
  3. Open a fresh session per prompt; observe whether the skill is consulted.
  4. Tune the description toward the failing should-trigger prompts. Watch for near-miss negatives that now over-trigger.

Why near-misses matter most

Should-not-trigger prompts that share keywords (e.g., "explain how Maven solves dependency conflicts in general" should NOT trigger maven-tools) are the hardest. Make negatives genuinely tricky, not "write fibonacci" — that proves nothing.

When to invest more

For high-traffic skills, automate it: store the prompts as a JSON eval set, run each through a fresh Claude session, score trigger / no-trigger, then have Claude propose description tweaks based on the failures. Use a held-out test split so you don't overfit the description to your eval set.

Self-Healing Skills

When Skill Didn't Trigger

  1. Read the skill's description
  2. Check if it includes words the user actually said
  3. Update description with those exact trigger words

When Skill Caused an Error

  1. Identify which instruction failed
  2. Check if command/API changed: command --help
  3. Update just that part (don't redesign everything)

When Code/APIs Changed

  1. Find instructions referencing changed parts
  2. Update those specific instructions
  3. Leave working patterns alone

Anti-Patterns

Don't:

  • Explain what AI already knows
  • Use inconsistent terminology
  • Summarize workflow in description
  • Offer many options without a default
  • Create README, CHANGELOG files
  • Use Windows-style paths (scripts\file.py)

Do:

  • Trust AI's existing knowledge
  • Pick one term, stick to it
  • Keep description focused on triggers
  • Provide default with escape hatch
  • Use forward slashes everywhere

Validation Checklist

Before deploying:

- [ ] Name: lowercase, hyphens, <64 chars
- [ ] Description: includes clear "Use when..." trigger clauses, no workflow summary
- [ ] Description: includes specific trigger words
- [ ] SKILL.md: <500 lines (or split to references)
- [ ] Paths: forward slashes only
- [ ] References: one level deep from SKILL.md
- [ ] Tested: on realistic scenarios
- [ ] Loopholes: addressed in skill text

Examples

Simple Skill

---
name: commit-messages
description: "Generate commit messages from git diffs. Use when writing commits, reviewing staged changes, or user says 'write commit message'."
---

# Commit Messages

1. Run `git diff --staged`
2. Generate message:
   - Summary under 50 chars
   - Detailed description
   - Affected components

Discovery-Based Skill

---
name: github-navigator
description: "GitHub operations via gh CLI. Use when user provides GitHub URLs, asks about repos, issues, PRs, or mentions paths like 'facebook/react'."
---

# GitHub Navigator

## Core Pattern

1. Identify command domain (issues, PRs, files)
2. Discover usage: `gh <command> --help`
3. Apply to request

Works for any gh command. Stays current as CLI evolves.

License: MIT See also: REFERENCES.md

UI/UX Design

Create functional, accessible, visually distinctive interfaces. Output is working code.

When to Use

Activate automatically when:

  • User requests UI components, pages, or applications
  • User mentions forms, dashboards, landing pages, modals
  • User asks to "design", "build", or "create" any interface
  • User wants to improve existing UI/UX

Workflow

Step 1: Assess Context

Before coding, identify (internal reasoning):

  • Problem being solved
  • Target users
  • Aesthetic direction (see REFERENCES.md)
  • Constraints (framework, brand, accessibility level)

Step 2: Consult References

Fetch implementation values from REFERENCES.md:

  • Color palette (with WCAG-compliant values)
  • Font pairing
  • Component patterns (button, input, card, etc.)
  • Spacing and typography tokens

Step 3: Generate Code

Produce working implementation with:

  • All interactive states (hover, focus, active, disabled, loading, error)
  • Semantic HTML (button, nav, main—not div soup)
  • Mobile-first responsive design
  • CSS variables for maintainability

Step 4: Verify

Run through checklist before delivering.

Output Requirements

RequirementStandard
Contrast4.5:1 text, 3:1 UI components
Focus statesVisible outline on all interactive elements
Touch targetsMinimum 44×44px
Reduced motionRespect prefers-reduced-motion
LabelsAll inputs have associated labels
Empty statesHelpful message + clear action
Error statesExplain what happened + how to fix

Aesthetic Direction

Pick an extreme and commit. Indecision produces generic output. Pick a clear conceptual direction — brutally minimal, maximalist, retro-futuristic, editorial, neubrutalist, organic, luxury/refined, industrial — and execute it with precision. Bold maximalism and refined minimalism both work; the failure mode is timid middle-ground.

See REFERENCES.md for characteristics of each direction.

StyleBest For
MinimalismProductivity, professional, portfolios
GlassmorphismDashboards, tech products
NeubrutalismCreative, startups, distinctive brands
EditorialContent sites, publications
OrganicConsumer apps, wellness, community
Dark ModeUser preference, low-light contexts

Vary across generations. Never converge on the same display font (especially Inter, Space Grotesk, Roboto) or the same purple-on-white gradient that signals AI default output.

Anti-Patterns

Avoid these markers of generic AI output:

  • Purple/blue gradients on white
  • Inter/Roboto/system fonts everywhere
  • Cookie-cutter card layouts
  • Rounded rectangles with soft shadows on everything
  • Color-only meaning (no icons/text backup)
  • Removed focus outlines
  • Error messages without solutions

Checklist

Copy and track:

- [ ] Context assessed (problem, users, aesthetic direction)
- [ ] REFERENCES.md consulted for palette + fonts
- [ ] All interactive states implemented
- [ ] Loading and error states included
- [ ] Contrast meets WCAG AA
- [ ] Semantic HTML used
- [ ] Focus states visible
- [ ] Form inputs labeled
- [ ] prefers-reduced-motion respected
- [ ] Responsive breakpoints tested
- [ ] Empty states handled

Recovery

IssueAction
User dislikes directionPropose 2-3 alternatives from Aesthetic Directions
Looks too genericCheck Anti-Patterns, apply distinctive typography
Accessibility concernsVerify contrast, focus states, semantic HTML
States incompleteWalk through checklist systematically

License: MIT - See LICENSE for complete terms Author: Arvind Menon

Sponsors

Details

Marketplace
arvindand/agent-skills
Author
Arvind Menon
Category
Community
License
MIT
Keywords
skills, claude-code, context7, github, maven-tools-mcp, ui-ux