Agent skill

Generate Sample Metadata

by pnp in pnp/sp-dev-fx-aces

Create or fix the assets/sample.json metadata file for a sample in pnp/sp-dev-fx-aces before merging a new-sample PR.

MITAuto-check passedDevelopment

Install Generate Sample Metadata

skills CLI
$ npx skills add pnp/sp-dev-fx-aces --skill generate-sample-metadata -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install pnp/sp-dev-fx-aces generate-sample-metadata --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/pnp/sp-dev-fx-aces.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.github/skills/generate-sample-metadata .claude/skills/generate-sample-metadata && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
generate-sample-metadata
GitHub stars
139
Token cost
~2.3k tokens
SKILL.md length
967 words
Files
3 (incl. scripts)
Skills in repo
4
Repo updated
First seen
Licence
MIT

At a glance

Create or fix the assets/sample.json metadata file for a sample in pnp/sp-dev-fx-aces before merging a new-sample PR.

  • Works in 7 steps: Identify the sample folder → Gather raw facts → Derive each field → …
  • : a new-sample PR is missing assets/sample.json
  • SKILL.md covers When to Use, Reference material, Procedure and Notes
  • Runs Shell scripts from its folder; calls gh and jq; reaches twitter.com and github.com

What it does

Generate Sample Metadata is an agent skill from pnp/sp-dev-fx-aces. Create or fix the assets/sample.json metadata file for a sample in pnp/sp-dev-fx-aces before merging a new-sample PR. Use when: a new-sample PR is missing assets/sample.json, "create sample.json", "generate sample metadata", "add sample.json before merge". Derives name/title/description/thumbnails/authors from the sample README, package.json/.yo-rc.json and assets folder, checks the generated "name" for uniqueness against every other sample.json in the repo, validates required fields against…

Its SKILL.md is about 2.3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including scripts (for example `scripts/check-name-uniqueness.sh` and `scripts/gather-sample-facts.sh`).

It sits in Development. It works with npm. The repository describes itself as: Repository for the Microsoft Viva Connections Adaptive Card sample solutions from Microsoft and community. The licence is MIT.

When your agent uses it

  • : a new-sample PR is missing assets/sample.json
  • Create sample.json
  • Generate sample metadata
  • Add sample.json before merge

Example prompts

  • “create sample.json”
  • “generate sample metadata”
  • “add sample.json before merge”
  • “/generate-sample-metadata”

Requirements

  • A Bash shell

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. Identify the sample folder
  2. Gather raw facts
  3. Derive each field
  4. Check name uniqueness
  5. Write the file
  6. Validate required fields
  7. Hand off

What it can do on your machine

Read from SKILL.md and the folder at commit a3a0b1e. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 2 files in scripts/ (Shell), which the agent can run.

    Shell commands in SKILL.md call:

    • gh
    • jq

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • twitter.com
    • github.com
    • aka.ms

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Generate Sample Metadata loads about 2.3k tokens when it runs. Until then it costs about 164 tokens; SKILL.md has 967 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~164
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from pnp/sp-dev-fx-aces at commit a3a0b1e, republished under its MIT licence (© pnp). 967 words, ~2,284 tokens.

Download SKILL.mdSave it as .claude/skills/generate-sample-metadata/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
generate-sample-metadata
description
Create or fix the assets/sample.json metadata file for a sample in pnp/sp-dev-fx-aces before merging a new-sample PR. Use when: a new-sample PR is missing assets/sample.json, "create sample.json", "generate sample metadata", "add sample.json before merge". Derives name/title/description/thumbnails/authors from the sample README, package.json/.yo-rc.json and assets folder, checks the generated "name" for uniqueness against every other sample.json in the repo, validates required fields against templates/metadata-schema.json, and writes samples/<SampleName>/assets/sample.json in the same array format used by every other sample.
argument-hint
<samples/SampleName path, or PR number>

Generate Sample Metadata (assets/sample.json)

Every sample under samples/<Name>/ (and scenarios/<Name>/) must ship an assets/sample.json file. A GitHub Action (merge-sample-json.yml) concatenates all of these files on every push to main into samples.json on the gh-pages branch (the data source for the public samples gallery), and validates the result against templates/metadata-schema.json. A missing or malformed assets/sample.json breaks that build — this is why it must exist and be correct before merging, not after.

This is a companion to verify-new-sample-pr — run that skill first to build and manually test the sample, then use this skill as the final step before merge.

When to Use

  • A new-sample PR does not include samples/<Name>/assets/sample.json
  • One was included but looks incomplete/copy-pasted (e.g. still has the literal word TODO from sample-metadatatemplate.json)
  • You need to double check an existing sample.json against the schema before merge

Reference material

Procedure

1. Identify the sample folder

If given a PR number instead of a path, find the affected folder(s) the same way verify-new-sample-pr does:

bash
gh pr view <PR_NUMBER> --repo pnp/sp-dev-fx-aces --json files --jq '.files[].path' \
  | grep -oE '^samples/[^/]+' | sort -u

Check whether assets/sample.json already exists in that folder before doing anything else — if it exists, skip to step 6 (validate) instead of generating from scratch.

2. Gather raw facts

Run gather-sample-facts.sh against the sample's absolute path — it reports the SPFx version, whether React is a dependency, the image files available in assets/ (thumbnail candidates), the README's Compatibility badges, and the README's Solution/Authors table, all read-only:

bash
./.github/skills/generate-sample-metadata/scripts/gather-sample-facts.sh <abs-path>/samples/<SampleName>

Also read the full README.md ## Summary section for the description text.

3. Derive each field
FieldHow to derive it
namepnp-sp-fx-aces-<slug> where <slug> is the folder name lowercased, with any character that isn't a-z0-9 collapsed to -. Must be globally unique — verify with step 4 before finalizing.
sourceAlways the literal string "pnp".
titleFrom the README's H1. If it still contains discouraged terms per the README template guidance (SharePoint, WebPart, React, Angular, JavaScript, SPFx, ACE/sample), flag it to the user instead of silently rewriting — title wording is subjective and worth a human look.
shortDescriptionFirst sentence/paragraph of the README ## Summary section (strip any leftover > template guidance lines).
longDescriptionArray with one string — can reuse the full ## Summary paragraph(s) verbatim.
urlhttps://github.com/pnp/sp-dev-fx-aces/tree/main/samples/<SampleName> (must match the schema's URL pattern exactly, including tree/main/samples/).
creationDateTime / updateDateTimeToday's date in YYYY-MM-DD (both the same for a brand-new sample).
productsDefault ["SharePoint", "Office"]. Add "Viva" if the README Compatibility section badges or text mention Viva Connections/Teams support.
metadata{"key": "CLIENT-SIDE-DEV", "value": "React"} if react is a dependency (from gather-sample-facts.sh), else "None". Plus {"key": "SPFX-VERSION", "value": "<version>"} from .yo-rc.json.
thumbnailsOne entry per image file found in assets/ (from gather-sample-facts.sh): {"type": "image", "order": 100, "url": "https://raw.githubusercontent.com/pnp/sp-dev-fx-aces/main/samples/<SampleName>/assets/<file>", "alt": "Preview"}. If no images exist, stop and tell the user — the contributor must add a screenshot (required per CONTRIBUTING.md) before this can be completed.
authorsParse the README ## Solution table row(s): [Author Name](GitHubProfileUrl) → gitHubAccount (last path segment of the URL) and name; ([@handle](https://twitter.com/handle)) → twitter (optional field, omit if absent); trailing text after the comma → company (optional, omit if absent). Always add pictureUrl as https://github.com/<gitHubAccount>.png. If the table is missing/unparseable, fall back to the PR author's GitHub login (gh pr view <PR> --json author --jq .author.login) as gitHubAccount and ask the user to confirm the display name since it can't be reliably inferred.
referencesDefault to keeping the standard entry used by virtually every existing sample: {"name": "Viva Connections Extensibility guidance", "description": "Adaptive Card Extensions are client-side components that run in the context of a SharePoint page.", "url": "https://aka.ms/viva/connections/extensibility"}. Add more only if the sample's README references something specific worth linking.
Show full SKILL.md (362 more words)Show less
4. Check name uniqueness

Never skip this — the schema doesn't enforce uniqueness, but a duplicate name will confuse the public samples gallery data:

bash
./.github/skills/generate-sample-metadata/scripts/check-name-uniqueness.sh pnp-sp-fx-aces-<slug>

If it collides, adjust the slug (e.g. include more of the folder name) and re-check.

5. Write the file

Write a JSON array with a single object (matching the format of every existing samples/*/assets/sample.json) to samples/<SampleName>/assets/sample.json. Show the generated content to the user before finalizing — title, shortDescription, and authors involve subjective/promotional wording a human should sanity-check, not just structurally-valid JSON.

6. Validate required fields

Per templates/metadata-schema.json, these top-level fields are required: name, source, title, url, shortDescription, products, metadata, thumbnails, authors, creationDateTime, updateDateTime. Confirm none are missing/empty, and that:

  • url matches https://github.com/pnp/sp-dev-fx-aces/tree/main/(samples|scenarios)/...
  • name matches pnp-sp-fx-aces-.*
  • every thumbnails[].url actually resolves to a file that exists in assets/
  • every authors[].gitHubAccount matches ^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$

You can sanity-check the JSON is well-formed with:

bash
jq . samples/<SampleName>/assets/sample.json
7. Hand off

This file needs to end up on the same branch as the rest of the PR's changes before merging (see the maintainer-edits-a-PR guidance in repo memory / CONTRIBUTING.md discussion) — either push it to the contributor's PR branch yourself (if maintainer edits are allowed) or ask the contributor to add it. Do not merge the PR yourself; only prepare and report the file.

Notes

  • Never fabricate an author's name, company, or Twitter handle — omit optional fields rather than guess, and ask the user when the README doesn't state them.
  • Reuse an existing samples/*/assets/sample.json as a structural reference if unsure about formatting — the format has stayed consistent for years.
  • This skill only produces/validates the metadata file — it does not build the sample or test the .sppkg. Use verify-new-sample-pr for that.
  • Expect the "Sample validation" PR check to fail after you push this file for a brand-new sample — it fetches every thumbnails[].url and expects HTTP 200, but a URL pointing at raw.githubusercontent.com/pnp/sp-dev-fx-aces/main/... (the correct, canonical form used here) 404s until the PR is actually merged. This is a known false-negative, not a defect in the generated file — do not "fix" it by pointing thumbnails at the contributor's own fork/branch instead, that's the wrong long-term URL. Confirm main has no branch protection requiring this check before telling the user it's safe to merge anyway.

© pnp, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (scripts) in .github/skills/generate-sample-metadata of pnp/sp-dev-fx-aces.

  • SKILL.md
  • scripts/check-name-uniqueness.sh
  • scripts/gather-sample-facts.sh

Open the folder on GitHubat commit a3a0b1e

Compare with similar skills

Generate Sample Metadata next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Generate Sample Metadata compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Generate Sample Metadata this skillpnp/sp-dev-fx-aces139—~2.3kAutomated safety check: PassMIT
Install Anti-Slop Oxlint Rulesdmmulroy/anti-slop5.3k1 repos~2.2kAutomated safety check: PassMIT
Nx Run Tasksnomcopter/react-mosaic4.8k8 repos~613Automated safety check: PassCustom licence
Get API Docs with chubandrewyng/context-hub14k2 repos~775Automated safety check: PassMIT
Migrate Internal Package into GhostTryGhost/Ghost55k—~3.8kAutomated safety check: PassMIT
Open Code Review CLIalibaba/open-code-review44k—~3.1kAutomated safety check: PassApache-2.0

Similar skills

  • Installs, updates or migrates the vendored anti-slop Oxlint plugin in a repository, keeping local rule changes and the plugin's license and provenance files.

    5.3k GitHub starsUsed in 1 repo~2.2k tokens
    DevelopmentAuto-check passed
  • Nx Run Tasks

    nomcopter/react-mosaic

    Helps with running tasks in an Nx workspace. An agent skill from nomcopter/react-mosaic.

    4.8k GitHub starsUsed in 8 repos~613 tokens
    DevelopmentAuto-check passed
  • Get API Docs with chub

    andrewyng/context-hub

    Fetches current documentation for third-party APIs and SDKs with the chub CLI before the agent writes code against them, instead of relying on remembered API shapes.

    14k GitHub starsUsed in 2 repos~775 tokens
    DevelopmentAuto-check passed
  • Moves a package from another TryGhost repository into Ghost as an internal workspace package while keeping its Git history, with checkpoints for the steps that need an administrator.

    55k GitHub stars~3.8k tokensUpdated today
    DevelopmentAuto-check passed
  • Open Code Review CLI

    alibaba/open-code-review

    Runs the ocr command-line tool to review Git changes, a commit or a branch comparison with an AI model, returning line-level comments and optionally applying fixes.

    44k GitHub stars~3.1k tokensUpdated 3 days ago
    DevelopmentAuto-check passed
  • Cutting A Release

    TriliumNext/Trilium

    A skill your agent uses when cutting, preparing, or debugging a Trilium release — bumping the monorepo version, tagging, or diagnosing a failed "Release" workflow run.

    38k GitHub stars~3.2k tokensUpdated today
    DevelopmentAuto-check passed

More from pnp/sp-dev-fx-aces

  • Verify New Sample PR

    pnp/sp-dev-fx-aces

    Verify a "new sample" PR in pnp/sp-dev-fx-aces builds successfully, then produce a deployment + testing checklist from the sample README so it can be manually deployed and tested before merging.

    139 GitHub stars~2k tokensUpdated 9 days ago
    Auto-check passed
  • Verify Sample PR Build

    pnp/sp-dev-fx-aces

    Verify that the SPFx ACE sample(s) touched by a pull request in this repo build successfully before merging.

    139 GitHub stars~1.5k tokensUpdated 9 days ago
    Auto-check passed
  • Merge New Sample PR

    pnp/sp-dev-fx-aces

    End-to-end review-and-merge workflow for a new-sample PR in pnp/sp-dev-fx-aces.

    139 GitHub stars~1.9k tokensUpdated 9 days ago
    Auto-check passed

Works with

Categories

Questions about Generate Sample Metadata

What does Generate Sample Metadata do?

Create or fix the assets/sample.json metadata file for a sample in pnp/sp-dev-fx-aces before merging a new-sample PR. Generate Sample Metadata is an agent skill from pnp/sp-dev-fx-aces.json metadata file for a sample in pnp/sp-dev-fx-aces before merging a new-sample PR.

When should I use Generate Sample Metadata?

Generate Sample Metadata fits situations like: : a new-sample PR is missing assets/sample.json; create sample.json; generate sample metadata; add sample.json before merge.

How do I install Generate Sample Metadata in Claude Code?

Run `npx skills add pnp/sp-dev-fx-aces --skill generate-sample-metadata -a claude-code`. Or copy the skill folder (.github/skills/generate-sample-metadata in pnp/sp-dev-fx-aces) into .claude/skills/generate-sample-metadata in your project. Claude Code loads it when a task matches its description.

How do I install Generate Sample Metadata in Codex?

Run `npx skills add pnp/sp-dev-fx-aces --skill generate-sample-metadata -a codex`. Or copy the skill folder (.github/skills/generate-sample-metadata in pnp/sp-dev-fx-aces) into .agents/skills/generate-sample-metadata in your project. Codex loads it when a task matches its description.

Can I use Generate Sample Metadata in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pnp/sp-dev-fx-aces --skill generate-sample-metadata -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/generate-sample-metadata, .gemini/skills/generate-sample-metadata, .github/skills/generate-sample-metadata and .opencode/skills/generate-sample-metadata in your project.

What does Generate Sample Metadata need to run?

Going by SKILL.md and its folder, Generate Sample Metadata needs a shell for the scripts in its folder and the command-line tools its instructions call (gh and jq). Our summary lists: A Bash shell.

Does Generate Sample Metadata access the network?

SKILL.md names 3 domains. In commands or code: twitter.com, github.com and aka.ms; the agent is likely to contact these when it follows the instructions. This is read from the text; nothing was executed.

Is Generate Sample Metadata safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Generate Sample Metadata use?

Generate Sample Metadata is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Generate Sample Metadata use?

About 2.3k tokens (SKILL.md is roughly 9.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Generate Sample Metadata?

Skills that share tags, products or a category with Generate Sample Metadata: Install Anti-Slop Oxlint Rules (dmmulroy/anti-slop, 5.3k stars), Nx Run Tasks (nomcopter/react-mosaic, 4.8k stars), Get API Docs with chub (andrewyng/context-hub, 14k stars) and Migrate Internal Package into Ghost (TryGhost/Ghost, 55k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Generate Sample Metadata?

pnp (a GitHub organization) maintains it in pnp/sp-dev-fx-aces, which has 139 GitHub stars. The repository holds 4 skills in this directory. The repository was last updated on September 28, 2026.

Source: pnp/sp-dev-fx-aces on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.