Claude-skill-registry writing-skills

Use when troubleshooting skill issues, understanding CC platform limitations, or reviewing skills for CC-specific gotchas. For skill creation tutorials, use plugin-dev:skill-development.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/cc-writing-skills" ~/.claude/skills/majiayu000-claude-skill-registry-writing-skills-21bf27 && rm -rf "$T"

manifest: skills/data/cc-writing-skills/SKILL.md

Writing Skills

Scope

This skill covers Claude Code platform gotchas and limitations. For different purposes, use:

Comprehensive tutorials:
```
plugin-dev:skill-development
```
TDD methodology:
```
superpowers:writing-skills
```
This skill: Bug workarounds, version-specific behavior, issue tracking

Facts

The frontmatter
```
name
```
is what appears in autocomplete list when typing
```
/
```
in session. So
```
name: foo
```
would allow user to submit
```
/foo
```
to trigger that skill.

The skill directory name appears printed in session when skill is activated by the agent. E.g. dir

/foobar

would yield e.g.

⏺ Skill(foobar)
⎿  Initializing…

```
Skill(foobar)
```
is also the syntax for granting permission to the skill in config
Development Related
- Skills created or modified in ~/.claude/skills or .claude/skills are immediately available without restarting the session (added in v2.1.0)

Key Rules (from Anthropic guide)

Frontmatter:

```
name
```
: Max 64 chars, lowercase letters/numbers/hyphens only, no reserved words ("anthropic", "claude")
```
description
```
: Max 1024 chars, non-empty, third person, critical for discovery
- Good: "Processes Excel files and generates reports"
- Avoid: "I can help you process Excel files"
Use gerund form (verb + -ing) for names:
```
processing-pdfs
```
,
```
analyzing-spreadsheets
```

Body:

Keep SKILL.md under 500 lines
"Claude is already very smart. Only add context Claude doesn't already have."
Paths are relative to skill directory — use
```
scripts/foo
```
not
```
.claude/skills/my-skill/scripts/foo
```

File Structure

my-skill/
├── SKILL.md          # Main (<500 lines)
├── reference/        # Detailed docs (loaded on demand)
├── scripts/          # Executable (zero-token)
└── assets/           # Static files (banners, templates)

Naming: Directory name = skill name (kebab-case). Opening

# Title

= titleized skill name.

Skill Body Headings

Heading	Purpose
`## CRITICAL`	Safety rules at top
`## Use Cases`	Refine when skill applies
`## Requirements`	Deps, env vars, how to handle absence
`## Steps`	Sequential workflow
`## Operations`	Menu of actions
`## Examples`	User prompt → Claude action
`## Reference`	Internal docs
`## Notes`	Gotchas, tips
`## Appendix`	Implementation details

Tools for Skills

Tool	Purpose	Reference
AskUserQuestion	Interactive prompts (max 4 options)	tool-ask-user-question.md
TodoWrite	Task checkboxes	tool-todo-write.md
Bash	Execute bundled scripts (zero-token)	pattern-script-bundling.md
Read	Load reference files on demand	pattern-progressive-disclosure.md

Frontmatter Options

Field	Purpose	Reference
`name` , `description`	Identity and discovery	config-frontmatter.md
`allowed-tools`	Skip permission prompts	config-allowed-tools.md
`context: fork`	Run in isolated subagent	config-context-fork.md
`hooks`	PreToolUse/PostToolUse/Stop	config-hooks.md
`user-invocable`	Show in slash menu	config-frontmatter.md
`disable-model-invocation`	User-triggered only	config-frontmatter.md

Platform Limitations

Cannot control:

Collapsed/expanded state of tool output - see limitation-output-collapse.md
Terminal theme/colors
Streaming behavior
Custom UI widgets
Status line refresh from skills - see feature-status-line.md

Patterns

Pattern	Reference
Code examples	pattern-code-examples.md
Progressive disclosure	pattern-progressive-disclosure.md
Script bundling	pattern-script-bundling.md

When Reviewing Skills

Apply criteria from both this skill (CC platform) and

superpowers:writing-skills

(methodology).

Platform checklist:

Frontmatter valid? (name format, description length, third person)
SKILL.md under 500 lines?
Reference files used for detailed content?
Code examples have language tags?
Known limitations acknowledged? (output collapse, status line)
Hooks correctly structured if used?
```
allowed-tools
```
syntax correct if used?

Methodology checklist (from

superpowers:writing-skills

CSO applied? (Claude-Specific Optimization)
Token-efficient structure?
Clear trigger conditions in description?