Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .agents/skills/powershell-new-module/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,9 @@ Read these before writing files, unless they are already loaded:
if the module defines a class. Do not create empty folders for things the module does not have.
3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the
result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions
by name. Take `Author` and the project links from the user or the repository; leave out what you do
not know.
by name. Take `Author`, `CompanyName`, and the copyright holder from
`.github/powershell-attribution.md` when the project has one (DOC-18), and the project links from
the user or the repository; leave out what you do not know.
4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that
matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and
`Public` dot-sourced in that order, failing the import if a file fails to load.
Expand Down
5 changes: 3 additions & 2 deletions .claude/skills/powershell-new-module/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,9 @@ Read these before writing files, unless they are already loaded:
if the module defines a class. Do not create empty folders for things the module does not have.
3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the
result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions
by name. Take `Author` and the project links from the user or the repository; leave out what you do
not know.
by name. Take `Author`, `CompanyName`, and the copyright holder from
`.github/powershell-attribution.md` when the project has one (DOC-18), and the project links from
the user or the repository; leave out what you do not know.
4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that
matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and
`Public` dot-sourced in that order, failing the import if a file fails to load.
Expand Down
2 changes: 1 addition & 1 deletion .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ counts as much as one listed here.
- **DOC-05** Help MUST describe what the code does. Performance figures, compliance claims, and
behaviour that the code does not have MUST NOT be invented. If a fact is not known, leave it out.
- **DOC-07** Help MUST NOT contain a version number, a date, or a change history. An author name is
added only when the user supplies one.
added only when the user supplies one or `.github/powershell-attribution.md` lists one (DOC-18).

## Function template

Expand Down
42 changes: 40 additions & 2 deletions .github/instructions/powershell-help.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ in `.github/instructions/powershell-platyps.instructions.md`.
- **DOC-06** `.OUTPUTS` names the same type as `[OutputType()]`. `.INPUTS` names the type that can be
piped in, or says `None`.
- **DOC-07** Help MUST NOT contain a version number, a date, or a change history. An author name is
added only when the user supplies one.
added only when the user supplies one or `.github/powershell-attribution.md` lists one (DOC-18).
- **DOC-08** Each `.EXAMPLE` starts with a command that runs as written, followed by a blank line and
a sentence saying what it does. An explanatory line placed before that blank line MUST start with
`#` and MUST NOT be the first line.
Expand All @@ -55,11 +55,16 @@ in `.github/instructions/powershell-platyps.instructions.md`.
A `DURATION:` line is added only for a time that was measured.
- **DOC-15** `.NOTES` holds security considerations (permissions and data handling), performance
characteristics, and known limitations with their workarounds. It holds the author's name, blog,
and LinkedIn address only when the user supplies them (DOC-07).
LinkedIn address, and other profiles only when the user supplies them or the project's
attribution file lists them (DOC-07, DOC-18).
- **DOC-16** List references with one `.LINK` keyword for each: related commands, the online
documentation of the command, and Microsoft documentation.
- **DOC-17** Where they have been measured, help documents typical execution time, memory use, and
scalability. It states no performance figure that was not measured (DOC-05).
- **DOC-18** When the project has `.github/powershell-attribution.md`, take the author details from
it: the `AUTHOR:` lines of `.NOTES` in new help, and the manifest keys of MOD-03. Use each line
that has a value, with its label, in the file's order. A line without a value is left out and
MUST NOT be filled in from anywhere else. Existing help is not changed only to add the details.

### Comments

Expand Down Expand Up @@ -219,6 +224,39 @@ Test-Connection
Tested on PowerShell 7.6 and Windows PowerShell 5.1: `Get-Help` keeps these lines and the blank
lines between them, and lists each `.LINK` as one related link.

**DOC-18.** The attribution file is a list of labelled lines that the project fills in:

```markdown
- Author: Alex Example
- Company:
- Copyright holder: Alex Example
- Blog: https://blog.example.com
- LinkedIn: https://www.linkedin.com/in/alex-example
```

New help then ends its `.NOTES` with the lines that have a value. `Company` is empty, so it is left
out; `Copyright holder` belongs to the manifest only:

```powershell
<#
.NOTES
KNOWN LIMITATIONS:
- Computers must be reachable through WinRM.

AUTHOR:
- Author: Alex Example
- Blog: https://blog.example.com
- LinkedIn: https://www.linkedin.com/in/alex-example
#>
```

Tested on PowerShell 7.6 and Windows PowerShell 5.1: `Get-Help -Full` shows the `AUTHOR:` block as
written, after the other notes.

The standards installer creates the file when it is missing and never changes it afterwards. It
starts from the profile of the project's GitHub owner when the standards repository has one, and
from an empty template otherwise.

**DOC-20.**

```powershell
Expand Down
5 changes: 5 additions & 0 deletions .github/instructions/powershell-modules.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,11 @@ GUID, and it never changes afterwards. Set `Author`, `CompanyName`, `Copyright`,
`Tags` from what the user or the repository provides; do not invent them. Write the copyright year
as a literal: `'(c) $(Get-Date -Format yyyy) ...'` stays that literal text too.

When the project has `.github/powershell-attribution.md` (DOC-18), `Author` is its `Author` line,
`CompanyName` its `Company` line, and the holder in `Copyright` its `Copyright holder` line. Leave
out `CompanyName` when that line is empty, and name the author as the holder when the
`Copyright holder` line is empty.

Leave out `HelpInfoURI` unless the project publishes updatable help at that address: `Update-Help`
reports an error against a `HelpInfoURI` that has no `HelpInfo.xml` behind it. Shipping compiled
help in `en-US/` does not need the key. Leave out `IconUri` when there is no icon (MOD-13).
Expand Down
18 changes: 18 additions & 0 deletions .github/powershell-attribution.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Attribution

Coding agents that follow the PowerShell standards read this file when they write an author into
new code: the `.NOTES` of comment-based help and of help Markdown, and the `Author`, `CompanyName`,
and `Copyright` keys of a new module manifest (DOC-18). Fill in the values that should appear. A
line with no value is left out, and an agent does not invent one.

The standards installer creates this file when it is missing and never changes it afterwards, so
these details belong to this repository.

- Author: Jeffrey Stuhr
- Company:
- Copyright holder: Jeffrey Stuhr
- Blog: https://techbyjeff.net
- LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/
- Bluesky: https://bsky.app/profile/techbyjeff.net

Add a line in the same form for another profile, for example `- GitHub: https://github.com/<name>`.
5 changes: 3 additions & 2 deletions .github/skills/powershell-new-module/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,9 @@ Read these before writing files, unless they are already loaded:
if the module defines a class. Do not create empty folders for things the module does not have.
3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the
result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions
by name. Take `Author` and the project links from the user or the repository; leave out what you do
not know.
by name. Take `Author`, `CompanyName`, and the copyright holder from
`.github/powershell-attribution.md` when the project has one (DOC-18), and the project links from
the user or the repository; leave out what you do not know.
4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that
matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and
`Public` dot-sourced in that order, failing the import if a file fails to load.
Expand Down