SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsbuild-skill

build-skill

Agents & models

View repository

Updated 10-16 07:05

About this skill

Build Agent Skills

Synthesize robust, spec-compliant agent skills adhering to the open Agent Skills Specification. Built on empirical research, progressive disclosure, deterministic scripting, and verified domain context.

Mandatory Companion Prerequisite: run-research

High-quality skills cannot be built in a vacuum or from stale model memory. Skill authoring requires verified ground truth:

  • Prerequisite skill: skills/run-research
  • Install command: npx -y skills add yigitkonur/skills-by-yigitkonur/skills/run-research -y

Standing Invariant: Never draft a skill based on assumptions, unverified library contracts, or generic training weights. When non-trivial APIs, frameworks, or domain workflows are involved, invoke run-research first to gather authoritative documentation, verifiable quotes, and real code patterns. If run-research is not available, install it before proceeding.

When to Use

Use this skill when you are:

  • creating a new agent skill from scratch ("make me a skill for X", "scaffold a skill", "I need a skill that does Y")
  • substantially redesigning or refactoring an existing skill ("rewrite this skill", "clean up this bloated skill")
  • merging multiple skills or disparate source corpora into one ("combine these skills into one coherent skill")
  • extracting an in-flight conversation into a skill ("convert what we just did into a skill", session reaching 200k–400k tokens)
  • authoring a framework- or repo-specific skill with extensive reference blocks grounded in live documentation
  • auditing a skill for agentskills.io specification compliance (frontmatter fields, script conventions, progressive disclosure)

Do NOT use this skill for:

  • testing live derailment resistance — use audit-skill-by-derailment
  • one-off quick script fixes where outside skill patterns or documentation aren't relevant
  • blind cloning of a remote skill without synthesis, adaptation, or repo-fit

Core Non-Negotiable Rules

  1. Specification compliance first: Frontmatter strictly adheres to agentskills.io/specification (name, description, license, compatibility, metadata, allowed-tools).
  2. Context grounding before drafting: Invoke run-research for all non-trivial domains. Refuse to hallucinate APIs or edge cases.
  3. Progressive disclosure architecture: Keep SKILL.md under 500 lines (<5,000 tokens). Offload bulky documentation to references/ and deterministic operations to scripts/.
  4. Deterministic scripting: Write bundled scripts in portable JavaScript (.mjs ES Modules) or Python (.py). Avoid fragile shell scripts (.sh).
  5. Reproduce and test: Always test scripts and verify execution infrastructure before declaring done.
  6. Comparison before combination: When researching remote skills, build a structured comparison table with explicit inherit/avoid decisions.

Available Scripts

Scripts live in scripts/ and run directly via Node.js or Python without external global installations:

  • scripts/skill-dl.mjs — Discovery, download, and specification auditor.
    • Search registry: node scripts/skill-dl.mjs search "typescript" "mcp" --top 10
    • Download candidate: node scripts/skill-dl.mjs download anthropics/skills/mcp-builder -o ./research-corpus
    • Audit spec compliance: node scripts/skill-dl.mjs inspect ./skills/build-skill
  • scripts/skill-research.mjs — End-to-end multi-query discovery → download → corpus inspection pipeline:
    • node scripts/skill-research.mjs "typescript,mcp,server" ./research-corpus 3

(Backward-compatible bash shims scripts/skill-dl and scripts/skill-research.sh forward directly to these .mjs scripts).

Four Operational Modes

Mode 1: Discovery Mode (Registry & Consortium Sweep)

Use when researching existing patterns on skills.sh, GitHub, and external repositories.

  1. Registry Discovery: Run node scripts/skill-dl.mjs search across 3–10 orthogonal keywords to find top candidate skills with consensus scoring.
  2. Subagent Consortium: Deploy up to 3–5 parallel sub-agents to analyze candidates across distinct lenses:
    • Lens A: Architecture & Progressive Disclosure (how references/ and line counts are structured).
    • Lens B: Script & Tool Automation (what logic is scripted in scripts/ vs left in prose).
    • Lens C: Triggers & Description Calibrations (negative triggers, precision, over-triggering guards).
  3. Corpus Inspection: Download shortlisted skills to ./research-corpus and run node scripts/skill-dl.mjs inspect <dir> to verify spec compliance.
  4. Comparison Table: Draft a markdown comparison table summarizing Focus, Strengths, Gaps, and Inherit/Avoid decisions before writing code.

Mode 2: Creation & Distillation Mode (Synthesis & Repo-Fit)

Use when drafting a new skill or major refactor from discovered knowledge.

  1. Synthesize into Target Idioms: Translate raw external patterns into your repository's native conventions and vocabulary.
  2. Draft the Plan: Establish the directory layout (SKILL.md, references/, scripts/, assets/) and decision gates before authoring.
  3. Progressive Disclosure Boundary:
    • SKILL.md: High-level workflow, decision trees, prerequisites, script summaries, reference routing.
    • references/: Deep technical documentation, API tables, and domain-specific checklists.
    • scripts/: Executable verification, parsing, and scaffolding tools.
  4. Specification Audit: Verify frontmatter contains only allowed fields and line count stays under 500 lines.

Mode 3: Conversation-Driven Mode (High-Token Session Distillation)

Use when turning an extensive in-flight conversation (e.g. 200k–400k tokens) into a reusable skill.

  1. Mental Model & Research Alignment: Ingest the chat context and invoke run-research to ground any ambiguous domain tools or commands used during the session.
  2. Step-by-Step Confession (Up to 5-Level Nested List): Extract and reconstruct the exact progression of actions, corrections, and discoveries:
    • Level 1: Primary Milestone (e.g. Setting up authentication)
      • Level 2: Sub-workflow Phase (e.g. OAuth token exchange debugging)
        • Level 3: Concrete Step Executed (e.g. Inspecting headers and callback payload)
          • Level 4: Error Encountered & Correction (e.g. Fixed state mismatch via Redis PKCE store)
            • Level 5: Deterministic Insight or Invariant (e.g. Token TTL must be ≥300s to avoid refresh race)
  3. Transfer Planning: Classify each confessed step:
    • Transfer to SKILL.md body (core decision tree and workflow gates).
    • Transfer to references/ (deep configuration examples and error catalogs).
    • Script-ify (turn repetitive terminal commands into clean .mjs or .py scripts).
  4. Script Scaffolding: Implement deterministic steps as executable scripts in scripts/.

Mode 4: Pure Research / Documentation-Driven Mode

Use when the user wants a skill for a specific repo, library, or framework.

  1. Exhaustive Extraction via run-research: Query official docs, source code, migration guides, and GitHub issue trackers.
  2. Structured Reference Modularization: Decompose the domain into structured, atomic reference files under references/:
    • Quick-reference decision trees
    • Configuration recipes and gotchas
    • Concrete "do this, not that" comparative guides
  3. Actionable Block Formatting: Write instructions in direct, imperative language ("Run...", "Configure...", "Verify...").

Step-by-Step Authoring Workflow

  1. Verify Prerequisites: Confirm run-research is accessible and node scripts/skill-dl.mjs --where succeeds.
  2. Select Mode: Choose Discovery, Creation, Conversation-driven, or Documentation mode.
  3. Execute Research: Collect evidence via run-research and skill-dl.mjs search. Build the comparison table.
  4. Draft SKILL.md:
    • Write valid YAML frontmatter conforming to agentskills.io.
    • Formulate clear imperative workflow sections with validation gates.
    • Route reference files cleanly.
  5. Develop & Test Scripts:
    • Author automation scripts in scripts/ using Node.js (.mjs) or Python (.py).
    • Run and test scripts with real data; confirm zero-crash execution.
  6. Spec & Quality Validation:
    • Run node scripts/skill-dl.mjs inspect . to verify frontmatter and line counts.
    • Run repository skill validator: python3 scripts/validate-skills.py.

Do This, Not That

Do This Not That
Ground every skill in verified facts using run-research Hallucinate APIs or procedures from model memory
Write portable, robust scripts in Node.js (.mjs) or Python (.py) Author fragile shell scripts (.sh) with platform-dependent grep/sed
Adhere strictly to the 6 canonical agentskills.io frontmatter fields Invent arbitrary frontmatter fields like user-invocable or hooks
Keep SKILL.md under 500 lines and route details to references/ Stuff monolithic 1,500-line guides into a single SKILL.md
Test and execute bundled scripts before declaring done Ship untested scripts that fail on live environments
Use 5-level nested lists to capture deep conversational context Summarize complex troubleshooting sessions into vague bullet points

Reference Routing

Read the smallest relevant reference set for your current task:

Authoring & Formatting

Patterns & Architecture

Research & Sourcing

Quality, Checklists & Iteration

Final Shipping Verification Checklist

  • Frontmatter strictly contains valid agentskills.io fields (name, description, license, compatibility, metadata, allowed-tools)
  • name matches directory name exactly (build-skill)
  • Description states WHAT the skill does and WHEN to use it (<1024 characters, no < or >)
  • SKILL.md line count is under 500 lines
  • Companion prerequisite run-research is documented and linked
  • All bundled scripts in scripts/ are written in Node.js (.mjs) or Python (.py)
  • Bundled scripts execute cleanly (node scripts/skill-dl.mjs --where)
  • Every file in references/ is explicitly routed in the reference routing section
  • Full repository validation passes: python3 scripts/validate-skills.py