Scaffold Skill

Quickly create a single AI documentation file with correct structure, frontmatter, and smart defaults based on the project context.

Note: This skill uses text-based prompts instead of AskUserQuestion due to a known bug where AskUserQuestion auto-completes inside plugin skills (GitHub #29547, #29733).

Step 1: Determine Type

Parse $ARGUMENTS to determine what to scaffold.

Valid types:

• skill — A SKILL.md file in .claude/skills/[name]/SKILL.md
• rule — A rule file in .claude/rules/[name].md AND .cursor/rules/[name].mdc
• agent — An agent definition in .claude/agents/[name].md
• hook — Hook configuration (appended to or creating hooks.json)
• command — A command in .claude/commands/[name].md
• plugin — A plugin manifest at .claude-plugin/plugin.json
• settings — Claude Code settings at .claude/settings.json
• config — Codex config at .codex/config.toml
• ignore — An ignore file (.cursorignore, .codexignore, or .claudeignore)

If $ARGUMENTS is empty or unclear, present the following to the user and wait for their response:

What would you like to scaffold?

1. skill — A SKILL.md file in .claude/skills/[name]/SKILL.md
2. rule — Rule files in .claude/rules/[name].md AND .cursor/rules/[name].mdc
3. agent — An agent definition in .claude/agents/[name].md
4. hook — Hook configuration (appended to or creating hooks.json)
5. command — A command in .claude/commands/[name].md
6. plugin — A plugin manifest at .claude-plugin/plugin.json
7. settings — Claude Code settings at .claude/settings.json
8. config — Codex config at .codex/config.toml
9. ignore — An ignore file (.cursorignore, .codexignore, or .claudeignore)

Enter a number or type the name directly:

Wait for the user to respond before proceeding. Parse their response to determine the type.

Step 2: Gather Details

Ask the user for required details. Ask only what is needed for the selected type.

For skill:

• Name (will become directory name and skill name in frontmatter)
• One-sentence purpose (used in description field)
• Tools needed (offer: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent, WebSearch, WebFetch)
• Does it need user input mid-run? (determines whether to include AskUserQuestion)

For rule:

• Name (becomes filename)
• Topic / purpose
• Target package or global scope? (determines globs or alwaysApply)
• Any specific file patterns this applies to? (for auto-attach globs)

For agent:

• Name
• Role description (what is the agent's specialty?)
• Is it read-only or read+write?
• What tools should it have access to?

For hook:

• Event: PreToolUse or PostToolUse
• What triggers it? (specific tool name or regex pattern)
• What command should it run?

For command:

• Command name (becomes filename and invocation /[plugin]:[name])
• What does it do?
• Does it accept arguments?

For plugin:

• Plugin name
• Description
• Author/username

For settings:

• Any specific tools to deny by default?
• Any sensitive file paths to protect?

For config (.codex/config.toml):

• Default shell (bash, zsh, sh)?
• Any environment variables to set in sandbox?
• Timeout preference?

For ignore:

• Which tool? (cursor / codex / both)
• Any specific paths to add beyond .env files?

Step 3: Select Template

Load the appropriate template from the templates/ directory. Check:
/plugins/docsmith/skills/scaffold/templates/

If the template file does not exist, use the built-in template below.

Built-in templates:

Skill Template

---
name: [name]
description: [description]
allowed-tools: [tools]
argument-hint: [hint or omit]
---

# [Name] Skill

[Brief explanation of what this skill does and when to use it.]

## Step 1: [First Step]

[Instructions for the first step.]

## Step 2: [Second Step]

[Instructions for the second step.]

## Verification

After completing all steps:
- [ ] [Verification item 1]
- [ ] [Verification item 2]

Rule Template (Claude — .claude/rules/)

# [Topic] Rules

[Brief explanation of why this rule exists.]

## Required Patterns

[What to always do.]

## Forbidden Patterns

[What to never do.]

## Examples

### Correct
\`\`\`[language]
// Good example
\`\`\`

### Incorrect
\`\`\`[language]
// Bad example
\`\`\`

Rule Template (Cursor MDC — .cursor/rules/)

---
description: [Description with keywords for discovery]
alwaysApply: [true|false]
globs:
  - [glob pattern if auto-attach]
---

# [Topic]

## ALWAYS
- [Required pattern 1]
- [Required pattern 2]

## NEVER
- [Forbidden pattern 1]
- [Forbidden pattern 2]

\`\`\`[language]
// DO: correct example
// DON'T: incorrect example
\`\`\`

Agent Template

---
name: [name]
description: [Description — Claude uses this to decide when to delegate]
allowed-tools: [tools]
---

# [Name]

[Role description and specialty. What does this agent know that makes it valuable?]

## Responsibilities

- [Responsibility 1]
- [Responsibility 2]

## Constraints

- [Constraint 1 — e.g., read-only, no destructive operations]
- [Constraint 2]

## Output Format

[How should this agent format its results?]

Hook Template (hooks.json entry)

{
  "hooks": {
    "[Event]": [
      {
        "matcher": "[tool-name-pattern]",
        "hooks": [
          {
            "type": "command",
            "command": "[shell command]"
          }
        ]
      }
    ]
  }
}

Command Template

---
description: [What this command does]
argument-hint: [hint or omit]
---

# [Command Name]

[What this command does in one sentence.]

[Step-by-step instructions or single command to run.]

Settings Template

{
  "permissions": {
    "allow": [],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(:(){ :|:& };:)"
    ]
  }
}

Codex Config Template

[sandbox]
network = false

[shell]
default = "bash"
timeout = 120

[env]
# Add environment variables available in sandbox
# MY_VAR = "value"

Ignore File Template

# AI Documentation Ignore File
# Files listed here are not indexed or read by [agent]

# Environment and secrets
.env
.env.*
*.pem
*.key
secrets/

# Build artifacts
dist/
build/
.next/
node_modules/

Step 4: Fill Template

Replace all placeholder values with project-specific content:

• Use the user's answers from Step 2
• If inside a project, read the detected package manager / framework / naming conventions
• Use actual file paths and patterns from the real project
• For rules, include a real DO/DON'T code example specific to the project's language

Progressive disclosure check — ask before writing:

• Does this file try to do too much? Should some sections live in a separate reference file instead?
• alwaysApply rules should stay focused and brief — they load on every interaction.
• Rule files should cover one topic clearly. Multiple distinct topics signal a split is needed.

Rough typical ranges for orientation:

Type	Typical Range
Rule file	50–200 lines
alwaysApply MDC body	Keep brief — loads every interaction
Skill file	Proportional to complexity

Anti-redundancy: Before creating a new file, scan existing files in the target directory for overlapping content. Cross-reference existing rules rather than duplicating them.
Progressive disclosure: Rule files — brief DO/DON'T pattern in main section, code examples only if essential. Detail belongs in reference docs, not inline.

Step 5: Create Files

For all types except "rule": Create the single file in the correct location.

For "rule" type: Create BOTH files:

1. .claude/rules/[name].md — Claude Code format (no frontmatter, markdown headers)
2. .cursor/rules/[name].mdc — Cursor MDC format (YAML frontmatter + bold ALWAYS/NEVER)

Ensure the directory exists before writing. If creating a skill, create the directory:
.claude/skills/[name]/SKILL.md

For hooks, check if hooks.json already exists:

• If yes: read it, merge the new hook into the appropriate event array, write back
• If no: create it with the new hook as the only entry

Step 6: Report

Output a brief confirmation:

Scaffolded: [type] "[name]"

Files created:
- [path/to/file]
[- path/to/second/file if rule]

Next steps:
- [Any immediate action needed, e.g., fill in examples, add to plugin manifest]