{"id":"ca9cd5e6-0837-4fd2-9346-5cc1a174cb52","shortId":"8SZVkZ","kind":"skill","title":"story-craftsman","tagline":"Professional User Story and documentation system construction. Assists in writing high-quality User Story documents through guided interviews to uncover requirements context and acceptance criteria, and places documents precisely in the standardized docs directory structure. Trig","description":"# Story Craftsman\n\nThis skill embodies the \"Everything is Code\" engineering philosophy, helping you produce high-quality user stories and their supporting documentation alongside your MR submissions.\n\nFor the detailed example template, see [examples/TEMPLATE-UserStory.md](examples/TEMPLATE-UserStory.md).\n\n---\n\n## Rules\n\n1. **Never fabricate information**: When information is insufficient, obtain context through guided interviews rather than filling in details yourself\n2. **Architecture-aware placement**: Analyze file paths or `git status` to determine the relevant module and place documents in the corresponding `docs/04-user-stories/` directory\n3. **Testable acceptance criteria**: Each AC must be a verifiable, checkable condition (Given/When/Then or clear checkbox)\n4. **Consolidate questions**: During interviews, combine all missing dimensions into a single round of questions to avoid multi-round fragmented asking that causes user fatigue\n5. **Path-first inference**: First attempt to infer the target sub-module from context; only ask the user when uncertain\n\n---\n\n## Execution Flow\n\n### Feature A: Generate User Story\n\n### Trigger Conditions\n\nUser requests \"help me write a User Story,\" \"describe this feature,\" \"generate user story,\" etc.\n\n### Step 1: Assess Information Sufficiency\n\nAfter receiving a request, check whether the following three elements are present:\n\n| Element | Meaning | Sufficiency Criteria |\n|------|------|--------------------|\n| **Background (Why)** | Current pain points, impact scope | Can articulate \"who is affected in what scenario\" |\n| **Goals (What)** | Verifiable success metrics | Can articulate \"what can be quantified after completion\" |\n| **Acceptance Criteria (AC)** | Key boundary scenarios | At least 2 checkable conditions are listed |\n\n**If information is insufficient, execute Step 2 (interview); if sufficient, proceed directly to Step 3 (generation).**\n\n### Step 2: Guided Interview Protocol\n\nTake on the dual role of \"detective\" and \"poet,\" asking all missing dimension questions in a single round (avoiding multi-round fragmented questions):\n\n```\nTo generate a professional user story, I need you to confirm the following (keep it brief, 1-3 sentences per item):\n\n1. **Background/Pain point**: [specific missing background question]\n2. **Goal**: [specific missing goal question]\n3. **Acceptance criteria**: [specific missing AC question]\n\nYou can describe briefly — I will handle converting it into the standard professional document format.\n```\n\n### Step 3: Generate User Story File\n\nStrictly follow the structure from [TEMPLATE-UserStory.md](examples/TEMPLATE-UserStory.md) to generate the file.\n\n**File naming convention**: `{feature-name}.md` (lowercase kebab-case)\n\n**Placement path**: `{submodule_root}/docs/04-user-stories/{feature-name}.md`\n\nIf the target directory does not exist, first execute Feature B or prompt the user.\n\n---\n\n### Feature B: Initialize Standard Docs Structure\n\n### Trigger Conditions\n\nUser explicitly requests \"create docs structure,\" \"initialize docs,\" etc.\n\n### Standard Directory Structure\n\n```\ndocs/\n├── 01-product-research/    # Product research and competitive analysis\n├── 02-system-design/       # System design and architecture decisions\n├── 03-detailed-design/     # Detailed design documents\n├── 04-user-stories/        # User Stories\n└── 05-user-guide/          # User manuals and operation guides\n```\n\n### Execution Steps\n\n1. Confirm the target root directory (ask the user or infer from context)\n2. Create the 5 subdirectories listed above under the target root\n3. Create a `.gitkeep` file in each subdirectory to ensure Git tracks empty directories\n4. Generate `AGENTS.md` in the `docs/` root directory describing each directory's purpose\n\n### Generated `docs/AGENTS.md` Content Template\n\n```markdown\n# docs/\n\nThis directory is the project documentation root, organized by R&D lifecycle stages.\n\n## Directory Structure\n\n- `01-product-research/`: Product research, competitive analysis, market insights\n- `02-system-design/`: System architecture design, technology selection, ADR (Architecture Decision Records)\n- `03-detailed-design/`: Module detailed design, interface specifications, data structures\n- `04-user-stories/`: User Story files, naming convention: `{feature-name}.md`\n- `05-user-guide/`: End-user operation manuals and usage instructions\n\n## Maintenance Conventions\n\n- User stories are created as individual `.md` files per feature module\n- This file should be updated after architectural/directory-level changes\n```\n\n---\n\n### Sub-Module Identification Logic\n\nAnalyze code changes or user descriptions to determine the target sub-module in the following order:\n\n1. **Infer from file paths**: Top-level directory of changed files (e.g., `device-cloud-server/`, `frontend/`)\n2. **Infer from git status**: Path prefixes in `git status` output\n3. **Ask when uncertain**: If changes span multiple modules or paths are unclear, **must ask the user**\n\n---\n\n## Examples\n\n### Bad\n\n```markdown\n## User Story: Alarm Filtering Feature\n\n**As** a system administrator, **I want** to filter alarms, **so that** I can reduce distractions.\n\n**Acceptance Criteria**:\n- [ ] System supports filtering functionality\n- [ ] Filtered alarms are not displayed after filtering\n```\n\nProblem: Missing background, ACs are too vague, unable to verify \"what conditions trigger filtering.\"\n\n### Good\n\n```markdown\n## User Story: Rule-Based Alarm Silence Filtering\n\n**Background**: The monitoring system generates 500+ heartbeat probe alarms daily, causing\noperator alert fatigue. Real fault alarms get buried, and average response time has increased\nfrom 2 minutes to 15 minutes.\n\n**As** an operations engineer, **I want** to configure alarm silence rules (by device type + alarm type combination),\n**so that** known non-fault alarms are suppressed and real fault alarm response time returns to under 2 minutes.\n\n**Acceptance Criteria**:\n- [ ] Given a configured silence rule \"device type=heartbeat probe AND alarm type=connection timeout,\"\n      When such an alarm fires, Then the Grafana dashboard does not display it and the audit log records \"silenced\"\n- [ ] Given the silence rule configuration interface, When the admin saves a rule,\n      Then the rule takes effect within 30 seconds without requiring a service restart\n- [ ] Given an alarm matches both a silence rule and an escalation rule simultaneously,\n      When the alarm fires, Then the silence rule takes priority, but the conflict is noted in the audit log\n```\n\n---\n\n## Exemptions\n\n| Scenario | Condition |\n|------|------|\n| Technical refactoring MR | No visible user-facing functionality change — may simplify to a brief technical note |\n| Pure bug fix | Reference the corresponding Issue directly — full User Story format not required |\n\nExemption method: `/override skill=story-craftsman reason=\"pure technical refactoring, no user-visible functionality change\"`\n\n---\n\n## References\n\n- [User Story Template](examples/TEMPLATE-UserStory.md)\n- [INVEST Principles](https://en.wikipedia.org/wiki/INVEST_(mnemonic)) — Independent, Negotiable, Valuable, Estimable, Small, Testable\n- [Given-When-Then Acceptance Criteria Writing](https://martinfowler.com/bliki/GivenWhenThen.html)","tags":["story","craftsman","enterprise","harness","engineering","addxai","agent-skills","ai-agent","ai-engineering","claude-code","code-review","cursor"],"capabilities":["skill","source-addxai","skill-story-craftsman","topic-agent-skills","topic-ai-agent","topic-ai-engineering","topic-claude-code","topic-code-review","topic-cursor","topic-devops","topic-enterprise","topic-sre","topic-windsurf"],"categories":["enterprise-harness-engineering"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/addxai/enterprise-harness-engineering/story-craftsman","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add addxai/enterprise-harness-engineering","source_repo":"https://github.com/addxai/enterprise-harness-engineering","install_from":"skills.sh"}},"qualityScore":"0.458","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 16 github stars · SKILL.md body (7,230 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T01:02:12.940Z","embedding":null,"createdAt":"2026-04-21T19:04:02.430Z","updatedAt":"2026-04-22T01:02:12.940Z","lastSeenAt":"2026-04-22T01:02:12.940Z","tsv":"'-3':332 '/bliki/givenwhenthen.html)':1002 '/docs/04-user-stories':403 '/override':962 '/wiki/invest_(mnemonic))':986 '01':444,558 '02':453,568 '03':462,581 '04':469,592 '05':475,605 '1':77,209,331,336,486,660 '15':795 '2':96,265,276,287,343,499,678,792,832 '3':120,284,349,372,510,689 '30':887 '4':136,524 '5':162,502 '500':771 'ac':125,259,354,745 'accept':28,122,257,350,729,834,997 'admin':877 'administr':717 'adr':577 'affect':240 'agents.md':526 'alarm':711,722,736,763,774,782,805,811,820,826,846,853,896,909 'alert':778 'alongsid':64 'analysi':452,565 'analyz':101,643 'architectur':98,460,573,578 'architectural/directory-level':636 'architecture-awar':97 'articul':237,250 'ask':157,179,300,492,690,703 'assess':210 'assist':11 'attempt':168 'audit':865,924 'averag':786 'avoid':152,309 'awar':99 'b':418,424 'background':229,341,744,766 'background/pain':337 'bad':707 'base':762 'boundari':261 'brief':330,943 'briefli':359 'bug':947 'buri':784 'case':398 'caus':159,776 'chang':637,645,670,694,938,976 'check':217 'checkabl':130,266 'checkbox':135 'clear':134 'cloud':675 'code':49,644 'combin':141,813 'competit':451,564 'complet':256 'condit':131,192,267,430,753,928 'configur':804,838,873 'confirm':325,487 'conflict':919 'connect':848 'consolid':137 'construct':10 'content':539 'context':26,86,177,498 'convent':390,600,618 'convert':363 'correspond':117,951 'craftsman':3,42,966 'creat':434,500,511,622 'criteria':29,123,228,258,351,730,835,998 'current':231 'd':553 'daili':775 'dashboard':858 'data':590 'decis':461,579 'describ':201,358,532 'descript':648 'design':456,458,465,467,571,574,584,587 'detail':70,94,464,466,583,586 'detailed-design':463,582 'detect':297 'determin':108,650 'devic':674,809,841 'device-cloud-serv':673 'dimens':144,303 'direct':281,953 'directori':38,119,411,441,491,523,531,534,544,556,668 'display':739,861 'distract':728 'doc':37,427,435,438,443,529,542 'docs/04-user-stories':118 'docs/agents.md':538 'document':8,19,32,63,114,369,468,548 'dual':294 'e.g':672 'effect':885 'element':222,225 'embodi':45 'empti':522 'en.wikipedia.org':985 'en.wikipedia.org/wiki/invest_(mnemonic))':984 'end':610 'end-us':609 'engin':50,800 'ensur':519 'escal':904 'estim':990 'etc':207,439 'everyth':47 'exampl':71,706 'examples/template-userstory.md':74,75,383,981 'execut':184,274,416,484 'exempt':926,960 'exist':414 'explicit':432 'fabric':79 'face':936 'fatigu':161,779 'fault':781,819,825 'featur':186,203,392,405,417,423,602,628,713 'feature-nam':391,404,601 'file':102,376,387,388,514,598,626,631,663,671 'fill':92 'filter':712,721,733,735,741,755,765 'fire':854,910 'first':165,167,415 'fix':948 'flow':185 'follow':220,327,378,658 'format':370,957 'fragment':156,313 'frontend':677 'full':954 'function':734,937,975 'generat':188,204,285,316,373,385,525,537,770 'get':783 'git':105,520,681,686 'gitkeep':513 'given':836,869,894,994 'given-when-then':993 'given/when/then':132 'goal':244,344,347 'good':756 'grafana':857 'guid':21,88,288,478,483,608 'handl':362 'heartbeat':772,843 'help':52,195 'high':15,56 'high-qual':14,55 'identif':641 'impact':234 'increas':790 'independ':987 'individu':624 'infer':166,170,496,661,679 'inform':80,82,211,271 'initi':425,437 'insight':567 'instruct':616 'insuffici':84,273 'interfac':588,874 'interview':22,89,140,277,289 'invest':982 'issu':952 'item':335 'kebab':397 'kebab-cas':396 'keep':328 'key':260 'known':816 'least':264 'level':667 'lifecycl':554 'list':269,504 'log':866,925 'logic':642 'lowercas':395 'mainten':617 'manual':480,613 'markdown':541,708,757 'market':566 'martinfowler.com':1001 'martinfowler.com/bliki/givenwhenthen.html)':1000 'match':897 'may':939 'md':394,407,604,625 'mean':226 'method':961 'metric':248 'minut':793,796,833 'miss':143,302,340,346,353,743 'modul':111,175,585,629,640,655,697 'monitor':768 'mr':66,931 'multi':154,311 'multi-round':153,310 'multipl':696 'must':126,702 'name':389,393,406,599,603 'need':322 'negoti':988 'never':78 'non':818 'non-fault':817 'note':921,945 'obtain':85 'oper':482,612,777,799 'order':659 'organ':550 'output':688 'pain':232 'path':103,164,400,664,683,699 'path-first':163 'per':334,627 'philosophi':51 'place':31,113 'placement':100,399 'poet':299 'point':233,338 'precis':33 'prefix':684 'present':224 'principl':983 'prioriti':916 'probe':773,844 'problem':742 'proceed':280 'produc':54 'product':446,448,560,562 'product-research':445,559 'profession':4,318,368 'project':547 'prompt':420 'protocol':290 'pure':946,968 'purpos':536 'qualiti':16,57 'quantifi':254 'question':138,150,304,314,342,348,355 'r':552 'rather':90 'real':780,824 'reason':967 'receiv':214 'record':580,867 'reduc':727 'refactor':930,970 'refer':949,977 'relev':110 'request':194,216,433 'requir':25,890,959 'research':447,449,561,563 'respons':787,827 'restart':893 'return':829 'role':295 'root':402,490,509,530,549 'round':148,155,308,312 'rule':76,761,807,840,872,880,883,901,905,914 'rule-bas':760 'save':878 'scenario':243,262,927 'scope':235 'second':888 'see':73 'select':576 'sentenc':333 'server':676 'servic':892 'silenc':764,806,839,868,871,900,913 'simplifi':940 'simultan':906 'singl':147,307 'skill':44,963 'skill-story-craftsman' 'small':991 'source-addxai' 'span':695 'specif':339,345,352,589 'stage':555 'standard':36,367,426,440 'status':106,682,687 'step':208,275,283,286,371,485 'stori':2,6,18,41,59,190,200,206,320,375,472,474,595,597,620,710,759,956,965,979 'story-craftsman':1,964 'strict':377 'structur':39,380,428,436,442,557,591 'sub':174,639,654 'sub-modul':173,638,653 'subdirectori':503,517 'submiss':67 'submodul':401 'success':247 'suffici':212,227,279 'support':62,732 'suppress':822 'system':9,455,457,570,572,716,731,769 'system-design':454,569 'take':291,884,915 'target':172,410,489,508,652 'technic':929,944,969 'technolog':575 'templat':72,540,980 'template-userstory.md':382 'testabl':121,992 'three':221 'time':788,828 'timeout':849 'top':666 'top-level':665 'topic-agent-skills' 'topic-ai-agent' 'topic-ai-engineering' 'topic-claude-code' 'topic-code-review' 'topic-cursor' 'topic-devops' 'topic-enterprise' 'topic-sre' 'topic-windsurf' 'track':521 'trig':40 'trigger':191,429,754 'type':810,812,842,847 'unabl':749 'uncertain':183,692 'unclear':701 'uncov':24 'updat':634 'usag':615 'user':5,17,58,160,181,189,193,199,205,319,374,422,431,471,473,477,479,494,594,596,607,611,619,647,705,709,758,935,955,973,978 'user-fac':934 'user-guid':476,606 'user-stori':470,593 'user-vis':972 'vagu':748 'valuabl':989 'verifi':129,246,751 'visibl':933,974 'want':719,802 'whether':218 'within':886 'without':889 'write':13,197,999","prices":[{"id":"dd48b92b-118e-46f7-9a8e-ed335169ead7","listingId":"ca9cd5e6-0837-4fd2-9346-5cc1a174cb52","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"addxai","category":"enterprise-harness-engineering","install_from":"skills.sh"},"createdAt":"2026-04-21T19:04:02.430Z"}],"sources":[{"listingId":"ca9cd5e6-0837-4fd2-9346-5cc1a174cb52","source":"github","sourceId":"addxai/enterprise-harness-engineering/story-craftsman","sourceUrl":"https://github.com/addxai/enterprise-harness-engineering/tree/main/skills/story-craftsman","isPrimary":false,"firstSeenAt":"2026-04-21T19:04:02.430Z","lastSeenAt":"2026-04-22T01:02:12.940Z"}],"details":{"listingId":"ca9cd5e6-0837-4fd2-9346-5cc1a174cb52","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"addxai","slug":"story-craftsman","github":{"repo":"addxai/enterprise-harness-engineering","stars":16,"topics":["agent-skills","ai-agent","ai-engineering","claude-code","code-review","cursor","devops","enterprise","sre","windsurf"],"license":"apache-2.0","html_url":"https://github.com/addxai/enterprise-harness-engineering","pushed_at":"2026-04-17T08:57:37Z","description":"Enterprise-grade AI Agent Skills for software development, DevOps, SRE, security, and product teams. Compatible with Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot, and 30+ AI coding agents.","skill_md_sha":"17b431cf66251c55b545efe2595e46edd96cc39f","skill_md_path":"skills/story-craftsman/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/addxai/enterprise-harness-engineering/tree/main/skills/story-craftsman"},"layout":"multi","source":"github","category":"enterprise-harness-engineering","frontmatter":{"name":"story-craftsman","description":"Professional User Story and documentation system construction. Assists in writing high-quality User Story documents through guided interviews to uncover requirements context and acceptance criteria, and places documents precisely in the standardized docs directory structure. Triggers when the user requests writing User Stories, describing feature requirements, or initializing project documentation structure."},"skills_sh_url":"https://skills.sh/addxai/enterprise-harness-engineering/story-craftsman"},"updatedAt":"2026-04-22T01:02:12.940Z"}}