how to structure a .claude/skills/<name>/SKILL.md with valid YAML frontmatter for name and description fields

By Sai Kiran Pandrala · Last verified: 2026-05-31 · Source: vendor status pages and changelogs, community forums (r/nocode, r/automation, r/GoogleAppsScript, r/PowerAutomate, r/n8n, r/make, r/ClaudeAI), in-product help, vendor help centers

Running into how to structure a .claude/skills/<name>/SKILL.md with valid YAML frontmatter for name and description fields on Claude Code Skills - SKILL.md Authoring and Composition - 2026 is one of the more common stalls I see when I am deep in a scenario or a script and the platform suddenly refuses to cooperate. My standard pattern for this is to capture the run history first, then walk the fix below - here is what actually moves the needle when the vendor docs are too generic and you do not have time to file a support ticket.

What how to structure a .claude/skills//skill.md with valid yaml frontmatter for name and description fields actually involves on Claude Code Skills - SKILL.md Authoring and Composition - 2026

On Claude Code Skills - SKILL.md Authoring and Composition - 2026 when this lands in my queue the tools I lean on first are claudelog or CLAUDE_LOG_LEVEL=debug env var output, Node fs.readdirSync probe to confirm skill folder layout, Anthropic skill-creator skill from anthropics/skills repo. Each of these surfaces a different layer of the failure - keep at least the first one in your personal notes so the next time this happens you do not start cold.

For verification on Claude Code Skills - SKILL.md Authoring and Composition - 2026, the methods that survive contact with a real Monday-morning workload are git log -- .claude/skills/<name>/ to track skill version history and test -f .claude/skills/<name>/SKILL.md && head -20 to inspect frontmatter. Anything less than that and you are shipping on vibes.

Authoritative sources for Claude Code Skills - SKILL.md Authoring and Composition - 2026 that I cross-reference before committing to a fix: code.claude.com/docs/en/skills, resources.anthropic.com (Complete Guide to Building Skills for Claude), platform.claude.com/docs/en/agents-and-tools/agent-skills/overview. Marketing blog posts and Medium writeups are signal, not ground truth.

The rest of this page is the structured fix path. Start with diagnose, then remediation, then the automation options so you do not have to do this by hand the next time it surfaces. Verify and safety sections at the end are the discipline that keeps the fix from regressing the next time you open the platform.

Identify

Second pass: open the Claude Code Skills - SKILL.md Authoring and Composition - 2026 workspace admin or settings panel and look at the audit log or activity feed for the failing window. Most modern automation platforms surface an audit trail (the platform's execution history, the connector run log, the integration activity feed). The audit log tells you whether the failure was your action, a teammate changing a connected account in the same minute, or a platform-side rollout. Many "permission denied" or "connection not found" reports trace to a credential-level change pushed in the same admin panel in the previous hour - the audit trail makes that obvious without guesswork.

Start by capturing the exact failure signal in writing before you change a single thing on your Claude Code Skills - SKILL.md Authoring and Composition - 2026 setup. In the browser that is the failing request in DevTools Network tab (right-click, Copy as cURL) plus the JS console error. In the platform UI that is the error toast text, the timestamp, and the scenario or workspace id from the URL. On the Claude Code Skills - SKILL.md Authoring and Composition - 2026 status page capture the incident id and timestamp. Screenshot it. Do not paraphrase. Most Claude Code Skills - SKILL.md Authoring and Composition - 2026 support workflows will not even route the ticket without the workspace id or correlation id - the support rep pastes it straight into the internal trace tool and the first response is "we see your request, here is what the backend logged."

Sixth: pin down the latency and reliability envelope on the Claude Code Skills - SKILL.md Authoring and Composition - 2026 session under real working conditions. Run a long-duration sanity test by executing the failing scenario 10 times over 15 minutes, logging the timestamp and the result (success / error code / which step failed) per attempt to a notes file. Watch for the breakpoint where the success rate dips below 80 percent - that is your real signal that something is wrong, not the one-off failure that prompted the investigation. If you are on a marginal network (cafe wifi, mobile hotspot, hotel network), run the same test on a wired or known-good connection before assuming the platform is the problem. Capture the breakpoint in your personal notes next to the platform version, the account, and the workspace id - the next time this happens to a teammate, the notes are gold.

Field notes from real Claude Code Skills - SKILL.md Authoring and Composition - 2026 incidents

Last sprint I lost most of an afternoon to an Claude Code Skills bug before remembering that ripgrep across .claude/skills for description collisions would have surfaced the failing step in under a minute. The Agentic AI space inside Claude Code Skills changes fast enough that a Stack Overflow answer from 18 months ago is already half wrong, check the dates before you trust the snippet. Before I mark an Claude Code Skills ticket resolved I always run `claude --dangerously-skip-permissions OFF and invoke skill via natural language prompt` once more and screenshot the output, that habit has caught at least three silent regressions for me.

Tools I actually reach for

For most Claude Code Skills - SKILL.md Authoring and Composition - 2026 stalls I start with VS Code YAML extension for SKILL.md frontmatter validation, fall back to Anthropic skill-creator skill from anthropics/skills repo, claude --debug verbose startup log showing loaded skills, Claude Code /agents command skill list panel when VS Code YAML extension for SKILL.md frontmatter validation cannot surface the answer, and keep Claude Code plugin-dev SKILL.md as reference scaffolding handy for the cases where neither answers. That ordering is not academic - it matches the layers of the failure as they tend to surface, so the cheapest signal lands first and the heavier tooling only comes out when the simpler answer does not hold up. My muscle-memory shortcut for this is to run the first tool while the failing screen is still open, not after I have already restarted the platform.

Verification I run before I call it fixed

Before I mark a Claude Code Skills - SKILL.md Authoring and Composition - 2026 stall resolved, the verification loop below is what I actually run. Each step proves a different layer is green, and the order matters - the cheaper checks gate the more expensive ones.

claude /agents and confirm the skill appears with correct description

If that one comes back clean, move to the next check. If it does not, stop and dig in there before layering more verification on top of a red signal.

claude --dangerously-skip-permissions OFF and invoke skill via natural language prompt

If that one comes back clean, move to the next check. If it does not, stop and dig in there before layering more verification on top of a red signal.

wc -c on description value to assert under 1024 characters

If that one comes back clean, move to the next check. If it does not, stop and dig in there before layering more verification on top of a red signal.

git log -- .claude/skills/<name>/ to track skill version history

If that one comes back clean, move to the next check. If it does not, stop and dig in there before layering more verification on top of a red signal.

test -f .claude/skills/<name>/SKILL.md && head -20 to inspect frontmatter

Only when every line above runs clean do I close the loop and update my notes with the timestamps.

Where I check first when the docs disagree

When two sources contradict each other on a Claude Code Skills - SKILL.md Authoring and Composition - 2026 detail, the disambiguation order I lean on is stable. I usually check code.claude.com/docs/en/skills for the ground-truth view on this part of Claude Code Skills - SKILL.md Authoring and Composition - 2026. I usually check github.com/anthropics/skills for the ground-truth view on this part of Claude Code Skills - SKILL.md Authoring and Composition - 2026. I usually check platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices for the ground-truth view on this part of Claude Code Skills - SKILL.md Authoring and Composition - 2026. Marketing blog posts and Medium writeups are signal, not ground truth, and I treat them as such until the references above either confirm or contradict the claim.

Solution-focused remediation path

Before any destructive step on a Claude Code Skills - SKILL.md Authoring and Composition - 2026 workspace, slow down and stage rollback. Snapshot the current platform version, the current workspace settings (Settings -> screenshot every tab), the connected-apps list, the current sharing policy, and the current member list to a notes entry first. Capture the failing screenshot, the Claude Code Skills - SKILL.md Authoring and Composition - 2026 incident id if any, and the timestamp window. Photograph (screenshot) the workspace state from two angles: the scenario or script that is failing, and the workspace settings page that controls the relevant policy. Then do the destructive step (revoke a connector, change a sharing default, remove a member, delete a connected app) inside a test workspace or a test scenario first, never the whole workspace. Capture the platform version, the API permissions, the connected-app list, the workspace member roster, and the relevant integration log snapshot to your notes before the destructive step. Decision point: if you are on a paid plan, the cheapest correct path is almost always to open the in-product support chat in parallel with the rollback - the support rep can confirm whether a vendor-side rollout is responsible while you are still staging the change, which avoids a needless workspace edit if the fix is server-side.

Start by sorting the Claude Code Skills - SKILL.md Authoring and Composition - 2026 failure into one of three buckets, because roughly 80% of cases fall here. Bucket one is auth / account drift: you are signed into the wrong account, the SSO session expired, MFA tripped, or the workspace owner changed your role. Bucket two is sync / cache drift: the platform has a stale view of the connector, the offline cache disagrees with the cloud, or a recent edit has not synced yet. Bucket three is plan / quota / sharing: the action requires a higher plan tier, the workspace hit an operation or task cap, or the connector you are trying to use was revoked. Pick the bucket first, then act. Before you act, capture a baseline screenshot of the failing run plus the run id so you can prove whether the fix actually moved the needle. Decision point: if the failure is intermittent and you are on a paid Business / Enterprise plan, open the in-product support chat first - vendor support on a paid tenant beats hours of speculative debugging on cost and on liability if the failure recurs.

If the Claude Code Skills - SKILL.md Authoring and Composition - 2026 symptom started after a platform auto-update, a browser extension install, or a workspace setting change, treat versioning and environment as the prime suspect. Roll the platform back to the previous build if the Claude Code Skills - SKILL.md Authoring and Composition - 2026 platform supports it (most do not auto-rollback - in that case, sign in on the web app to bypass the desktop build entirely while you wait for a fix). Open a private / incognito browser window with no extensions, sign in, and reproduce; if private-window works, the issue is a browser extension or a cached service worker. If both desktop and private-web fail with the same payload and the same account, you have an account-level or workspace-level issue. Decision point: if the rolled-back or private-window session still fails and you are on a paid plan, open the in-product help chat with the failing screenshot; on the free tier the path is the community forum or r/claude with a minimal reproduction. Save the working platform version to your notes so the next rollback is a one-line "pin to build X."

Automate this fix so you do not do it twice

Automate Claude Code Skills - SKILL.md Authoring and Composition - 2026 session + sharing-policy snapshots via vendor CLI or API

On the Claude Code Skills - SKILL.md Authoring and Composition - 2026, regular session and policy snapshots catch silent role changes, sharing-default drift, and stale OAuth grants well before the workflow starts failing in prod. Pair vendor health checks (the platform's admin SDK, the platform's users API, the connector listing) with a token-validity check so both vendor-side and account-side issues land in one folder. Run the scheduled task on a control plane device (a small VPS, a GitHub Actions runner, a Cloud Function) under a tightly scoped service account that mirrors the real workspace policy.

# List workspace members + roles
curl -H "Authorization: Bearer $PLATFORM_TOKEN" \ https://api.example.com/v1/workspace/members \ > claude-members.json
# List active connectors + their last-tested timestamp
curl -H "Authorization: Bearer $PLATFORM_TOKEN" \ https://api.example.com/v1/connectors \ > claude-connectors.json
# Validate the bearer token itself
curl -H "Authorization: Bearer $PLATFORM_TOKEN" \ https://api.example.com/v1/me \ > claude-me.json

Scrape Claude Code Skills - SKILL.md Authoring and Composition - 2026 workspace audit log + integration log via scheduled job

For the Claude Code Skills - SKILL.md Authoring and Composition - 2026, workflow faults usually surface as failed run executions, audit-log denials, or quota nags before a full hang. A weekly scheduled job that exports the last 7 days of these events to CSV gives you a paper trail to correlate with platform updates, policy changes, and vendor incidents without staring at the settings panel live. Register the task via cron (Linux / macOS), Windows Task Scheduler (schtasks /create /XML), or a GitHub Actions schedule, then write the CSV to Dropbox / OneDrive / Google Drive for retention. Subscribe a simple dashboard (Google Sheets with a daily import, Airtable scheduled sync, Notion database via the API) to the same bucket so audit events from every Claude Code Skills - SKILL.md Authoring and Composition - 2026 workspace converge on a single view without per-workspace clicking.

# Export the platform audit log via the API (Enterprise plan)
curl -X POST https://api.example.com/v1/audit_logs \ -H "Authorization: Bearer $PLATFORM_TOKEN" \ -H "Accept: application/json" \ -d '{"start_date":"2026-05-24","end_date":"2026-05-31"}' \ -o claude-audit-log.json
# Export the run history for the last 7 days
curl -G https://api.example.com/v1/runs \ -H "Authorization: Bearer $PLATFORM_TOKEN" \ --data-urlencode "oldest=$(date -d '7 days ago' +%s)" \ -o claude-runs.json

Monitor + alert via Claude Code Skills - SKILL.md Authoring and Composition - 2026 admin reports, audit logs, and personal dashboard ingestion

For the Claude Code Skills - SKILL.md Authoring and Composition - 2026, the most useful long-running telemetry is the admin reports + audit logs shipped to a personal dashboard (Google Sheets daily import, Airtable scheduled sync, Notion database via the API, Grafana with a CSV source) and graphed on a single view. Pair that with synthetic monitoring (a small script that triggers the failing scenario or runs the failing action every 5 minutes from at least two devices) so a regional incident lights up before teammates report it. Subscribe the personal inbox or a private Slack channel to the Claude Code Skills - SKILL.md Authoring and Composition - 2026 status page (Atom/RSS or Statuspage webhook) plus the vendor X/Twitter status handle so an open incident self-correlates with the synthetic failures.

# Tiny synthetic monitor - hit the Claude Code Skills - SKILL.md Authoring and Composition - 2026 health endpoint every 5 minutes
while true; do curl -s -o /dev/null -w "%{http_code} %{time_total} $(date -Iseconds)\n" \ -H "Authorization: Bearer $TOKEN" \ https://api.example.com/v1/me \ >> ~/logs/claude-synth.log sleep 300
done

Pitfalls to dodge

Platform auto-updates during an active failure are the textbook way to break a Claude Code Skills - SKILL.md Authoring and Composition - 2026 workflow further, and the trap catches experienced builders because the release notes look like they describe exactly the bug at hand. Never accept a major platform version bump while you are in the middle of debugging, never push a beta build unless the release notes tie it to a specific advisory for your symptom, and never roll forward when a rollback is available. Skipping a required workspace-policy migration leaves a known regression path open even after the immediate fix, so check the deprecation timeline on the Claude Code Skills - SKILL.md Authoring and Composition - 2026 changelog before deciding to wait.

The other half is trusting the vendor status page verdict by itself. Vendor status pages can miss regional incidents that only hit one POP, the Trust Center will not flag a connector degradation, and the activity feed entries can lag several minutes behind the actual failure. Cross-reference the vendor X/Twitter status handle, Downdetector, the failing screenshot timestamps, and the on-screen symptom narrative before committing to a destructive remediation on Claude Code Skills - SKILL.md Authoring and Composition - 2026.

Resolve

• Reproduce the original failing run against Claude Code Skills - SKILL.md Authoring and Composition - 2026 on the same device AND a second device with the same account. If the failing toast or error code still surfaces on any device, you have not fixed it.
• Watch for 24 to 48 hours via the Claude Code Skills - SKILL.md Authoring and Composition - 2026 workspace audit log + the integration history + your personal notes. Cached error states and CDN caches mask slow-burn drift and intermittent regional issues.
• Smoke-test under realistic load: replay the workflow against a test workspace for at least 30 minutes at your normal working pace, log success / error and the timestamp per attempt to a notes file.
• Capture the new state in a personal notes entry so the next time this happens you do not rediscover it. Note platform version + workspace policy + connected-apps list + failing screenshot + verbatim error string + fix applied. Push to a shared team wiki if your team uses one.
• If the fix involved an API token rotation or a workspace policy change, commit the new token to your password manager and screenshot the workspace settings for archival.

Safety, rollback, blast radius

• Test in a Claude Code Skills - SKILL.md Authoring and Composition - 2026 test workspace or on a duplicate scenario first before any change that touches the real workspace. Snapshot the platform version, the workspace settings, the connected-apps list, and the sharing policy before changing anything.
• Apply the principle of least surprise when granting share access or connected-app permissions. Review the share list against the people who actually need access - extra shares are extra blast radius.
• Use idempotent runs where the Claude Code Skills - SKILL.md Authoring and Composition - 2026 API supports it (the platform's run id de-dupe, external id keys on destination records) so a retried run does not create duplicate records.
• Know your rollback path. Platform version rollback is a one-line download-and-install; an API token rotation is reversible if you kept the old token in the password manager during cutover; a workspace policy change is reversible only if you saved the previous policy in a screenshot.
• For team-wide or workspace-wide changes, line up a maintenance window with team notification before pushing through the admin console.

FAQ

Related fixes

Related guides worth a look while you sort this one out:

• how to pin a skill to a specific Claude model using the model field in SKILL.md frontmatter
• how to debug 'skill name must be lowercase kebab-case under 64 chars' validation error in SKILL.md
• how to distribute a skill pack as a Claude Code plugin under plugins/ /skills/
• how to fix skill triggering on wrong tasks by tightening the frontmatter description verbs
• how to migrate ad-hoc CLAUDE.md instructions into a discoverable Agent Skill folder
• how to reference helper scripts from SKILL.md using relative scripts/ paths that survive plugin packaging