agentleFS
astrowickedastrowicked/devils-council/skills/create-persona/SKILL.md

create-persona

Skill2 starsChanged 6 months agoMITView on GitHub

Interactive scaffolder for custom devils-council personas. Collects voice-kit fields, validates schema, coaches voice distinctness. Writes to plugin data workspace.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. len5ky/synth-personas★ 40same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

27 rules. About 0 are common, 23 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈23

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If $ARGUMENTS is provided, use it as the persona slug.

    line 26
  2. Distinctive:

    If the workspace already exists, use AskUserQuestion:

    line 42
  3. Distinctive:

    If the user selects "Cancel", stop execution.

    line 48
  4. Very specific:

    Do NOT offer chair or classifier tiers.

    line 61
  5. Distinctive:

    If the user selects "bench", proceed to Step 1b (Triggers).

    line 64
  6. Distinctive:

    If the user selects "core", skip to Step 2.

    line 65
  7. Distinctive:

    Read available signal IDs from the signal registry using Bash tool:

    line 71
  8. Very specific:

    After the user responds, split by comma and trim whitespace.

    line 83
  9. Distinctive:

    If any ID is invalid, report which ones failed and re-ask.

    line 90
  10. Distinctive:

    After collecting banned phrases, compute overlap with all shipped persona sidecars.

    line 162
  11. Distinctive:

    If any overlap > 30% is detected, inform the user which phrases overlap with which persona, then use AskUserQuestion:

    line 216
  12. Distinctive:

    If "Diversify", ask for replacement phrases and re-run the overlap check.

    line 223
  13. Distinctive:

    If "Keep as-is", proceed.

    line 224
  14. Distinctive:

    If any objection contains a banned phrase, flag it using AskUserQuestion:

    line 233
  15. Distinctive:

    If "Rephrase", ask for a replacement objection via AskUserQuestion.

    line 239
  16. Distinctive:

    If "Keep", accept it -- the author intentionally quotes the phrase.

    line 240
  17. Distinctive:

    If "Edit", use AskUserQuestion to ask which step to revisit (0-6), then loop back to that step and re-collect from there forward.

    line 314
  18. Distinctive:

    If "Cancel", stop execution.

    line 316
  19. Distinctive:

    If "Write it", proceed to Step 8.

    line 317
  20. Distinctive:

    Create the workspace directory structure using Bash tool:

    line 323
  21. Distinctive:

    Write the all-in-one agent file (the full assembled content from the preview) to the workspace using the Write tool:

    line 330
  22. Distinctive:

    Run the validator on the written file using Bash tool:

    line 346
  23. Distinctive:

    After 3 failed validation attempts (D-09 bail logic): Write the file anyway with a warning:

    line 374
  24. Distinctive:

    After validation passes, split the all-in-one file into the two-file format the production plugin expects:

    line 388
  25. Distinctive:

    Write both files using the Write tool.

    line 428
  26. Distinctive:

    No shell-injection: All shell operations in this wizard use the Bash tool explicitly.

    line 453
  27. Very specific:

    Workspace isolation: All files are written to ${CLAUDE_PLUGIN_DATA}/create-persona-workspace/<slug>/, not directly into the plugin's …

    line 459

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

create-persona

Interactive persona scaffolder for the devils-council plugin. This wizard guides you through creating a schema-valid custom persona by collecting voice-kit fields one at a time, coaching you on voice distinctness, and producing a validated persona file in a workspace directory.

This automates the manual workflow described in docs/AUTHORING.md. Where AUTHORING.md asks you to read PERSONA-SCHEMA.md and author a file by hand, this wizard collects the same fields interactively, enforces quality minimums inline, and runs validate-personas.sh before declaring success.


Step 0: Slug and Workspace Check (D-07)

If $ARGUMENTS is provided, use it as the persona slug. Otherwise, use AskUserQuestion to collect the persona name:

Header: "Persona Name" Question: "What slug should this persona have? Use kebab-case (e.g., cost-hawk, latency-hound). This becomes the filename."

Validate the slug matches the kebab-case pattern [a-z0-9]+(-[a-z0-9]+)*. Reject uppercase, underscores, spaces, dots, and path-traversal sequences (../). If invalid, explain the constraint and re-ask.

Then check if a workspace already exists for this slug using Bash tool:

test -d "${CLAUDE_PLUGIN_DATA}/create-persona-workspace/<slug>/" && echo "EXISTS" || echo "NEW"

If the workspace already exists, use AskUserQuestion:

Header: "Workspace Already Exists" Question: "A persona workspace for '<slug>' already exists. What would you like to do?" Options: ["Overwrite (start fresh)", "Cancel"]

If the user selects "Cancel", stop execution. If "Overwrite", proceed (the existing workspace will be replaced when files are written).


Step 1: Tier Selection (D-01 linear wizard)

Use AskUserQuestion:

Header: "Tier" Question: "Which tier is this persona?" Options: ["core -- Always invoked on every review", "bench -- Auto-triggered by structural signals"]

Do NOT offer chair or classifier tiers. Those are internal tiers reserved for the Council Chair and Haiku artifact-classifier respectively.

If the user selects "bench", proceed to Step 1b (Triggers). If the user selects "core", skip to Step 2.


Step 1b: Triggers (bench tier only, D-03)

Read available signal IDs from the signal registry using Bash tool:

jq -r '.signals | to_entries[] | "\(.key) -- \(.value.description)"' "${CLAUDE_PLUGIN_ROOT}/lib/signals.json"

Present the full list of available signals to the user, then use AskUserQuestion:

Header: "Triggers" Question: "Which signal(s) trigger this persona? List one or more signal IDs separated by commas. These are the structural patterns that auto-invoke your persona when detected in an artifact."

After the user responds, split by comma and trim whitespace. Validate each ID exists in lib/signals.json using Bash tool:

jq -e --arg id "<SIGNAL_ID>" '.signals | has($id)' "${CLAUDE_PLUGIN_ROOT}/lib/signals.json"

If any ID is invalid, report which ones failed and re-ask. Continue until all IDs are valid.


Step 2: Primary Concern (D-01, D-03)

Show existing persona primary concerns as negative examples (what NOT to duplicate). Read them using Bash tool:

for f in ${CLAUDE_PLUGIN_ROOT}/persona-metadata/*.yml; do
  slug=$(basename "$f" .yml)
  pc=$(yq -r '.primary_concern // empty' "$f" 2>/dev/null || python3 -c "import yaml,sys; d=yaml.safe_load(open(sys.argv[1])); print(d.get('primary_concern',''))" "$f")
  [ -n "$pc" ] && printf '  %s: %s\n' "$slug" "$pc"
done

Present the list, then use AskUserQuestion:

Header: "Primary Concern" Question: "What is this persona's primary concern? This is the value-system anchor -- one sentence ending with '?' that defines what this persona optimizes for above all else. Make it distinct from the existing concerns shown above."

Validate: the response must end with ? and be non-empty. If invalid, explain and re-ask.


Step 3: Blind Spots

Use AskUserQuestion:

Header: "Blind Spots" Question: "List 2-4 things this persona explicitly does NOT care about (blind spots). These are discipline declarations -- they narrow the persona's focus and prevent generic-reviewer voice. One per line."

Parse the response into a list. Must be non-empty (at least 1 entry). If empty, explain why blind spots matter and re-ask.


Step 4: Characteristic Objections (D-01, D-05 inline coaching)

Use AskUserQuestion:

Header: "Characteristic Objections" Question: "List at least 3 verbatim phrases this persona would actually say as objections. These are exact strings, not paraphrases -- they become few-shot voice anchors the persona reaches for during critique. One per line."

Parse the response into a list. Enforce minimum count >= 3. If fewer than 3, explain: "Characteristic objections are the strongest voice differentiation signal. Three is the minimum because two can be coincidence; three forces a pattern. Please provide at least 3." Re-ask.

Important: The D-05 cross-check against banned phrases happens AFTER Step 5 collects the banned_phrases. See the end of Step 5 for that logic.


Step 5: Banned Phrases (D-01, D-03, D-04 overlap coaching)

Use AskUserQuestion:

Header: "Banned Phrases" Question: "List at least 5 phrases this persona should NEVER use in findings. Start with the three baseline bans ('consider', 'think about', 'be aware of'), then add role-specific bans that would make this persona sound generic. One per line."

Parse the response into a list. Enforce minimum count >= 5. If fewer than 5, explain: "The scaffolder requires at least 5 banned phrases (3 baseline

  • 2 role-specific minimum). The validator's R6 rule requires >= 1, but the scaffolder sets a higher quality bar because role-specific bans are what differentiate your persona's voice." Re-ask.

Overlap Coaching (D-04)

After collecting banned phrases, compute overlap with all shipped persona sidecars. Use Bash tool with a multi-line python3 script:

python3 << 'OVERLAP_SCRIPT'
import yaml, os, glob, sys

# User's banned phrases (passed via environment or inline)
user_bans_raw = """USER_BANNED_PHRASES_HERE""".strip().split('\n')
user_bans = set(b.strip().lower() for b in user_bans_raw if b.strip())

# Baseline phrases excluded from overlap calculation
baseline = {'consider', 'think about', 'be aware of'}
user_role_specific = user_bans - baseline

if not user_role_specific:
    print("No role-specific banned phrases to compare (only baseline phrases provided).")
    sys.exit(0)

metadata_dir = "${CLAUDE_PLUGIN_ROOT}/persona-metadata"
overlaps = []

for f in sorted(glob.glob(os.path.join(metadata_dir, '*.yml'))):
    with open(f) as fh:
        data = yaml.safe_load(fh) or {}
    shipped_bans = set(b.lower() for b in data.get('banned_phrases', []))
    shipped_role_specific = shipped_bans - baseline

    if not shipped_role_specific:
        continue

    intersection = user_role_specific & shipped_role_specific
    denominator = min(len(user_role_specific), len(shipped_role_specific))
    pct = len(intersection) * 100 // denominator

    if pct > 30:
        slug = os.path.basename(f).replace('.yml', '')
        overlaps.append({
            'slug': slug,
            'pct': pct,
            'phrases': sorted(intersection)
        })

if overlaps:
    for o in overlaps:
        print(f"OVERLAP: {o['slug']} ({o['pct']}%) -- shared phrases: {', '.join(o['phrases'])}")
else:
    print("NO_OVERLAP: Your banned-phrase set is distinct from all shipped personas.")
OVERLAP_SCRIPT

Replace USER_BANNED_PHRASES_HERE with the actual newline-joined banned phrases the user provided.

If any overlap > 30% is detected, inform the user which phrases overlap with which persona, then use AskUserQuestion:

Header: "Banned-Phrase Overlap Detected" Question: "Your banned-phrase set has >30% overlap with [persona] (shared: [phrases]). Distinct banned phrases are what give your persona a unique voice. Would you like to diversify?" Options: ["Keep as-is", "Diversify (ask me for replacements)"]

If "Diversify", ask for replacement phrases and re-run the overlap check. If "Keep as-is", proceed.

D-05 Cross-Check: Objections vs Banned Phrases

Now that both characteristic_objections (from Step 4) and banned_phrases (from this step) are collected, cross-check each objection against the banned phrases. For each objection, check if it contains any banned phrase as a case-insensitive substring.

If any objection contains a banned phrase, flag it using AskUserQuestion:

Header: "Objection Uses Banned Phrase" Question: "Your objection '[objection text]' uses a phrase you banned ('[banned phrase]'). This means the persona's voice anchor contradicts its own banned-phrase discipline. Rephrase or keep?" Options: ["Rephrase (ask me for a replacement)", "Keep (I intentionally quote it)"]

If "Rephrase", ask for a replacement objection via AskUserQuestion. If "Keep", accept it -- the author intentionally quotes the phrase.


Step 6: Worked Examples (D-01)

Use AskUserQuestion:

Header: "Good Finding Examples" Question: "Provide 2 good-finding examples that show what this persona SHOULD produce. Each needs: target (specific line/heading), claim (in persona voice), evidence (verbatim 8+ char substring from artifact), ask (actionable remediation), severity (blocker|major|minor|nit), category (free text). Separate the two examples with a blank line."

Then use AskUserQuestion:

Header: "Bad Finding Example" Question: "Provide 1 bad-finding example showing what this persona REFUSES to ship. Same fields as above, plus a rejection reason explaining why this finding fails quality standards."

Enforce minimum counts: 2 good examples + 1 bad example. If fewer, explain the worked-example discipline (per persona-voice SKILL.md -- examples are few-shot voice anchors, not decoration) and re-ask.


Step 7: End Preview (D-02)

Assemble the complete persona file in all-in-one legacy format. All custom fields go in YAML frontmatter alongside the standard subagent fields. This format is what the validator expects when no sidecar exists.

The assembled file should look like:

---
name: <slug>
description: "<description generated from primary_concern>"
tools: [Read, Grep, Glob]
model: inherit
skills: [persona-voice, scorecard-schema]
tier: <tier>
primary_concern: "<primary_concern>"
blind_spots: [<blind_spots>]
characteristic_objections:
  - "<objection 1>"
  - "<objection 2>"
  - "<objection 3>"
banned_phrases:
  - "<phrase 1>"
  - "<phrase 2>"
tone_tags: [<inferred from responses>]
triggers: [<triggers if bench>]
---

<Value-system anchor paragraph>

## How you review

<Review instructions>

## Examples

### Good (what this persona ships)

<good examples>

### Bad (what this persona refuses to ship)

<bad example with rejection reason>

Show the complete assembled file to the user, then use AskUserQuestion:

Header: "Preview" Question: "Here is the complete persona file. Review it carefully. Ready to write?" Options: ["Write it", "Edit (go back to a specific step)", "Cancel"]

If "Edit", use AskUserQuestion to ask which step to revisit (0-6), then loop back to that step and re-collect from there forward. If "Cancel", stop execution. If "Write it", proceed to Step 8.


Step 8: Write to Workspace (D-06, D-07)

Create the workspace directory structure using Bash tool:

mkdir -p "${CLAUDE_PLUGIN_DATA}/create-persona-workspace/<slug>/agents"
mkdir -p "${CLAUDE_PLUGIN_DATA}/create-persona-workspace/<slug>/persona-metadata"

Write the all-in-one agent file (the full assembled content from the preview) to the workspace using the Write tool:

${CLAUDE_PLUGIN_DATA}/create-persona-workspace/<slug>/agents/<slug>.md

This is the legacy format with ALL custom fields in frontmatter. The validator uses its legacy fallback path to read custom fields directly from agent frontmatter when no sidecar exists at REPO_ROOT/persona-metadata/<slug>.yml.


Step 9: Validate (D-08, D-09, SCAF-03)

Run the validator on the written file using Bash tool:

"${CLAUDE_PLUGIN_ROOT}/scripts/validate-personas.sh" "${CLAUDE_PLUGIN_DATA}/create-persona-workspace/<slug>/agents/<slug>.md" --signals "${CLAUDE_PLUGIN_ROOT}/lib/signals.json"

Track validation attempts. Allow up to 3 retry loops.

If exit code 0: Validation passed. Proceed to Step 10.

If exit code 1: Parse the error output and map each R-code to the wizard step that collects the failing field (D-08 error code mapping):

R-codeError DescriptionGo Back To
R1YAML frontmatter is malformedStep 7 (Preview)
R2Invalid tier valueStep 1 (Tier)
R3primary_concern is emptyStep 2 (Primary Concern)
R4blind_spots is empty or missingStep 3 (Blind Spots)
R5Need at least 3 characteristic_objectionsStep 4 (Objections)
R6banned_phrases is emptyStep 5 (Banned Phrases)
R7Trigger ID not found in signals.jsonStep 1b (Triggers)
R8Core/chair personas must not have triggersStep 1 (Tier)

Translate the R-code error into a user-friendly explanation of what went wrong and which field needs correction. Then loop back to the identified step to re-collect the failing field.

After 3 failed validation attempts (D-09 bail logic): Write the file anyway with a warning:

"Persona written to workspace but did not pass validation after 3 attempts. Fix manually using: ./scripts/validate-personas.sh ${CLAUDE_PLUGIN_DATA}/create-persona-workspace/<slug>/agents/<slug>.md --signals lib/signals.json"

Then skip Step 10 (split) and proceed directly to Step 11 (install commands).


Step 10: Split into Agent + Sidecar

After validation passes, split the all-in-one file into the two-file format the production plugin expects:

Agent file (<workspace>/agents/<slug>.md) retains only standard subagent fields:

---
name: <slug>
description: "<description>"
tools: [Read, Grep, Glob]
model: inherit
skills: [persona-voice, scorecard-schema]
---

Plus the full markdown body (value-system paragraph, How you review, Examples sections).

Sidecar file (<workspace>/persona-metadata/<slug>.yml) gets all custom voice-kit fields:

tier: <tier>
primary_concern: "<primary_concern>"
blind_spots:
  - <blind_spot_1>
  - <blind_spot_2>
characteristic_objections:
  - "<objection_1>"
  - "<objection_2>"
  - "<objection_3>"
banned_phrases:
  - "<phrase_1>"
  - "<phrase_2>"
tone_tags: [<tags>]
triggers:
  - <trigger_1>   # only if bench tier

Write both files using the Write tool.


Step 11: Print Install Commands (D-06)

Print the exact commands the user needs to install the persona into their plugin directory:

cp "${CLAUDE_PLUGIN_DATA}/create-persona-workspace/<slug>/agents/<slug>.md" <your-plugin-dir>/agents/
cp "${CLAUDE_PLUGIN_DATA}/create-persona-workspace/<slug>/persona-metadata/<slug>.yml" <your-plugin-dir>/persona-metadata/

Then print the post-install checklist:

After copying:

  1. Run ./scripts/validate-personas.sh to verify the installed persona
  2. Run /reload-plugins to pick up the new persona
  3. Test with /devils-council:review on an artifact that matches your persona's triggers

Important Notes

  • No shell-injection: All shell operations in this wizard use the Bash tool explicitly. Do NOT use the exclamation-backtick shell-injection pattern anywhere in this skill. Shell-inject is reserved for deterministic pre-prompt data injection in the review command; the scaffolder is an interactive wizard that uses tool calls.
  • Workspace isolation: All files are written to ${CLAUDE_PLUGIN_DATA}/create-persona-workspace/<slug>/, not directly into the plugin's agents/ or persona-metadata/ directories. This ensures the user reviews and copies the files intentionally.
  • Legacy format for validation: The all-in-one file written in Step 8 puts all custom fields in YAML frontmatter. This triggers the validator's legacy fallback path (lines 426-439 of validate-personas.sh) which reads custom fields from agent frontmatter when no sidecar exists at REPO_ROOT/persona-metadata/<slug>.yml.
  • Quality bar vs validator bar: The scaffolder enforces stricter minimums than the validator. Specifically:
    • Scaffolder requires >= 5 banned phrases (validator R6 requires >= 1)
    • Scaffolder requires 2 good + 1 bad example (validator W2 only warns on missing ## Examples heading)
    • Scaffolder checks >30% banned-phrase overlap (validator does not)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.